Skip to content

CAMELS-PE

Overview

CAMELS-PE is the Peru hydrological dataset implementation, providing CAMELS-style daily hydrometeorological time series and catchment attributes for 136 catchments in Peru (Llauca et al., 2026).

Dataset Information

  • Region: Peru
  • Module: hydrodataset.camels_pe
  • Class: CamelsPe
  • Backend: aqua_fetch.CAMELS_PE (available since aqua-fetch 1.1.0)
  • Download source: Zenodo 21195425 (~121 MB)

Features

Static Attributes

Static catchment attributes include: - Basin area - Mean precipitation - Topographic characteristics - Land cover information - Soil properties - Geological and human-intervention attributes - Gauge metadata (name, region, record period)

Dynamic Variables

Timeseries variables available: - Streamflow (observed) - Precipitation - Temperature (min, max, mean) - Potential evapotranspiration - Solar radiation - Vapor pressure

Usage

Basic Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
from hydrodataset.camels_pe import CamelsPe
from hydrodataset import resolve_data_path

# Initialize dataset (first access triggers a ~121 MB download)
data_path = resolve_data_path("camels_pe")
ds = CamelsPe(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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
# 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:

1
2
3
4
5
6
7
8
9
# 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", "pisco"),  # Specify PISCO source
        "streamflow"  # Use default source
    ]
)

API Reference

hydrodataset.camels_pe.CamelsPe

Bases: HydroDataset

CAMELS-PE dataset reader.

Thin wrapper over the aqua_fetch CAMELS_PE class (available since aqua-fetch 1.1.0). Data is downloaded/extracted by aqua_fetch to {root}/CAMELS_PE/CAMELS-PE_v1.0.1/CAMELS-PE/... and cached locally as camels_pe_attributes.nc / camels_pe_timeseries.nc via the base HydroDataset cache methods.

Cloud (S3/zarr) support is handled by the base class cache_*_to_zarr.

