cosmicbiomass 0.1.1__tar.gz

cosmicbiomass-0.1.1/.gitignore

@@ -0,0 +1,195 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be added to the global gitignore or merged into this project gitignore.  For a PyCharm
+#  project, it is common to ignore the .idea/ directory.
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# OS specific files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+
+# Project specific
+# Debug and demo scripts can be kept for development
+debug_footprint.py
+plot_results.py
+simple_demo.py
+test_import.py
+_cosmicbiomass/*
+comprehensive_footprint_analysis.py
+readme_scripts.py
+
+# Generated plots (uncomment if you don't want to track generated plots)
+*.png
+*.jpg
+*.pdf
+*.html

cosmicbiomass-0.1.1/.gitlab-ci.yml

@@ -0,0 +1,84 @@
+stages:
+  - test
+  - build
+  - publish
+
+variables:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+  UV_CACHE_DIR: "$CI_PROJECT_DIR/.uv-cache"
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+  UV_PYTHON: "python3.12"
+  UV_PYTHON_PREFERENCE: "only-system"
+  UV_PYTHON_DOWNLOAD: "0"
+
+default:
+  image: python:3.12-slim
+  tags:
+    - hifis-linux-small-amd64
+    - dind
+    - hifis
+  before_script:
+    - apt-get update && apt-get install -y --no-install-recommends libexpat1 && rm -rf /var/lib/apt/lists/*
+    - python -m pip install --upgrade pip uv
+
+cache:
+  key: "uv-cache"
+  paths:
+    - .uv-cache/
+    - .cache/pip/
+
+pytest:
+  stage: test
+  rules:
+    - if: '$CI_COMMIT_TAG'
+      when: never
+    - when: on_success
+  script:
+    - uv sync --group dev --frozen
+    - uv run ruff check .
+    - uv run pytest
+
+build:
+  stage: build
+  script:
+    - |
+      if [ -n "$CI_COMMIT_TAG" ]; then
+        VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+        TAG_VERSION=${CI_COMMIT_TAG#v}
+        if [ "$TAG_VERSION" != "$VERSION" ]; then
+          echo "Tag version ($TAG_VERSION) does not match pyproject.toml ($VERSION)."
+          exit 1
+        fi
+      fi
+    - uv build
+    - uv publish --dry-run dist/*.whl dist/*.tar.gz
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 7 days
+
+publish_testpypi:
+  stage: publish
+  needs:
+    - job: build
+      artifacts: true
+  dependencies:
+    - build
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+a\d+$/'
+  script:
+    - ls -la dist
+    - uv publish --publish-url https://test.pypi.org/legacy/ --token "$TESTPYPI_TOKEN" dist/*.whl dist/*.tar.gz
+
+publish_pypi:
+  stage: publish
+  needs:
+    - job: build
+      artifacts: true
+  dependencies:
+    - build
+  rules:
+    - if: '$CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/'
+  script:
+    - ls -la dist
+    - uv publish --token "$PYPI_TOKEN" dist/*.whl dist/*.tar.gz

cosmicbiomass-0.1.1/.python-version

@@ -0,0 +1 @@
+3.13.2

cosmicbiomass-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Louis Ferdinand Trinkle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cosmicbiomass-0.1.1/PKG-INFO

@@ -0,0 +1,319 @@
+Metadata-Version: 2.4
+Name: cosmicbiomass
+Version: 0.1.1
+Summary: Aboveground biomass extraction with footprint-weighted statistics.
+Project-URL: Homepage, https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass
+Project-URL: Repository, https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass
+Project-URL: Issues, https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass/issues
+Author-email: LFT-W47 <louis.trinkle@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agbd,biomass,crns,geospatial,remote-sensing,stac
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Requires-Dist: cubo<2025.0.0,>=2024.8.0
+Requires-Dist: earthengine-api<2.0.0,>=1.1.4
+Requires-Dist: geopandas<0.15.0,>=0.14.0
+Requires-Dist: joblib<2.0.0,>=1.3.0
+Requires-Dist: numpy<2.0.0,>=1.24.0
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: planetary-computer<2.0.0,>=1.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: pystac-client<1.0.0,>=0.8.0
+Requires-Dist: rasterio<2.0.0,>=1.3.0
+Requires-Dist: rioxarray<0.20.0,>=0.19.0
+Requires-Dist: scikit-learn<2.0.0,>=1.7.0
+Requires-Dist: scipy<2.0.0,>=1.11.0
+Requires-Dist: seaborn<0.14.0,>=0.13.2
+Requires-Dist: setuptools>=80.9.0
+Requires-Dist: shapely<3.0.0,>=2.0.0
+Requires-Dist: stackstac<1.0.0,>=0.5.1
+Requires-Dist: xee<1.0.0,>=0.0.13
+Description-Content-Type: text/markdown
+
+# CosmicBiomass
+
+A modern Python package for extracting and analyzing aboveground biomass density (AGBD) from satellite data sources with support for geospatial footprint weighting and statistical analysis.
+
+## Features
+
+- 🌍 **Geospatial biomass extraction** from DLR STAC data sources (2017-2023)
+- 📊 **Footprint-weighted statistics** with circular, Gaussian, and CRNS weighting schemes
+- 🔬 **CRNS weighting function** implementing Schrön et al. (2017) for cosmic ray neutron sensing
+- 🎯 **High precision analysis** with uncertainty quantification and outlier detection
+- 🏗️ **Modular architecture** with pluggable data sources and processing components
+- ✅ **89% test coverage** with comprehensive unit and integration tests
+- 🐍 **Modern Python 3.10+** with type hints, uv-managed environments, and `src/` layout
+
+## Quick Start
+
+### Installation
+
+#### Option 1: Install from GitHub (Recommended)
+
+```bash
+# Install directly from GitHub using pip
+pip install git+https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass.git
+
+# Or install in development mode for contributions
+pip install -e git+hhttps://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass.git#egg=cosmicbiomass
+```
+
+#### Option 2: Install with conda/mamba
+
+```bash
+# First install dependencies via conda
+conda install -c conda-forge numpy xarray matplotlib pyproj
+
+# Then install cosmicbiomass from GitHub
+pip install git+https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass.git
+```
+
+#### Option 3: Development Installation (uv)
+
+```bash
+# Clone the repository
+git clone https://codebase.helmholtz.cloud/louis-ferdinand.trinkle/cosmicbiomass.git
+cd cosmicbiomass
+
+# Create a virtual environment
+uv venv .venv
+
+# Activate the environment
+source .venv/bin/activate
+
+# Install the package in development mode
+uv pip install -e .
+
+# Lock dependencies for reproducibility
+uv lock
+
+```
+
+### Reproducible Workflow Example
+
+Here's a complete example extracting biomass data at the TERENO Hohes Holz station:
+
+```python
+import cosmicbiomass
+
+# TERENO Hohes Holz station coordinates
+lat, lon = 52.09, 11.226  # degrees N, E
+footprint_radius = 240    # meters
+
+# Extract biomass data with 240m circular footprint
+result = cosmicbiomass.get_average_biomass(
+    lat=lat,
+    lon=lon,
+    radius=footprint_radius,
+    source="dlr",
+    dataset="agbd_2018"  # Available: 2017-2023
+)
+
+# Access results
+biomass_mgha = result['summary']['mean_biomass_Mg_ha']
+uncertainty_mgha = result['summary']['uncertainty_Mg_ha']
+
+print(f"Mean AGBD: {biomass_mgha:.1f} ± {uncertainty_mgha:.1f} Mg/ha")
+# Output: Mean AGBD: 202.6 ± 27.8 Mg/ha
+
+# Access detailed information
+print(f"Footprint coverage: {result['footprint']['effective_pixels']} pixels")
+print(f"Data source: {result['data_info']['source']}")
+print(f"Dataset: {result['data_info']['dataset']}")
+```
+
+### Available Datasets
+
+```python
+# List all available datasets
+datasets = cosmicbiomass.list_available_datasets(source="dlr")
+print("Available years:", list(datasets['datasets'].keys()))
+# Output: ['agbd_2017', 'agbd_2018', 'agbd_2019', 'agbd_2020', 'agbd_2021', 'agbd_2022', 'agbd_2023']
+```
+
+## API Reference
+
+### Core Functions
+
+#### `get_average_biomass(lat, lon, radius=500, source="dlr", dataset="agbd_2021", **kwargs)`
+
+Extract footprint-weighted biomass statistics for a location.
+
+**Parameters:**
+
+- `lat`, `lon` (float): Center coordinates in WGS84 decimal degrees
+- `radius` (float): Footprint radius in meters (default: 500)
+- `source` (str): Data source name (default: "dlr")
+- `dataset` (str): Dataset identifier like "agbd_2018" (default: "agbd_2021")
+- `footprint_shape` (str): "circular", "gaussian", or "crns" (default: "crns")
+- `include_uncertainty` (bool): Include uncertainty estimation (default: True)
+- `outlier_method` (str): "iqr", "zscore", or None for outlier detection
+
+**Returns:**
+Dictionary with biomass statistics, location info, and metadata.
+
+#### `list_available_datasets(source="dlr")`
+
+Get information about available datasets for a data source.
+
+#### `validate_coordinates(lat, lon)`
+
+Validate latitude/longitude coordinates are within valid ranges.
+
+## Directory Structure
+
+```
+cosmicbiomass/
+├── README.md
+├── pyproject.toml              # Python project configuration
+├── src/
+│   └── cosmicbiomass/
+│       ├── __init__.py         # Public API
+│       ├── core.py             # Main analysis functions  
+│       ├── config.py           # Configuration classes
+│       ├── registry.py         # Data source management
+│       ├── processing/         # Statistical and footprint processing
+│       └── sources/            # Data source implementations
+└── tests/                      # Comprehensive test suite (89% coverage)
+```
+
+## Dependency Lock
+
+Use the lockfile for reproducible environments:
+
+```bash
+uv lock
+```
+
+## Testing
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage report
+uv run pytest --cov=cosmicbiomass --cov-report=html
+
+# Run specific test modules
+uv run pytest tests/test_core.py -v
+```
+
+## Publishing to PyPI
+
+```bash
+# Build wheel and sdist
+uv build
+
+# Publish to PyPI (requires credentials)
+uv publish
+```
+
+## CI/CD (GitLab)
+
+See [docs/CI_CD.md](docs/CI_CD.md) for the GitLab pipeline, runner tags, and release tag formats.
+
+
+## Advanced Usage
+
+### Custom Footprint Analysis
+
+```python
+# CRNS footprint (default) - Schrön et al. (2017) weighting
+result = cosmicbiomass.get_average_biomass(
+    lat=52.09, lon=11.226,
+    radius=500,
+    footprint_shape="crns",  # Cosmic ray neutron sensing weighting
+    dataset="agbd_2020"
+)
+
+# Gaussian footprint with outlier detection
+result_gaussian = cosmicbiomass.get_average_biomass(
+    lat=52.09, lon=11.226,
+    radius=500,
+    footprint_shape="gaussian",
+    outlier_method="iqr",
+    dataset="agbd_2020"
+)
+
+# Access detailed footprint info
+print(f"Effective pixels: {result['footprint']['effective_pixels']}")
+print(f"Total weight: {result['footprint']['total_weight']:.1f}")
+```
+
+### Multi-year Analysis
+
+```python
+series = cosmicbiomass.get_average_biomass_timeseries(
+    lat=52.09,
+    lon=11.226,
+    radius=240,
+    dataset="agbd_{year}",
+    start_time="2017-01-01",
+    end_time="2023-12-31",
+)
+
+biomass_time_series = [
+    {
+        "year": entry["year"],
+        "biomass": entry["result"]["summary"]["mean_biomass_Mg_ha"],
+        "uncertainty": entry["result"]["summary"]["uncertainty_Mg_ha"],
+    }
+    for entry in series
+]
+
+```
+
+### VI-driven Seasonal Interpolation (pandas output)
+
+Use vegetation indices (LAI/EVI/NDVI) to create a higher-frequency biomass series. The
+frequency is inferred from your VI data or you can provide one (e.g., "1H", "1D").
+
+```python
+seasonal = cosmicbiomass.get_seasonal_biomass_timeseries(
+    lat=52.09,
+    lon=11.226,
+    radius=170,
+    dataset="agbd_{year}",
+    start_time="2017-01-01",
+    end_time="2023-12-31",
+    target_frequency="1D",
+    vi_source="auto",  # fetch LAI via GEE, EVI/NDVI via Planetary Computer
+)
+
+print(seasonal.head())
+```
+```
+
+## Data Sources
+
+### DLR Global Aboveground Biomass Density
+
+- **Coverage**: 2017-2023 annual products
+- **Resolution**: 10m spatial resolution
+- **Units**: Mg/ha (megagrams per hectare)
+- **Uncertainty**: Available via data spread analysis
+- **Access**: STAC catalog via `cubo` integration
+
+## Contributing
+
+- Follow PEP 8 and modern Python best practices
+- Add tests for new features (maintain >85% coverage)
+- Use f-strings, pathlib, and type hints
+- Run `uv run pytest` before submitting changes
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+Copyright (c) 2025 Louis Ferdinand Trinkle