canvodpy 0.2.0__tar.gz

canvodpy-0.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.3
+Name: canvodpy
+Version: 0.2.0
+Summary: Umbrella package for canVOD ecosystem
+Keywords: GNSS,VOD,vegetation,remote sensing,geodesy
+Author: Nicolas François Bader
+Author-email: Nicolas François Bader <nicolas.bader@tuwien.ac.at>
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Dist: canvod-readers
+Requires-Dist: canvod-auxiliary
+Requires-Dist: canvod-grids
+Requires-Dist: canvod-store
+Requires-Dist: canvod-store-metadata
+Requires-Dist: canvod-utils
+Requires-Dist: canvod-viz
+Requires-Dist: canvod-vod
+Requires-Dist: marimo>=0.9.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: pint>=0.20
+Requires-Dist: structlog>=23.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tqdm>=4.65
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: natsort>=8.0.0
+Requires-Dist: dask[distributed]>=2026.1.1
+Requires-Dist: mystmd>=1.8.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: howfairis>=0.13.0
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: palettable>=3.3.3
+Requires-Dist: altair>=6.0.0
+Requires-Dist: tabulate>=0.10.0
+Requires-Dist: sqlglot>=29.0.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# canvodpy
+
+Umbrella package for unified GNSS VOD analysis.
+
+## Overview
+
+`canvodpy` is the unified entry point for the canVOD ecosystem. It provides
+three levels of API:
+
+- **Level 1:** One-line convenience functions (fastest path to results)
+- **Level 2:** Object-oriented classes (structured workflows)
+- **Level 3:** Low-level components (full control)
+
+## Installation
+
+```bash
+# Installs canvodpy + all 7 sub-packages
+uv pip install canvodpy
+```
+
+## Quick Start
+
+### Level 1: Simple (One-Liners)
+
+```python
+from canvodpy import process_date, calculate_vod
+
+# Process one day of data
+data = process_date("Rosalia", "2025001")
+
+# Calculate VOD
+vod = calculate_vod("Rosalia", "canopy_01", "reference_01", "2025001")
+```
+
+### Level 2: Object-Oriented (More Control)
+
+```python
+from canvodpy import Site, Pipeline
+
+# Create site and pipeline
+site = Site("Rosalia")
+pipeline = site.pipeline(aux_agency="ESA", n_workers=8)
+
+# Process data
+data = pipeline.process_date("2025001")
+
+# Or process multiple days
+for date, datasets in pipeline.process_range("2025001", "2025007"):
+    print(f"Processed {date}")
+```
+
+### Level 3: Low-Level (Full Control)
+
+```python
+from canvod.readers import Rnxv3Obs
+from canvod.auxiliary import Sp3File, ClkFile
+from canvod.store import GnssResearchSite
+from canvodpy.orchestrator import PipelineOrchestrator
+
+# Direct access to all internals
+site = GnssResearchSite("Rosalia")
+orchestrator = PipelineOrchestrator(site, n_max_workers=12)
+# ... custom processing ...
+```
+
+## Included Packages
+
+Installing canvodpy provides access to all 7 packages:
+
+- **canvod.readers** -- RINEX file parsing (v3.04)
+- **canvod.auxiliary** -- Auxiliary data (SP3, CLK) handling
+- **canvod.grids** -- Hemisphere grid structures
+- **canvod.store** -- Icechunk data storage
+- **canvod.vod** -- VOD calculation algorithms
+- **canvod.viz** -- 2D/3D visualization
+- **canvod.utils** -- Shared utilities
+
+## Platform Support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | Full support | Recommended |
+| macOS | Full support | Fully tested |
+| Windows | WSL only | Native not supported (reserved `aux` name) |
+
+## Configuration
+
+Create a `.env` file in repository root (optional for NASA products):
+
+```bash
+# NASA CDDIS credentials (optional)
+CDDIS_MAIL=your.email@example.com
+
+# Data root directory (required)
+GNSS_ROOT_DIR=/path/to/your/data
+```
+
+Without `.env`, canvodpy operates in ESA-only mode (COD, GFZ, ESA products).
+
+## Documentation
+
+[Centralized documentation](../docs/index.md)
+
+## Development
+
+See the [main repository README](../README.md) for workspace development setup.
+
+## License
+
+Apache License 2.0

canvodpy-0.2.0/README.md