Source code in hydrodataset/camels_pe.py 
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
class CamelsPe(HydroDataset):
    """CAMELS-PE dataset reader.

    Thin wrapper over the aqua_fetch ``CAMELS_PE`` class (available since
    aqua-fetch 1.1.0). Data is downloaded/extracted by aqua_fetch to
    ``{root}/CAMELS_PE/CAMELS-PE_v1.0.1/CAMELS-PE/...`` and cached locally as
    ``camels_pe_attributes.nc`` / ``camels_pe_timeseries.nc`` via the base
    ``HydroDataset`` cache methods.

    Cloud (S3/zarr) support is handled by the base class ``cache_*_to_zarr``.
    """

    def __init__(
        self, uri: str, region: Optional[str] = None, download: bool = False
    ) -> None:
        super().__init__(uri)
        self.region = region
        self.download = download
        if not str(uri).startswith("s3://"):
            self.aqua_fetch = CAMELS_PE(uri)

    def get_name(self):
        return "CAMELS_PE"

    def set_data_source_describe(self):
        root = os.path.join(
            str(self.data_source_dir), "CAMELS_PE", "CAMELS-PE_v1.0.1", "CAMELS-PE"
        )
        return {
            "metadata": os.path.join(root, "01_metadata"),
            "attributes": os.path.join(root, "02_attributes"),
            "timeseries": os.path.join(root, "03_timeseries"),
        }

    def download_data_source(self):
        if not hasattr(self, "aqua_fetch"):
            raise NotImplementedError("cloud download is not supported; use cache_*_to_zarr")
        self.aqua_fetch._download_camels_pe(overwrite=True)

    def read_object_ids(self) -> np.ndarray:
        """Read station IDs.

        Local: delegate to the aqua_fetch wrapper's ``stations()``. Cloud (S3):
        read ``stations.csv`` from the metadata dir directly (no aqua_fetch).
        """
        if not self._is_cloud():
            if hasattr(self, "aqua_fetch"):
                return np.sort(np.array(self.aqua_fetch.stations()))
            raise NotImplementedError
        fs = self._make_s3fs()
        rel = "CAMELS_PE/CAMELS-PE_v1.0.1/CAMELS-PE/01_metadata/stations.csv"
        uri = str(self.data_source_dir).rstrip("/")
        with fs.open(f"{uri}/{rel}".removeprefix("s3://")) as fh:
            stations = pd.read_csv(fh, dtype={"gauge_id": str})
        return np.sort(stations["gauge_id"].astype(str).to_numpy())

    def read_target_cols(
        self,
        object_ids=None,
        t_range_list=None,
        target_cols=None,
        gage_id_lst=None,
        t_range=None,
        **kwargs,
    ) -> np.ndarray:
        if object_ids is None:
            object_ids = gage_id_lst
        if t_range_list is None:
            t_range_list = t_range
        if target_cols is None:
            target_cols = ["streamflow"]
        ds = self.read_ts_xrdataset(
            gage_id_lst=object_ids,
            t_range=t_range_list,
            var_lst=target_cols,
            **kwargs,
        )
        return ds.to_array().transpose("basin", "time", "variable").values

    def read_relevant_cols(
        self,
        object_ids=None,
        t_range_list=None,
        relevant_cols=None,
        gage_id_lst=None,
        t_range=None,
        var_lst=None,
        forcing_type=None,
        **kwargs,
    ) -> np.ndarray:
        if object_ids is None:
            object_ids = gage_id_lst
        if t_range_list is None:
            t_range_list = t_range
        if relevant_cols is None:
            relevant_cols = var_lst
        ds = self.read_ts_xrdataset(
            gage_id_lst=object_ids,
            t_range=t_range_list,
            var_lst=relevant_cols,
            **kwargs,
        )
        return ds.to_array().transpose("basin", "time", "variable").values

    def read_constant_cols(
        self,
        object_ids=None,
        constant_cols=None,
        gage_id_lst=None,
        var_lst=None,
        **kwargs,
    ) -> np.ndarray:
        if object_ids is None:
            object_ids = gage_id_lst
        if constant_cols is None:
            constant_cols = var_lst
        ds = self.read_attr_xrdataset(
            gage_id_lst=object_ids,
            var_lst=constant_cols,
            **kwargs,
        )
        return ds.to_array().transpose("basin", "variable").values

    @property
    def _attributes_cache_filename(self):
        return "camels_pe_attributes.nc"

    @property
    def _timeseries_cache_filename(self):
        return "camels_pe_timeseries.nc"

    @property
    def default_t_range(self):
        return ["1981-01-01", "2025-12-31"]

    _subclass_static_definitions = {
        "p_mean": {"specific_name": "p_mean", "unit": "mm/day"},
        "area": {"specific_name": "area_km2", "unit": "km^2"},
        "gauge_lat": {"specific_name": "lat", "unit": "degree"},
        "gauge_lon": {"specific_name": "long", "unit": "degree"},
        "gauge_elev": {"specific_name": "elev_gauge_m", "unit": "m"},
        "elev_mean": {"specific_name": "elev_catch_m", "unit": "m"},
        "pet_mean": {"specific_name": "pet_mean", "unit": "mm/day"},
        "q_mean": {"specific_name": "q_mean", "unit": "mm/day"},
    }

    _dynamic_variable_mapping = {
        StandardVariable.STREAMFLOW: {
            "default_source": "observations",
            # NOTE: aqua-fetch 1.1.0 exposes only observed streamflow
            # (q_mm_obs); model-simulated flow_sim is intentionally dropped.
            "sources": {
                "observations": {"specific_name": "q_mm_obs", "unit": "mm/day"},
            },
        },
        StandardVariable.PRECIPITATION: {
            "default_source": "pisco",
            "sources": {
                "pisco": {"specific_name": "pcp_mm", "unit": "mm/day"},
            },
        },
        StandardVariable.POTENTIAL_EVAPOTRANSPIRATION: {
            "default_source": "pisco",
            "sources": {
                "pisco": {"specific_name": "pet_mm", "unit": "mm/day"},
            },
        },
        StandardVariable.TEMPERATURE_MIN: {
            "default_source": "pisco",
            "sources": {
                "pisco": {"specific_name": "airtemp_c_min", "unit": "degC"},
            },
        },
        StandardVariable.TEMPERATURE_MEAN: {
            "default_source": "pisco",
            "sources": {
                "pisco": {"specific_name": "airtemp_c_mean", "unit": "degC"},
            },
        },
        StandardVariable.TEMPERATURE_MAX: {
            "default_source": "pisco",
            "sources": {
                "pisco": {"specific_name": "airtemp_c_max", "unit": "degC"},
            },
        },
        StandardVariable.SOLAR_RADIATION: {
            "default_source": "era5_land",
            "sources": {
                "era5_land": {"specific_name": "srad", "unit": "MJ/m^2/day"},
            },
        },
        StandardVariable.VAPOR_PRESSURE: {
            "default_source": "era5_land",
            "sources": {
                "era5_land": {"specific_name": "vp_hpa", "unit": "hPa"},
            },
        },
    }

