STanalysis 0.1.4

Air pollution data extraction and comparison with different sources - HealthyPlanet Project - AWI

STanalysis

A Python package for extracting, analyzing, and comparing environmental data from multiple sources.

Developed by the Data Science Support group (DSS) at AWI
For the HealthyPlanet Project – BIPS, under the DataNord initiative

---

Features

• Extract point values from NetCDF datasets with spatial and temporal dimensions
• Support for multiple input formats (CSV, Shapefile, GeoJSON)
• Temporal aggregation with configurable window sizes
• Efficient nearest-neighbor interpolation
• Automatic coordinate transformation when datasets use projected x/y grids
• Comprehensive error handling and input validation

Installation

You can install STanalysis directly from PyPI:

pip install STanalysis

Or install from source for development:

git clone https://github.com/MuhammadShafeeque/dss-environment-analysis.git
cd dss-environment-analysis
uv pip install -e .[dev]

Quick Start

Here's a simple example of extracting temperature values at specific points:

from STanalysis import extract_point_values

# Extract values from a NetCDF file at specified points
result_df = extract_point_values(
    netcdf_path="temperature.nc",
    points_path="measurement_points.csv",
    variable="temperature",
    days_back=2,  # Average over the last 2 days
    date_col="date"
)

print(result_df[["name", "lat", "lon", "value"]])

Input CSV format example:

name,lat,lon,date
"Bremen City",53.0793,8.8017,2024-06-08
"Bremen North",53.1680,8.6317,2024-06-15

Documentation

Main Functions

extract_point_values

def extract_point_values(
    netcdf_path: str | Path,
    points_path: str | Path,
    variable: str,
    *,
    days_back: int = 7,
    date_col: Optional[str] = None,
    output_path: Optional[str | Path] = None,
) -> pd.DataFrame

Parameters:

• netcdf_path: Path to the input NetCDF file
• points_path: Path to point data (CSV, shapefile or GeoJSON)
• variable: Name of the variable to extract from the NetCDF dataset
• days_back: Number of days to average backwards from the provided date
• date_col: Optional column in the point file containing the date
• output_path: Optional path to write results (CSV or JSON)
• Spatial coordinates in the input points are assumed to be WGS84 (EPSG:4326) and will be transformed automatically if the NetCDF data uses a different CRS

Returns:

• DataFrame containing the extracted values and point metadata

Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

• Docker
• Visual Studio Code
• Dev Containers extension for VS Code

Using Dev Container

1. Clone the Repository:

git clone https://github.com/MuhammadShafeeque/dss-environment-analysis.git
cd dss-environment-analysis

2. Open in Dev Container:
   • Open VS Code
   • Press Ctrl+Shift+P (or Cmd+Shift+P on macOS)
   • Type "Dev Containers: Open Folder in Container"
   • Select the cloned repository folder

The dev container provides:

• Python 3.13+ with uv package manager
• Pre-configured VS Code extensions
• All development dependencies

Development Tools

The development environment includes:

• pytest for testing
• mypy for type checking
• ruff for code formatting and linting

Run tests:

pytest

Run type checking:

mypy STanalysis

Format code:

ruff format .

Project Structure

dss-environment-analysis/          # Repository root
├── STanalysis/                   # Main package source
│   ├── __init__.py              # Package initialization
│   └── point_extraction.py       # Core functionality
├── examples/                     # Example scripts
│   └── point_extraction_example.py
├── tests/                        # Test files
├── docs/                         # Documentation
├── pyproject.toml               # Project configuration
└── README.md                    # This file

Troubleshooting

NumPy binary compatibility errors

If you see an error like:

ImportError: A module that was compiled using NumPy 1.x cannot be run in NumPy 2.x

one of the compiled dependencies (for example netCDF4, pyproj, or shapely) was built against an older NumPy version. Reinstall the affected packages after upgrading NumPy so that wheels compiled for your NumPy release are used:

pip install --force-reinstall --no-binary :all: netCDF4 pyproj shapely

If compatible wheels are not available, downgrade NumPy to a 1.x release:

pip install "numpy<2"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

---

Note: This repository is under active development. Features and APIs may change.