camelsch 0.1.0__tar.gz

camelsch-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: camelsch
+Version: 0.1.0
+Summary: CLI tool for extracting and working with CAMELS-CH hydrological data
+Author: Beatrice Marti
+Author-email: Beatrice Marti <mabesa@users.noreply.github.com>
+License-Expression: MIT
+Requires-Dist: pandas>=2.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: pandas-stubs>=2.0 ; extra == 'dev'
+Requires-Dist: pytest>=9.0.2 ; extra == 'dev'
+Requires-Dist: ruff>=0.15.2 ; extra == 'dev'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/hydrosolutions/camelsch
+Project-URL: Repository, https://github.com/hydrosolutions/camelsch
+Project-URL: Issues, https://github.com/hydrosolutions/camelsch/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# camelsch
+
+[![CI](https://github.com/hydrosolutions/camelsch/actions/workflows/ci.yml/badge.svg)](https://github.com/hydrosolutions/camelsch/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/hydrosolutions/camelsch/HEAD?labpath=demo.ipynb)
+
+CLI tool for downloading, exploring, and extracting data from the [CAMELS-CH](https://zenodo.org/records/15025258) hydrological dataset (331 Swiss basins, 1981-2020).
+
+## Installation
+
+```bash
+pip install camelsch
+```
+
+This also works inside conda/mamba environments — just activate yours first.
+
+If you use [uv](https://docs.astral.sh/uv/) for project management:
+
+```bash
+uv add camelsch
+```
+
+## Workflow
+
+camelsch follows a **download-then-query** workflow:
+
+1. **Download** the CAMELS-CH dataset once from Zenodo (~1.5 GB).
+2. **Explore** the dataset — list basins, check available variables, view summaries.
+3. **Extract** the data you need — filter by basin, variable, and date range, then export to CSV or Parquet.
+
+All commands read from a local data directory (default `./data/CAMELS_CH`). You can change it with `--data-dir` or the `CAMELSCH_DATA_DIR` environment variable.
+
+## Quick start
+
+```bash
+# Step 1: Download the dataset from Zenodo (~1.5 GB)
+camelsch download
+
+# Step 2: Explore — show dataset summary
+camelsch info
+
+# List all basin IDs
+camelsch basins
+camelsch basins --format json
+camelsch basins --format csv --attrs area,p_mean
+
+# Step 3: Extract data
+# Static catchment attributes
+camelsch attributes --basins 2004,2007 --output attrs.csv
+
+# Time series with filtering
+camelsch timeseries --basins 2004 --vars precipitation,discharge_spec \
+    --start 1990-01-01 --end 2000-12-31 --output ts.csv
+
+# Batch export to Parquet (with optional attribute merge)
+camelsch export --include-attrs --output camels_ch.parquet
+```
+
+## Python API
+
+```python
+import camelsch
+
+# Load static attributes for specific basins
+attrs = camelsch.load_attributes("./data/CAMELS_CH", basin_ids=["2004", "2007"])
+
+# Load time series with filtering
+data = camelsch.load_timeseries(
+    "./data/CAMELS_CH",
+    basin_ids=["2004"],
+    variables=["precipitation", "discharge_spec"],
+    start_date="1990-01-01",
+    end_date="2000-12-31",
+)
+
+# List available basins and variables
+basins = camelsch.list_basins("./data/CAMELS_CH")
+variables = camelsch.list_variables("./data/CAMELS_CH")
+```
+
+## Data reference
+
+CAMELS-CH provides daily hydrometeorological time series and static catchment attributes for 331 Swiss basins (1981-2020). Key variables include:
+
+| Variable | Description |
+|---|---|
+| `precipitation` | Basin-mean daily precipitation (mm/d) |
+| `temperature` | Basin-mean daily temperature (deg C) |
+| `discharge_spec` | Observed specific discharge (mm/d) |
+| `discharge_spec_sim` | Simulated specific discharge (mm/d) |
+| `pet` / `pet_sim` | Potential evapotranspiration (mm/d) |
+| `et` / `et_sim` | Actual evapotranspiration (mm/d) |
+| `snow_water_eq_sim` | Simulated snow water equivalent (mm) |
+
+Static attributes cover topography (`area`, `elev_mean`), climate (`p_mean`, `t_mean`), land cover, soil, and geology.
+
+**Full dataset**: [CAMELS-CH on Zenodo](https://zenodo.org/records/15025258)
+**Reference paper**: Hoege et al. (2023), *CAMELS-CH: hydro-meteorological time series and landscape attributes for 331 catchments in hydrologic Switzerland*, Earth Syst. Sci. Data.
+
+## For developers
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+MIT

camelsch-0.1.0/README.md

@@ -0,0 +1,119 @@
+# camelsch
+
+[![CI](https://github.com/hydrosolutions/camelsch/actions/workflows/ci.yml/badge.svg)](https://github.com/hydrosolutions/camelsch/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)](https://www.python.org)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/hydrosolutions/camelsch/HEAD?labpath=demo.ipynb)
+
+CLI tool for downloading, exploring, and extracting data from the [CAMELS-CH](https://zenodo.org/records/15025258) hydrological dataset (331 Swiss basins, 1981-2020).
+
+## Installation
+
+```bash
+pip install camelsch
+```
+
+This also works inside conda/mamba environments — just activate yours first.
+
+If you use [uv](https://docs.astral.sh/uv/) for project management:
+
+```bash
+uv add camelsch
+```
+
+## Workflow
+
+camelsch follows a **download-then-query** workflow:
+
+1. **Download** the CAMELS-CH dataset once from Zenodo (~1.5 GB).
+2. **Explore** the dataset — list basins, check available variables, view summaries.
+3. **Extract** the data you need — filter by basin, variable, and date range, then export to CSV or Parquet.
+
+All commands read from a local data directory (default `./data/CAMELS_CH`). You can change it with `--data-dir` or the `CAMELSCH_DATA_DIR` environment variable.
+
+## Quick start
+
+```bash
+# Step 1: Download the dataset from Zenodo (~1.5 GB)
+camelsch download
+
+# Step 2: Explore — show dataset summary
+camelsch info
+
+# List all basin IDs
+camelsch basins
+camelsch basins --format json
+camelsch basins --format csv --attrs area,p_mean
+
+# Step 3: Extract data
+# Static catchment attributes
+camelsch attributes --basins 2004,2007 --output attrs.csv
+
+# Time series with filtering
+camelsch timeseries --basins 2004 --vars precipitation,discharge_spec \
+    --start 1990-01-01 --end 2000-12-31 --output ts.csv
+
+# Batch export to Parquet (with optional attribute merge)
+camelsch export --include-attrs --output camels_ch.parquet
+```
+
+## Python API
+
+```python
+import camelsch
+
+# Load static attributes for specific basins
+attrs = camelsch.load_attributes("./data/CAMELS_CH", basin_ids=["2004", "2007"])
+
+# Load time series with filtering
+data = camelsch.load_timeseries(
+    "./data/CAMELS_CH",
+    basin_ids=["2004"],
+    variables=["precipitation", "discharge_spec"],
+    start_date="1990-01-01",
+    end_date="2000-12-31",
+)
+
+# List available basins and variables
+basins = camelsch.list_basins("./data/CAMELS_CH")
+variables = camelsch.list_variables("./data/CAMELS_CH")
+```
+
+## Data reference
+
+CAMELS-CH provides daily hydrometeorological time series and static catchment attributes for 331 Swiss basins (1981-2020). Key variables include:
+
+| Variable | Description |
+|---|---|
+| `precipitation` | Basin-mean daily precipitation (mm/d) |
+| `temperature` | Basin-mean daily temperature (deg C) |
+| `discharge_spec` | Observed specific discharge (mm/d) |
+| `discharge_spec_sim` | Simulated specific discharge (mm/d) |
+| `pet` / `pet_sim` | Potential evapotranspiration (mm/d) |
+| `et` / `et_sim` | Actual evapotranspiration (mm/d) |
+| `snow_water_eq_sim` | Simulated snow water equivalent (mm) |
+
+Static attributes cover topography (`area`, `elev_mean`), climate (`p_mean`, `t_mean`), land cover, soil, and geology.
+
+**Full dataset**: [CAMELS-CH on Zenodo](https://zenodo.org/records/15025258)
+**Reference paper**: Hoege et al. (2023), *CAMELS-CH: hydro-meteorological time series and landscape attributes for 331 catchments in hydrologic Switzerland*, Earth Syst. Sci. Data.
+
+## For developers
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest
+
+# Lint and format
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+
+# Type check
+uv run mypy src/
+```
+
+## License
+
+MIT

camelsch-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "camelsch"
+version = "0.1.0"
+description = "CLI tool for extracting and working with CAMELS-CH hydrological data"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Beatrice Marti", email = "mabesa@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "pandas>=2.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+    "pyarrow>=14.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/hydrosolutions/camelsch"
+Repository = "https://github.com/hydrosolutions/camelsch"
+Issues = "https://github.com/hydrosolutions/camelsch/issues"
+
+[project.scripts]
+camelsch = "camelsch.cli:app"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP", "B", "A", "SIM", "RUF"]
+ignore = ["B008"]  # typer.Option() in defaults is the standard typer pattern
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[[tool.mypy.overrides]]
+module = ["pyarrow"]
+ignore_missing_imports = true
+
+[project.optional-dependencies]
+dev = [
+    "mypy>=1.10",
+    "pandas-stubs>=2.0",
+    "pytest>=9.0.2",
+    "ruff>=0.15.2",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "src"]
+addopts = "--doctest-modules"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.10",
+    "pandas-stubs>=2.0",
+    "pytest>=9.0.2",
+    "ruff>=0.15.2",
+]

camelsch-0.1.0/src/camelsch/__init__.py

@@ -0,0 +1,30 @@
+"""camelsch — CLI tool for CAMELS-CH hydrological data extraction."""
+
+import logging
+
+from camelsch.attributes import get_attribute_names, load_attributes
+from camelsch.download import download_camels_ch
+from camelsch.export import export_attributes, export_merged, export_timeseries
+from camelsch.timeseries import (
+    list_basins,
+    list_variables,
+    load_basin_timeseries,
+    load_timeseries,
+)
+
+__version__ = "0.1.0"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+__all__ = [
+    "download_camels_ch",
+    "export_attributes",
+    "export_merged",
+    "export_timeseries",
+    "get_attribute_names",
+    "list_basins",
+    "list_variables",
+    "load_attributes",
+    "load_basin_timeseries",
+    "load_timeseries",
+]

camelsch-0.1.0/src/camelsch/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the CLI with ``python -m camelsch``."""
+
+from camelsch.cli import app
+
+app()

camelsch-0.1.0/src/camelsch/attributes.py

@@ -0,0 +1,84 @@
+"""Load and merge static attribute CSVs."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+from camelsch.io import find_id_column, read_csv_robust, strip_units
+
+logger = logging.getLogger(__name__)
+
+
+def _read_attribute_csv(path: Path) -> pd.DataFrame:
+    """Read a single CAMELS-CH attribute CSV handling encoding and comments."""
+    df = read_csv_robust(path)
+    df.columns = [strip_units(c) for c in df.columns]
+
+    id_col = find_id_column(df)
+    if id_col:
+        df[id_col] = df[id_col].astype(str)
+        if id_col != "gauge_id":
+            df = df.rename(columns={id_col: "gauge_id"})
+        df = df.set_index("gauge_id")
+
+    return df
+
+
+def load_attributes(
+    data_dir: str | Path,
+    basin_ids: list[str] | None = None,
+) -> pd.DataFrame:
+    """Load and merge all static attribute CSVs.
+
+    Reads every ``*.csv`` under ``static_attributes/`` (including subdirectories),
+    strips unit suffixes from column names, and merges on ``gauge_id``.
+
+    Args:
+        data_dir: Path to the extracted ``camels_ch`` directory.
+        basin_ids: Optional list of basin IDs to filter to.
+
+    Returns:
+        DataFrame indexed by ``gauge_id`` with all attribute columns.
+    """
+    data_dir = Path(data_dir)
+    attr_dir = data_dir / "static_attributes"
+
+    csv_files = sorted(attr_dir.glob("*.csv"))
+    for subdir in ["supplements", "simulation_based"]:
+        sub = attr_dir / subdir
+        if sub.exists():
+            csv_files.extend(sorted(sub.glob("*.csv")))
+
+    if not csv_files:
+        msg = f"No attribute CSVs found in {attr_dir}"
+        raise FileNotFoundError(msg)
+
+    merged: pd.DataFrame | None = None
+    for csv_path in csv_files:
+        df = _read_attribute_csv(csv_path)
+        logger.debug("Loaded attribute file %s (%d cols)", csv_path.name, len(df.columns))
+        if merged is None:
+            merged = df
+        else:
+            new_cols = [c for c in df.columns if c not in merged.columns]
+            if new_cols:
+                merged = merged.join(df[new_cols], how="outer")
+
+    if merged is None:
+        msg = f"No attribute data could be loaded from {attr_dir}"
+        raise ValueError(msg)
+
+    if basin_ids is not None:
+        merged = merged.loc[merged.index.isin(basin_ids)]
+
+    logger.debug("Attributes loaded: %d basins, %d columns", len(merged), len(merged.columns))
+    return merged
+
+
+def get_attribute_names(data_dir: str | Path) -> list[str]:
+    """List all available attribute column names."""
+    df = load_attributes(data_dir)
+    return list(df.columns)

camelsch-0.1.0/src/camelsch/cli.py

@@ -0,0 +1,357 @@
+"""CLI entry point for camelsch."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from camelsch import __version__
+
+Format = Literal["csv", "parquet"]
+
+app = typer.Typer(
+    name="camelsch",
+    help="CLI tool for CAMELS-CH hydrological data extraction.",
+    no_args_is_help=True,
+)
+
+DEFAULT_DATA_DIR = Path("./data/CAMELS_CH")
+
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"camelsch {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        help="Show version and exit.",
+        callback=_version_callback,
+        is_eager=True,
+    ),
+) -> None:
+    """CLI tool for CAMELS-CH hydrological data extraction."""
+
+
+def resolve_data_dir(data_dir: Path | None) -> Path:
+    """Resolve data directory from argument, env var, or default."""
+    if data_dir is not None:
+        return data_dir
+    env = os.environ.get("CAMELSCH_DATA_DIR")
+    if env:
+        return Path(env)
+    return DEFAULT_DATA_DIR
+
+
+def _check_data_dir(dd: Path) -> None:
+    """Exit with a friendly hint if the data directory doesn't exist."""
+    if not dd.exists():
+        console.print(f"[red]Directory not found: {dd}[/red]")
+        console.print("Run 'camelsch download' first.")
+        raise typer.Exit(1)
+
+
+def _infer_format(output: Path, fmt: str) -> Format:
+    """Infer output format from file extension, falling back to *fmt*."""
+    if output.suffix == ".parquet":
+        return "parquet"
+    if output.suffix == ".csv":
+        return "csv"
+    if fmt in ("csv", "parquet"):
+        return fmt  # type: ignore[return-value]
+    return "csv"
+
+
+# ---------------------------------------------------------------------------
+# download
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def download(
+    dest: Path = typer.Option(DEFAULT_DATA_DIR, help="Target directory."),
+    force: bool = typer.Option(False, help="Re-download even if exists."),
+    url: str | None = typer.Option(None, help="Custom Zenodo URL to download from."),
+) -> None:
+    """Download and extract the CAMELS-CH dataset from Zenodo.
+
+    Example: camelsch download --dest ./my_data
+    """
+    from camelsch.download import download_camels_ch
+
+    kwargs: dict[str, object] = {"dest": dest, "force": force}
+    if url is not None:
+        kwargs["url"] = url
+    path = download_camels_ch(**kwargs)  # type: ignore[arg-type]
+    console.print(f"[green]Dataset ready at {path}[/green]")
+
+
+# ---------------------------------------------------------------------------
+# info
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def info(
+    data_dir: Path | None = typer.Option(None, help="Path to CAMELS_CH dir."),
+) -> None:
+    """Show dataset summary: basins, time range, variables.
+
+    Example: camelsch info --data-dir ./data/CAMELS_CH
+    """
+    from camelsch.attributes import load_attributes
+    from camelsch.timeseries import (
+        list_basins,
+        list_variables,
+        load_basin_timeseries,
+    )
+
+    dd = resolve_data_dir(data_dir)
+    _check_data_dir(dd)
+
+    basin_ids = list_basins(dd)
+    variables = list_variables(dd)
+
+    date_range = ""
+    if basin_ids:
+        sample = load_basin_timeseries(dd, basin_ids[0])
+        if len(sample.index) > 0:
+            date_range = f"{sample.index.min().date()} to {sample.index.max().date()}"
+
+    try:
+        attrs = load_attributes(dd)
+        attr_count = len(attrs.columns)
+    except FileNotFoundError:
+        attr_count = 0
+
+    table = Table(title="CAMELS-CH Dataset Summary", show_header=False)
+    table.add_column("Key", style="bold")
+    table.add_column("Value")
+    table.add_row("Location", str(dd))
+    table.add_row("Basins", str(len(basin_ids)))
+    table.add_row("Time range", date_range)
+    table.add_row("Variables", ", ".join(variables))
+    table.add_row("Attributes", f"{attr_count} static features")
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# basins
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def basins(
+    data_dir: Path | None = typer.Option(None, help="Path to CAMELS_CH dir."),
+    fmt: str = typer.Option("table", "--format", help="Output: table, csv, json."),
+    attrs: str | None = typer.Option(None, help="Comma-separated attribute names."),
+) -> None:
+    """List available basin IDs with optional attributes.
+
+    Example: camelsch basins --format json --attrs area,p_mean
+    """
+    from camelsch.timeseries import list_basins as _list_basins
+
+    dd = resolve_data_dir(data_dir)
+    _check_data_dir(dd)
+    basin_ids = _list_basins(dd)
+
+    attr_df = None
+    if attrs:
+        from camelsch.attributes import load_attributes
+
+        attr_names = [a.strip() for a in attrs.split(",")]
+        attr_df = load_attributes(dd)
+        valid_cols = [c for c in attr_names if c in attr_df.columns]
+        attr_df = attr_df[valid_cols] if valid_cols else attr_df.iloc[:, :0]
+        attr_df = attr_df.loc[attr_df.index.isin(basin_ids)]
+
+    if fmt == "json":
+        _basins_json(basin_ids, attr_df)
+    elif fmt == "csv":
+        _basins_csv(basin_ids, attr_df)
+    else:
+        _basins_table(basin_ids, attr_df)
+
+
+def _basins_json(basin_ids: list[str], attr_df: pd.DataFrame | None) -> None:
+    """Output basin list as JSON."""
+    if attr_df is not None:
+        records = []
+        for bid in basin_ids:
+            rec: dict[str, object] = {"basin_id": bid}
+            if bid in attr_df.index:
+                rec.update(attr_df.loc[bid].to_dict())  # type: ignore[arg-type]
+            records.append(rec)
+        typer.echo(json.dumps(records, indent=2))
+    else:
+        typer.echo(json.dumps(basin_ids, indent=2))
+
+
+def _basins_csv(basin_ids: list[str], attr_df: pd.DataFrame | None) -> None:
+    """Output basin list as CSV."""
+    if attr_df is not None:
+        header = "basin_id," + ",".join(attr_df.columns)
+        typer.echo(header)
+        for bid in basin_ids:
+            if bid in attr_df.index:
+                vals = ",".join(str(v) for v in attr_df.loc[bid])
+                typer.echo(f"{bid},{vals}")
+            else:
+                typer.echo(bid)
+    else:
+        for bid in basin_ids:
+            typer.echo(bid)
+
+
+def _basins_table(basin_ids: list[str], attr_df: pd.DataFrame | None) -> None:
+    """Output basin list as a rich table."""
+    table = Table(title="CAMELS-CH Basins")
+    table.add_column("basin_id")
+    if attr_df is not None:
+        for col in attr_df.columns:
+            table.add_column(col)
+        for bid in basin_ids:
+            if bid in attr_df.index:
+                row = attr_df.loc[bid]
+                table.add_row(bid, *(str(v) for v in row))
+            else:
+                table.add_row(bid, *[""] * len(attr_df.columns))
+    else:
+        for bid in basin_ids:
+            table.add_row(bid)
+    console.print(table)
+
+
+# ---------------------------------------------------------------------------
+# attributes
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def attributes(
+    data_dir: Path | None = typer.Option(None, help="Path to CAMELS_CH dir."),
+    basins_opt: str | None = typer.Option(None, "--basins", help="Comma-separated basin IDs."),
+    output: Path | None = typer.Option(None, help="Output file path."),
+    fmt: str = typer.Option("csv", "--format", help="Output format: csv or parquet."),
+) -> None:
+    """Extract static catchment attributes to CSV or Parquet.
+
+    Example: camelsch attributes --basins 2004,2007 --output attrs.csv
+    """
+    from camelsch.attributes import load_attributes
+    from camelsch.export import export_attributes
+
+    dd = resolve_data_dir(data_dir)
+    _check_data_dir(dd)
+    bid_list = [b.strip() for b in basins_opt.split(",")] if basins_opt else None
+    df = load_attributes(dd, basin_ids=bid_list)
+
+    if output:
+        export_attributes(df, output, fmt=_infer_format(output, fmt))
+        console.print(f"[green]Attributes written to {output}[/green]")
+    else:
+        typer.echo(df.to_csv())
+
+
+# ---------------------------------------------------------------------------
+# timeseries
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def timeseries(
+    data_dir: Path | None = typer.Option(None, help="Path to CAMELS_CH dir."),
+    basins_opt: str | None = typer.Option(
+        None, "--basins", help="Comma-separated basin IDs, or 'all'."
+    ),
+    vars_opt: str | None = typer.Option(None, "--vars", help="Comma-separated variable names."),
+    start: str | None = typer.Option(None, help="Start date (YYYY-MM-DD)."),
+    end: str | None = typer.Option(None, help="End date (YYYY-MM-DD)."),
+    output: Path | None = typer.Option(None, help="Output file path."),
+    fmt: str = typer.Option("csv", "--format", help="Output format: csv or parquet."),
+) -> None:
+    """Extract time series data for one or more basins.
+
+    Example: camelsch timeseries --basins 2004 --vars precipitation --start 1990-01-01
+    """
+    from camelsch.export import export_timeseries
+    from camelsch.timeseries import load_timeseries
+
+    dd = resolve_data_dir(data_dir)
+    _check_data_dir(dd)
+    bid_list = (
+        None
+        if basins_opt is None or basins_opt.strip().lower() == "all"
+        else [b.strip() for b in basins_opt.split(",")]
+    )
+    var_list = [v.strip() for v in vars_opt.split(",")] if vars_opt else None
+
+    data = load_timeseries(
+        dd,
+        basin_ids=bid_list,
+        variables=var_list,
+        start_date=start,
+        end_date=end,
+    )
+
+    if output:
+        export_timeseries(data, output, fmt=_infer_format(output, fmt))
+        console.print(f"[green]Time series written to {output}[/green]")
+    else:
+        for bid, df in data.items():
+            if len(data) > 1:
+                typer.echo(f"--- Basin {bid} ---")
+            typer.echo(df.to_csv())
+
+
+# ---------------------------------------------------------------------------
+# export
+# ---------------------------------------------------------------------------
+
+
+@app.command()
+def export(
+    data_dir: Path | None = typer.Option(None, help="Path to CAMELS_CH dir."),
+    basins_opt: str | None = typer.Option(None, "--basins", help="Comma-separated basin IDs."),
+    output: Path = typer.Option(Path("camels_ch_export.parquet"), help="Output file path."),
+    fmt: str = typer.Option("parquet", "--format", help="Output format: csv or parquet."),
+    include_attrs: bool = typer.Option(False, help="Merge static attributes into output."),
+) -> None:
+    """Batch export: merge time series (+ optional attributes) into one file.
+
+    Example: camelsch export --basins 2004,2007 --include-attrs --output merged.parquet
+    """
+    from camelsch.attributes import load_attributes
+    from camelsch.export import export_merged, export_timeseries
+    from camelsch.timeseries import load_timeseries
+
+    dd = resolve_data_dir(data_dir)
+    _check_data_dir(dd)
+    bid_list = [b.strip() for b in basins_opt.split(",")] if basins_opt else None
+
+    data = load_timeseries(dd, basin_ids=bid_list)
+
+    resolved_fmt = _infer_format(output, fmt)
+
+    if include_attrs:
+        attrs = load_attributes(dd, basin_ids=bid_list)
+        export_merged(data, attrs, output, fmt=resolved_fmt)
+    else:
+        export_timeseries(data, output, fmt=resolved_fmt)
+
+    console.print(f"[green]Exported {len(data)} basin(s) to {output}[/green]")

camelsch-0.1.0/src/camelsch/download.py

@@ -0,0 +1,110 @@
+"""Download and extract the CAMELS-CH dataset."""
+
+from __future__ import annotations
+
+import logging
+import shutil
+import zipfile
+from pathlib import Path
+from urllib.request import urlopen
+
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TransferSpeedColumn,
+)
+
+logger = logging.getLogger(__name__)
+
+CAMELS_CH_URL = "https://zenodo.org/api/records/15025258/files/camels_ch.zip/content"
+ZIP_FILENAME = "camels_ch.zip"
+EXTRACTED_DIR = "CAMELS_CH"
+
+
+def download_camels_ch(
+    dest: Path | str = Path("./data/CAMELS_CH"),
+    url: str = CAMELS_CH_URL,
+    force: bool = False,
+) -> Path:
+    """Download and extract CAMELS-CH. Returns path to extracted dir.
+
+    Args:
+        dest: Target directory for the extracted dataset.
+        url: URL to download from.
+        force: Re-download even if already exists.
+
+    Returns:
+        Path to the extracted dataset directory.
+    """
+    dest = Path(dest)
+
+    if dest.exists() and not force:
+        logger.debug("Dataset already exists at %s, skipping download", dest)
+        return dest
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    zip_path = dest.parent / ZIP_FILENAME
+
+    # Download with rich progress bar
+    if not zip_path.exists() or force:
+        logger.debug("Downloading CAMELS-CH from %s", url)
+        _download_with_progress(url, zip_path)
+
+    # Extract
+    _extract_and_rename(zip_path, dest)
+
+    # Clean up zip
+    zip_path.unlink(missing_ok=True)
+
+    return dest
+
+
+def _validate_zip_members(zf: zipfile.ZipFile, target: Path) -> None:
+    """Raise ValueError if any zip member would extract outside *target*."""
+    resolved = target.resolve()
+    for member in zf.namelist():
+        member_path = (target / member).resolve()
+        if not str(member_path).startswith(str(resolved) + "/") and member_path != resolved:
+            msg = f"Zip member {member!r} would escape target directory"
+            raise ValueError(msg)
+
+
+def _download_with_progress(url: str, zip_path: Path) -> None:
+    """Download a file with a rich progress bar."""
+    response = urlopen(url, timeout=30)
+    total = int(response.headers.get("Content-Length", 0))
+
+    with Progress(
+        TextColumn("[bold blue]{task.description}"),
+        BarColumn(),
+        DownloadColumn(),
+        TransferSpeedColumn(),
+    ) as progress:
+        task = progress.add_task("Downloading CAMELS-CH", total=total or None)
+        with open(zip_path, "wb") as f:
+            while chunk := response.read(8192):
+                f.write(chunk)
+                progress.update(task, advance=len(chunk))
+
+
+def _extract_and_rename(zip_path: Path, dest: Path) -> None:
+    """Extract zip and rename extracted folder to dest."""
+    extract_to = dest.parent
+    with zipfile.ZipFile(zip_path, "r") as zf:
+        _validate_zip_members(zf, extract_to)
+        zf.extractall(extract_to)
+
+    # Auto-detect extracted folder (starts with "camels" or "CAMELS")
+    for item in extract_to.iterdir():
+        if item.is_dir() and item.name.lower().startswith("camels") and item != dest:
+            if dest.exists():
+                shutil.rmtree(dest)
+            item.rename(dest)
+            return
+
+    # If extraction produced files directly (no subfolder), dest should already exist
+    if not dest.exists():
+        msg = f"Could not find extracted CAMELS-CH folder in {extract_to}"
+        raise FileNotFoundError(msg)

camelsch-0.1.0/src/camelsch/export.py

@@ -0,0 +1,85 @@
+"""Export time series and attributes to CSV/Parquet."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Literal
+
+import pandas as pd
+
+logger = logging.getLogger(__name__)
+
+Format = Literal["csv", "parquet"]
+
+
+def export_timeseries(
+    data: dict[str, pd.DataFrame],
+    output: Path,
+    fmt: Format = "csv",
+) -> None:
+    """Export time series dict to file(s).
+
+    For parquet: single file with ``basin_id`` column.
+    For CSV: single file if one basin, directory of files if multiple.
+    """
+    logger.debug("Exporting %d basin(s) as %s to %s", len(data), fmt, output)
+    if fmt == "parquet":
+        frames = []
+        for bid, df in data.items():
+            df = df.copy()
+            df.insert(0, "basin_id", bid)
+            frames.append(df)
+        combined = pd.concat(frames)
+        combined.to_parquet(output)
+    else:
+        if len(data) == 1:
+            bid, df = next(iter(data.items()))
+            df.to_csv(output)
+        else:
+            output.mkdir(parents=True, exist_ok=True)
+            for bid, df in data.items():
+                df.to_csv(output / f"basin_{bid}.csv")
+
+
+def export_attributes(
+    df: pd.DataFrame,
+    output: Path,
+    fmt: Format = "csv",
+) -> None:
+    """Export attributes DataFrame to file."""
+    if fmt == "parquet":
+        df.to_parquet(output)
+    else:
+        df.to_csv(output)
+
+
+def export_merged(
+    timeseries: dict[str, pd.DataFrame],
+    attributes: pd.DataFrame,
+    output: Path,
+    fmt: Format = "parquet",
+) -> None:
+    """Export merged timeseries + attributes as flat analysis-ready file.
+
+    Produces a dataset with columns: basin_id, date, <forcing_vars>, <target>, [<static_attrs>].
+    Static attributes are repeated for each row of a given basin.
+    """
+    logger.debug("Exporting merged data for %d basin(s) as %s to %s", len(timeseries), fmt, output)
+    frames = []
+    for bid, df in timeseries.items():
+        df = df.copy()
+        df.insert(0, "basin_id", bid)
+
+        if bid in attributes.index:
+            for col in attributes.columns:
+                df[col] = attributes.loc[bid, col]
+
+        frames.append(df)
+
+    combined = pd.concat(frames)
+
+    if fmt == "parquet":
+        combined.to_parquet(output)
+    else:
+        combined.to_csv(output)

camelsch-0.1.0/src/camelsch/io.py

@@ -0,0 +1,87 @@
+"""Shared I/O helpers for reading CAMELS-CH CSV files."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+def strip_units(name: str) -> str:
+    """Strip parenthesised unit suffixes from a column name.
+
+    Examples:
+        >>> strip_units("discharge_spec(mm/d)")
+        'discharge_spec'
+        >>> strip_units("temperature_mean(degC)")
+        'temperature_mean'
+        >>> strip_units("gauge_id")
+        'gauge_id'
+    """
+    return re.sub(r"\(.*?\)\s*$", "", name).strip()
+
+
+def read_csv_robust(filepath: Path, **kwargs: Any) -> pd.DataFrame:
+    """Read CSV trying utf-8, then latin-1 encoding. Handle comment lines."""
+    for encoding in ("utf-8", "latin-1"):
+        try:
+            df: pd.DataFrame = pd.read_csv(filepath, comment="#", encoding=encoding, **kwargs)
+            return df
+        except UnicodeDecodeError:
+            continue
+    msg = f"Could not decode {filepath} with utf-8 or latin-1"
+    raise ValueError(msg)
+
+
+def find_id_column(df: pd.DataFrame) -> str | None:
+    """Detect basin/gauge ID column from common names.
+
+    Examples:
+        >>> import pandas as pd
+        >>> find_id_column(pd.DataFrame({"gauge_id": [1], "value": [2]}))
+        'gauge_id'
+        >>> find_id_column(pd.DataFrame({"basin_id": [1], "value": [2]}))
+        'basin_id'
+        >>> find_id_column(pd.DataFrame({"x": [1], "y": [2]})) is None
+        True
+    """
+    candidates = ["gauge_id", "basin_id", "id", "ID", "station_id", "catchment_id"]
+    for name in candidates:
+        if name in df.columns:
+            return name
+    return None
+
+
+def find_date_column(df: pd.DataFrame) -> str | None:
+    """Detect date/time column from common names.
+
+    Examples:
+        >>> import pandas as pd
+        >>> find_date_column(pd.DataFrame({"date": ["2020-01-01"], "value": [1]}))
+        'date'
+        >>> find_date_column(pd.DataFrame({"timestamp": ["2020-01-01"]}))
+        'timestamp'
+        >>> find_date_column(pd.DataFrame({"x": [1]})) is None
+        True
+    """
+    candidates = ["date", "Date", "datetime", "time", "timestamp"]
+    for name in candidates:
+        if name in df.columns:
+            return name
+    return None
+
+
+def extract_basin_id(filepath: Path) -> str:
+    """Extract numeric basin ID from filename.
+
+    Expects filenames like ``CAMELS_CH_obs_based_2034.csv`` → ``"2034"``.
+
+    Examples:
+        >>> extract_basin_id(Path("CAMELS_CH_obs_based_2034.csv"))
+        '2034'
+        >>> extract_basin_id(Path("/data/timeseries/sim_2007.csv"))
+        '2007'
+    """
+    return filepath.stem.rsplit("_", 1)[-1]

camelsch-0.1.0/src/camelsch/timeseries.py

@@ -0,0 +1,164 @@
+"""Load and merge observation + simulation time series."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+import pandas as pd
+
+from camelsch.io import extract_basin_id, find_date_column, read_csv_robust, strip_units
+
+logger = logging.getLogger(__name__)
+
+
+def _read_ts_csv(path: Path) -> pd.DataFrame:
+    """Read a single time series CSV with encoding fallback and unit stripping."""
+    df = read_csv_robust(path)
+    df.columns = [strip_units(c) for c in df.columns]
+
+    date_col = find_date_column(df)
+    if date_col:
+        df[date_col] = pd.to_datetime(df[date_col])
+        if date_col != "date":
+            df = df.rename(columns={date_col: "date"})
+        df = df.set_index("date")
+
+    # Drop gauge_id column from data — it's redundant in per-basin files
+    if "gauge_id" in df.columns:
+        df = df.drop(columns=["gauge_id"])
+
+    return df
+
+
+def _add_aliases(df: pd.DataFrame) -> pd.DataFrame:
+    """Add convenience aliases: pet_sim -> pet, et_sim -> et."""
+    if "pet_sim" in df.columns and "pet" not in df.columns:
+        df["pet"] = df["pet_sim"]
+    if "et_sim" in df.columns and "et" not in df.columns:
+        df["et"] = df["et_sim"]
+    return df
+
+
+def _find_timeseries_dirs(data_dir: Path) -> tuple[Path | None, Path | None]:
+    """Find observation_based/ and simulation_based/ directories."""
+    ts_dir = data_dir / "timeseries"
+    obs_dir = ts_dir / "observation_based"
+    sim_dir = ts_dir / "simulation_based"
+    return (
+        obs_dir if obs_dir.exists() else None,
+        sim_dir if sim_dir.exists() else None,
+    )
+
+
+def list_basins(data_dir: str | Path) -> list[str]:
+    """List all available basin IDs from time series filenames."""
+    data_dir = Path(data_dir)
+    obs_dir, sim_dir = _find_timeseries_dirs(data_dir)
+
+    ids: set[str] = set()
+    for d in (obs_dir, sim_dir):
+        if d is not None:
+            for f in d.glob("*.csv"):
+                ids.add(extract_basin_id(f))
+    return sorted(ids)
+
+
+def list_variables(data_dir: str | Path) -> list[str]:
+    """List all available variable names from a sample basin."""
+    data_dir = Path(data_dir)
+    basin_ids = list_basins(data_dir)
+    if not basin_ids:
+        return []
+    sample = load_basin_timeseries(data_dir, basin_ids[0])
+    # Exclude aliases from the canonical list
+    return [c for c in sample.columns if c not in ("pet", "et")]
+
+
+def load_basin_timeseries(data_dir: str | Path, basin_id: str) -> pd.DataFrame:
+    """Load and merge obs + sim time series for one basin.
+
+    Args:
+        data_dir: Path to the extracted ``camels_ch`` directory.
+        basin_id: 4-digit FOEN gauge identifier (e.g. ``"2004"``).
+
+    Returns:
+        DataFrame with DatetimeIndex and all observation + simulation columns.
+    """
+    data_dir = Path(data_dir)
+    obs_dir, sim_dir = _find_timeseries_dirs(data_dir)
+
+    obs: pd.DataFrame | None = None
+    sim: pd.DataFrame | None = None
+
+    if obs_dir:
+        matches = list(obs_dir.glob(f"*_{basin_id}.csv"))
+        if matches:
+            obs = _read_ts_csv(matches[0])
+
+    if sim_dir:
+        matches = list(sim_dir.glob(f"*_{basin_id}.csv"))
+        if matches:
+            sim = _read_ts_csv(matches[0])
+
+    if obs is None and sim is None:
+        msg = f"No time series files found for basin {basin_id}"
+        raise FileNotFoundError(msg)
+
+    if obs is not None and sim is not None:
+        merged = obs.join(sim, how="outer")
+        logger.debug("Merged obs+sim for basin %s (%d rows)", basin_id, len(merged))
+    elif obs is not None:
+        merged = obs
+    else:
+        merged = sim  # both-None handled above
+
+    return _add_aliases(merged)
+
+
+def load_timeseries(
+    data_dir: str | Path,
+    basin_ids: list[str] | None = None,
+    variables: list[str] | None = None,
+    start_date: str | None = None,
+    end_date: str | None = None,
+) -> dict[str, pd.DataFrame]:
+    """Load time series for multiple basins with optional filtering.
+
+    Args:
+        data_dir: Path to the extracted ``camels_ch`` directory.
+        basin_ids: List of basin IDs to load. If ``None``, loads all.
+        variables: Variables to include. If ``None``, includes all.
+        start_date: Start date filter (YYYY-MM-DD).
+        end_date: End date filter (YYYY-MM-DD).
+
+    Returns:
+        Dict mapping basin ID to its merged time series DataFrame.
+    """
+    data_dir = Path(data_dir)
+
+    if basin_ids is None:
+        basin_ids = list_basins(data_dir)
+        if not basin_ids:
+            msg = f"No time series files found in {data_dir / 'timeseries'}"
+            raise FileNotFoundError(msg)
+
+    result: dict[str, pd.DataFrame] = {}
+    for bid in basin_ids:
+        df = load_basin_timeseries(data_dir, bid)
+
+        if start_date:
+            df = df.loc[start_date:]  # type: ignore[misc]
+        if end_date:
+            df = df.loc[:end_date]  # type: ignore[misc]
+        if variables:
+            # Also include aliases if the base variable is requested
+            cols = []
+            for v in variables:
+                if v in df.columns:
+                    cols.append(v)
+            df = df[cols] if cols else df
+
+        result[bid] = df
+
+    return result