@@ -0,0 +1,110 @@
+# canvodpy
+
+Umbrella package for unified GNSS VOD analysis.
+
+## Overview
+
+`canvodpy` is the unified entry point for the canVOD ecosystem. It provides
+three levels of API:
+
+- **Level 1:** One-line convenience functions (fastest path to results)
+- **Level 2:** Object-oriented classes (structured workflows)
+- **Level 3:** Low-level components (full control)
+
+## Installation
+
+```bash
+# Installs canvodpy + all 7 sub-packages
+uv pip install canvodpy
+```
+
+## Quick Start
+
+### Level 1: Simple (One-Liners)
+
+```python
+from canvodpy import process_date, calculate_vod
+
+# Process one day of data
+data = process_date("Rosalia", "2025001")
+
+# Calculate VOD
+vod = calculate_vod("Rosalia", "canopy_01", "reference_01", "2025001")
+```
+
+### Level 2: Object-Oriented (More Control)
+
+```python
+from canvodpy import Site, Pipeline
+
+# Create site and pipeline
+site = Site("Rosalia")
+pipeline = site.pipeline(aux_agency="ESA", n_workers=8)
+
+# Process data
+data = pipeline.process_date("2025001")
+
+# Or process multiple days
+for date, datasets in pipeline.process_range("2025001", "2025007"):
+    print(f"Processed {date}")
+```
+
+### Level 3: Low-Level (Full Control)
+
+```python
+from canvod.readers import Rnxv3Obs
+from canvod.auxiliary import Sp3File, ClkFile
+from canvod.store import GnssResearchSite
+from canvodpy.orchestrator import PipelineOrchestrator
+
+# Direct access to all internals
+site = GnssResearchSite("Rosalia")
+orchestrator = PipelineOrchestrator(site, n_max_workers=12)
+# ... custom processing ...
+```
+
+## Included Packages
+
+Installing canvodpy provides access to all 7 packages:
+
+- **canvod.readers** -- RINEX file parsing (v3.04)
+- **canvod.auxiliary** -- Auxiliary data (SP3, CLK) handling
+- **canvod.grids** -- Hemisphere grid structures
+- **canvod.store** -- Icechunk data storage
+- **canvod.vod** -- VOD calculation algorithms
+- **canvod.viz** -- 2D/3D visualization
+- **canvod.utils** -- Shared utilities
+
+## Platform Support
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | Full support | Recommended |
+| macOS | Full support | Fully tested |
+| Windows | WSL only | Native not supported (reserved `aux` name) |
+
+## Configuration
+
+Create a `.env` file in repository root (optional for NASA products):
+
+```bash
+# NASA CDDIS credentials (optional)
+CDDIS_MAIL=your.email@example.com
+
+# Data root directory (required)
+GNSS_ROOT_DIR=/path/to/your/data
+```
+
+Without `.env`, canvodpy operates in ESA-only mode (COD, GFZ, ESA products).
+
+## Documentation
+
+[Centralized documentation](../docs/index.md)
+
+## Development
+
+See the [main repository README](../README.md) for workspace development setup.
+
+## License
+
+Apache License 2.0

