CAMELS-NZ¶

Overview¶

CAMELS-NZ is the New Zealand hydrological dataset implementation. New Zealand CAMELS dataset covering diverse climates from subtropical to alpine.

Dataset Information¶

Region: New Zealand
Module: hydrodataset.camels_nz
Class: CamelsNz

Features¶

Static Attributes¶

Static catchment attributes include: - Basin area - Mean precipitation - Topographic characteristics - Land cover information - Soil properties - Climate indices

Dynamic Variables¶

Timeseries variables available (varies by dataset): - Streamflow - Precipitation - Temperature (min, max, mean) - Potential evapotranspiration - Solar radiation - And more...

Usage¶

Basic Usage¶

from hydrodataset.camels_nz import CamelsNz
from hydrodataset import SETTING

# Initialize dataset
data_path = SETTING["local_data_path"]["datasets-origin"]
ds = CamelsNz(data_path)

# Get basin IDs
basin_ids = ds.read_object_ids()
print(f"Number of basins: {len(basin_ids)}")

# Check available features
print("Static features:", ds.available_static_features)
print("Dynamic features:", ds.available_dynamic_features)

# Read timeseries data
timeseries = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:5],
    t_range=ds.default_t_range,
    var_lst=["streamflow", "precipitation"]
)
print(timeseries)

# Read attribute data
attributes = ds.read_attr_xrdataset(
    gage_id_lst=basin_ids[:5],
    var_lst=["area", "p_mean"]
)
print(attributes)

Reading Specific Variables¶

# Read with specific time range
ts_data = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:10],
    t_range=["1990-01-01", "1995-12-31"],
    var_lst=["streamflow", "precipitation", "temperature_mean"]
)

# Read basin area
areas = ds.read_area(gage_id_lst=basin_ids[:10])

# Read mean precipitation
mean_precip = ds.read_mean_prcp(gage_id_lst=basin_ids[:10])

Data Sources¶

The dataset supports multiple data sources for certain variables. Check the class documentation for available sources and use tuple notation to specify:

# Request specific data source
ts_data = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:5],
    t_range=["1990-01-01", "1995-12-31"],
    var_lst=[
        ("precipitation", "era5land"),  # Specify ERA5-Land source
        "streamflow"  # Use default source
    ]
)

API Reference¶

`hydrodataset.camels_nz.CamelsNz` ¶

Bases: HydroDataset

CAMELS_NZ dataset class.

This class uses a custom data reading implementation to support a newer dataset version than the one supported by the underlying aquafetch library. It overrides the download URLs and provides its own parsing and caching logic.

The dataset supports both hourly ('H') and daily ('D') timesteps.

Attributes:

Name	Type	Description
`region`		Geographic region identifier
`download`		Whether to download data automatically
`timestep`		Time step for the data ('H' for hourly, 'D' for daily)

Source code in hydrodataset/camels_nz.py

class CamelsNz(HydroDataset):
    """CAMELS_NZ dataset class.

    This class uses a custom data reading implementation to support a newer
    dataset version than the one supported by the underlying aquafetch library.
    It overrides the download URLs and provides its own parsing and caching logic.

    The dataset supports both hourly ('H') and daily ('D') timesteps.

    Attributes:
        region: Geographic region identifier
        download: Whether to download data automatically
        timestep: Time step for the data ('H' for hourly, 'D' for daily)
    """

    def __init__(
        self,
        data_path: str,
        region: Optional[str] = None,
        download: bool = False,
        timestep: str = "H",
    ) -> None:
        """Initialize CAMELS_NZ dataset.

        Args:
            data_path: Path to the CAMELS_NZ data directory
            region: Geographic region identifier (optional)
            download: Whether to download data automatically (default: False)
            timestep: Time step for the data ('H' for hourly, 'D' for daily, default: 'H')
        """
        super().__init__(data_path)
        self.region = "NZ" if region is None else region
        self.download = download
        self.timestep = timestep

        # Instantiate our custom CAMELS_NZ class with timestep support
        self.aqua_fetch = CAMELS_NZ(data_path, timestep=timestep)

    @property
    def _attributes_cache_filename(self):
        return f"camels_nz_{self.timestep.lower()}_attributes.nc"

    @property
    def _timeseries_cache_filename(self):
        return f"camels_nz_{self.timestep.lower()}_timeseries.nc"

    @property
    def default_t_range(self):
        return ["1972-01-01", "2024-08-02"]

    # Static variable definitions for CAMELS-NZ
    # Note: specific_name should be the cleaned version (lowercase, no spaces)
    # as stored in the cache file after _clean_feature_names() processing
    _subclass_static_definitions = {
        "area": {"specific_name": "area_km2", "unit": "km^2"},
        "p_mean": {"specific_name": "meanannualrainfall", "unit": "mm"},
    }

    # Dynamic variable mapping for CAMELS-NZ
    _dynamic_variable_mapping = {
        StandardVariable.STREAMFLOW: {
            "default_source": "obs",
            "sources": {"obs": {"specific_name": "q_cms_obs", "unit": "m^3/s"}},
        },
        StandardVariable.PRECIPITATION: {
            "default_source": "default",
            "sources": {"default": {"specific_name": "pcp_mm", "unit": "mm/day"}},
        },
        StandardVariable.TEMPERATURE_MEAN: {
            "default_source": "default",
            "sources": {"default": {"specific_name": "airtemp_c_mean", "unit": "°C"}},
        },
        StandardVariable.POTENTIAL_EVAPOTRANSPIRATION: {
            "default_source": "default",
            "sources": {"default": {"specific_name": "pet_mm", "unit": "mm/day"}},
        },
        StandardVariable.RELATIVE_HUMIDITY: {
            "default_source": "default",
            "sources": {"default": {"specific_name": "rh_", "unit": "%"}},
        },
    }

`default_t_range` `property` ¶

`init(data_path, region=None, download=False, timestep='H')` ¶

Initialize CAMELS_NZ dataset.

Parameters:

Name	Type	Description	Default
`data_path`	`str`	Path to the CAMELS_NZ data directory	required
`region`	`Optional[str]`	Geographic region identifier (optional)	`None`
`download`	`bool`	Whether to download data automatically (default: False)	`False`
`timestep`	`str`	Time step for the data ('H' for hourly, 'D' for daily, default: 'H')	`'H'`