default_t_range property

__init__(uri, region=None, download=False)

Source code in hydrodataset/camels_pe.py 
23
24
25
26
27
28
29
30
def __init__(
    self, uri: str, region: Optional[str] = None, download: bool = False
) -> None:
    super().__init__(uri)
    self.region = region
    self.download = download
    if not str(uri).startswith("s3://"):
        self.aqua_fetch = CAMELS_PE(uri)

read_object_ids()

Read station IDs.

Local: delegate to the aqua_fetch wrapper's stations(). Cloud (S3): read stations.csv from the metadata dir directly (no aqua_fetch).

Source code in hydrodataset/camels_pe.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
def read_object_ids(self) -> np.ndarray:
    """Read station IDs.

    Local: delegate to the aqua_fetch wrapper's ``stations()``. Cloud (S3):
    read ``stations.csv`` from the metadata dir directly (no aqua_fetch).
    """
    if not self._is_cloud():
        if hasattr(self, "aqua_fetch"):
            return np.sort(np.array(self.aqua_fetch.stations()))
        raise NotImplementedError
    fs = self._make_s3fs()
    rel = "CAMELS_PE/CAMELS-PE_v1.0.1/CAMELS-PE/01_metadata/stations.csv"
    uri = str(self.data_source_dir).rstrip("/")
    with fs.open(f"{uri}/{rel}".removeprefix("s3://")) as fh:
        stations = pd.read_csv(fh, dtype={"gauge_id": str})
    return np.sort(stations["gauge_id"].astype(str).to_numpy())

read_constant_cols(object_ids=None, constant_cols=None, gage_id_lst=None, var_lst=None, **kwargs)

Source code in hydrodataset/camels_pe.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
def read_constant_cols(
    self,
    object_ids=None,
    constant_cols=None,
    gage_id_lst=None,
    var_lst=None,
    **kwargs,
) -> np.ndarray:
    if object_ids is None:
        object_ids = gage_id_lst
    if constant_cols is None:
        constant_cols = var_lst
    ds = self.read_attr_xrdataset(
        gage_id_lst=object_ids,
        var_lst=constant_cols,
        **kwargs,
    )
    return ds.to_array().transpose("basin", "variable").values

read_relevant_cols(object_ids=None, t_range_list=None, relevant_cols=None, gage_id_lst=None, t_range=None, var_lst=None, forcing_type=None, **kwargs)

Source code in hydrodataset/camels_pe.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def read_relevant_cols(
    self,
    object_ids=None,
    t_range_list=None,
    relevant_cols=None,
    gage_id_lst=None,
    t_range=None,
    var_lst=None,
    forcing_type=None,
    **kwargs,
) -> np.ndarray:
    if object_ids is None:
        object_ids = gage_id_lst
    if t_range_list is None:
        t_range_list = t_range
    if relevant_cols is None:
        relevant_cols = var_lst
    ds = self.read_ts_xrdataset(
        gage_id_lst=object_ids,
        t_range=t_range_list,
        var_lst=relevant_cols,
        **kwargs,
    )
    return ds.to_array().transpose("basin", "time", "variable").values

read_target_cols(object_ids=None, t_range_list=None, target_cols=None, gage_id_lst=None, t_range=None, **kwargs)

Source code in hydrodataset/camels_pe.py 
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def read_target_cols(
    self,
    object_ids=None,
    t_range_list=None,
    target_cols=None,
    gage_id_lst=None,
    t_range=None,
    **kwargs,
) -> np.ndarray:
    if object_ids is None:
        object_ids = gage_id_lst
    if t_range_list is None:
        t_range_list = t_range
    if target_cols is None:
        target_cols = ["streamflow"]
    ds = self.read_ts_xrdataset(
        gage_id_lst=object_ids,
        t_range=t_range_list,
        var_lst=target_cols,
        **kwargs,
    )
    return ds.to_array().transpose("basin", "time", "variable").values