canvodpy-0.2.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "canvodpy"
+version = "0.2.0"
+description = "Umbrella package for canVOD ecosystem"
+readme = "README.md"
+requires-python = ">=3.14"
+authors = [
+    { name = "Nicolas François Bader", email = "nicolas.bader@tuwien.ac.at" },
+]
+keywords = ["GNSS", "VOD", "vegetation", "remote sensing", "geodesy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+
+# Core dependencies - sub-packages from workspace
+dependencies = [
+    "canvod-readers",
+    "canvod-auxiliary",
+    "canvod-grids",
+    "canvod-store",
+    "canvod-store-metadata",
+    "canvod-utils",
+    "canvod-viz",
+    "canvod-vod",
+    "marimo>=0.9.0",
+    "matplotlib>=3.8.0",
+    "pint>=0.20",
+    "structlog>=23.0",
+    "pydantic>=2.0",
+    "tqdm>=4.65",
+    "tomli>=2.0.0",
+    "natsort>=8.0.0",
+    "dask[distributed]>=2026.1.1",
+    "mystmd>=1.8.0",
+    "docker>=7.1.0",
+    "howfairis>=0.13.0",
+    "pyarrow>=23.0.1",
+    "palettable>=3.3.3",
+    "altair>=6.0.0",
+    "tabulate>=0.10.0",
+    "sqlglot>=29.0.1",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "ruff>=0.14",
+    "ty>=0.0.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"
+
+# Workspace package sources
+# This tells uv where to find the local packages
+[tool.uv.sources]
+canvod-readers = { workspace = true }
+canvod-auxiliary = { workspace = true }
+canvod-grids = { workspace = true }
+canvod-store = { workspace = true }
+canvod-store-metadata = { workspace = true }
+canvod-utils = { workspace = true }
+canvod-viz = { workspace = true }
+canvod-vod = { workspace = true }
+
+[tool.ty]
+extend-exclude = [
+    "**/docs/*.ipynb",
+    "**/docs/notebooks/*.py",
+]

canvodpy-0.2.0/src/canvodpy/__init__.py

@@ -0,0 +1,276 @@
+"""canvodpy: GNSS Vegetation Optical Depth Analysis.
+
+A modern Python package for processing GNSS data and calculating
+vegetation optical depth (VOD) using the tau-omega model.
+
+Quick Start
+-----------
+Three levels of API to match your needs:
+
+**Level 1: Simple (one-liners)**
+    >>> from canvodpy import process_date, calculate_vod
+    >>> data = process_date("Rosalia", "2025001")
+    >>> vod = calculate_vod("Rosalia", "canopy_01", "reference_01", "2025001")
+
+**Level 2: Object-oriented (more control)**
+    >>> from canvodpy import Site, Pipeline
+    >>> site = Site("Rosalia")
+    >>> pipeline = site.pipeline()
+    >>> data = pipeline.process_date("2025001")
+    >>> vod = pipeline.calculate_vod("canopy_01", "reference_01", "2025001")
+
+**Level 3: Low-level (full control)**
+    >>> from canvod.store import GnssResearchSite
+    >>> from canvod.vod import VODCalculator
+    >>> # Direct access to all internals
+
+Community Extensions
+--------------------
+Extend canvodpy with custom components using factories:
+
+    >>> from canvodpy import VODFactory
+    >>> from my_package import CustomCalculator
+    >>> VODFactory.register("custom", CustomCalculator)
+    >>> calc = VODFactory.create("custom", **params)
+
+Package Structure
+-----------------
+- canvod.readers - RINEX file parsing
+- canvod.auxiliary - Auxiliary data (ephemeris, clocks)
+- canvod.grids - Hemisphere grid structures
+- canvod.vod - VOD calculation algorithms
+- canvod.viz - 2D/3D visualization
+- canvod.store - Icechunk data storage
+
+Configuration
+-------------
+Site configurations are stored in ``config/sites.yaml``.
+Default variables and settings are in `globals.py`.
+
+Examples
+--------
+Process one day of data:
+    >>> from canvodpy import process_date
+    >>> data = process_date("Rosalia", "2025001")
+
+Process a week:
+    >>> from canvodpy import Pipeline
+    >>> pipeline = Pipeline("Rosalia")
+    >>> for date, datasets in pipeline.process_range("2025001", "2025007"):
+    ...     print(f"Processed {date}")
+
+Calculate and visualize VOD:
+    >>> from canvodpy import calculate_vod
+    >>> from canvod.viz import HemisphereVisualizer
+    >>> vod = calculate_vod("Rosalia", "canopy_01", "reference_01", "2025001")
+    >>> viz = HemisphereVisualizer()
+    >>> fig = viz.plot_2d(vod)
+
+"""
+
+from canvodpy.api import (
+    Pipeline,
+    Site,
+    calculate_vod,
+    preview_processing,
+    process_date,
+)
+
+# Factories (for community extensions)
+from canvodpy.factories import (
+    AugmentationFactory,
+    GridFactory,
+    ReaderFactory,
+    VODFactory,
+)
+
+# Fluent workflow API (deferred execution)
+from canvodpy.fluent import FluentWorkflow
+
+# Functional API (Airflow-compatible)
+from canvodpy.functional import (
+    assign_grid_cells,
+    assign_grid_cells_to_file,
+    augment_with_ephemeris,
+    calculate_vod_to_file,
+    create_grid,
+    create_grid_to_file,
+    read_rinex,
+    read_rinex_to_file,
+)
+
+# Logging (for all users)
+from canvodpy.logging import get_logger, setup_logging
+
+# VOD computation helper
+from canvodpy.vod_computer import VodComputer
+
+# New workflow API
+from canvodpy.workflow import VODWorkflow
+
+
+def workflow(site: str, **kwargs) -> FluentWorkflow:
+    """Create a fluent workflow with deferred execution.
+
+    Parameters
+    ----------
+    site : str
+        Site name (e.g. ``"Rosalia"``).
+    **kwargs
+        Forwarded to :class:`FluentWorkflow`.
+
+    Returns
+    -------
+    FluentWorkflow
+
+    Examples
+    --------
+    >>> import canvodpy
+    >>> result = (canvodpy.workflow("Rosalia")
+    ...     .read("2025001")
+    ...     .preprocess()
+    ...     .grid()
+    ...     .vod("canopy_01", "reference_01")
+    ...     .result())
+    """
+    return FluentWorkflow(site, **kwargs)
+
+
+# ============================================================================
+# Level 3 API: Re-export subpackages for advanced users
+# ============================================================================
+
+
+# Lazy import subpackages on access to avoid circular dependencies
+def __getattr__(name: str):
+    """Lazy import subpackages when accessed."""
+    _subpackages = {
+        "auxiliary": "canvod.auxiliary",
+        "grids": "canvod.grids",
+        "readers": "canvod.readers",
+        "store": "canvod.store",
+        "viz": "canvod.viz",
+        "vod": "canvod.vod",
+    }
+
+    if name in _subpackages:
+        import importlib
+        import sys
+
+        module = importlib.import_module(_subpackages[name])
+        # Cache the imported module (can't use globals() as it's shadowed by canvodpy.globals)
+        setattr(sys.modules[__name__], name, module)
+        return module
+
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+# ============================================================================
+# Version
+# ============================================================================
+
+__version__ = "0.1.0"
+
+# ============================================================================
+# Public API
+# ============================================================================
+
+__all__ = [  # noqa: RUF022
+    # Version
+    "__version__",
+    # High-level API (most users)
+    "Site",
+    "Pipeline",
+    "process_date",
+    "calculate_vod",
+    "preview_processing",
+    # New workflow API
+    "VODWorkflow",
+    # Fluent workflow API
+    "FluentWorkflow",
+    "workflow",
+    # Functional API (notebooks & Airflow)
+    "read_rinex",
+    "read_rinex_to_file",
+    "create_grid",
+    "create_grid_to_file",
+    "assign_grid_cells",
+    "assign_grid_cells_to_file",
+    "calculate_vod_to_file",
+    # Logging
+    "setup_logging",
+    "get_logger",
+    # Factories (community extensions)
+    "ReaderFactory",
+    "GridFactory",
+    "VODFactory",
+    "AugmentationFactory",
+    # Subpackages (advanced users)
+    "readers",
+    "aux",
+    "grids",
+    "vod",
+    "viz",
+    "store",
+]
+
+
+# ============================================================================
+# Auto-register built-in components
+# ============================================================================
+
+
+def _register_builtin_components() -> None:
+    """
+    Register built-in component implementations.
+
+    Called automatically on package import. Registers:
+    - Rnxv3Obs reader (rinex3)
+    - EqualAreaGridBuilder (equal_area)
+    - TauOmegaZerothOrder calculator (tau_omega)
+
+    Notes
+    -----
+    Uses lazy imports to avoid loading heavy dependencies unless needed.
+    """
+    log = get_logger(__name__)
+
+    # Set ABC classes for validation
+    ReaderFactory._set_abc_class()
+    GridFactory._set_abc_class()
+    VODFactory._set_abc_class()
+    AugmentationFactory._set_abc_class()
+
+    try:
+        from canvod.readers import Rnxv3Obs
+
+        ReaderFactory.register("rinex3", Rnxv3Obs)
+    except ImportError:
+        log.debug("canvod-readers not available, skipping reader registration")
+
+    try:
+        from canvod.readers.sbf import SbfReader
+
+        ReaderFactory.register("sbf", SbfReader)
+    except ImportError:
+        log.debug("SbfReader not available, skipping sbf reader registration")
+
+    try:
+        from canvod.grids import EqualAreaBuilder
+
+        GridFactory.register("equal_area", EqualAreaBuilder)
+    except ImportError:
+        log.debug("canvod-grids not available, skipping grid registration")
+
+    try:
+        from canvod.vod.calculator import TauOmegaZerothOrder
+
+        VODFactory.register("tau_omega", TauOmegaZerothOrder)
+    except ImportError:
+        log.debug("canvod-vod not available, skipping VOD registration")
+
+    log.info("builtin_components_registered")
+
+
+# Auto-register on import
+_register_builtin_components()