Skip to content

CAMELS-FR

Overview

CAMELS-FR is the France hydrological dataset implementation. French CAMELS dataset for diverse catchments across France.

Dataset Information

  • Region: France
  • Module: hydrodataset.camels_fr
  • Class: CamelsFr

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

 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_fr import CamelsFr
from hydrodataset import SETTING

# Initialize dataset
data_path = SETTING["local_data_path"]["datasets-origin"]
ds = CamelsFr(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", "era5land"),  # Specify ERA5-Land source
        "streamflow"  # Use default source
    ]
)

API Reference

hydrodataset.camels_fr.CamelsFr

Bases: HydroDataset

CAMELS_FR dataset class extending RainfallRunoff.

This class provides access to the CAMELS_FR dataset, which contains hourly hydrological and meteorological data for various watersheds.

Attributes:

Name Type Description
region

Geographic region identifier
download

Whether to download data automatically
ds_description

Dictionary containing dataset file paths
Source code in hydrodataset/camels_fr.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
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
class CamelsFr(HydroDataset):
    """CAMELS_FR dataset class extending RainfallRunoff.

    This class provides access to the CAMELS_FR dataset, which contains hourly
    hydrological and meteorological data for various watersheds.

    Attributes:
        region: Geographic region identifier
        download: Whether to download data automatically
        ds_description: Dictionary containing dataset file paths
    """

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

        Args:
            data_path: Path to the CAMELS_FR data directory
            region: Geographic region identifier (optional)
            download: Whether to download data automatically (default: False)
            cache_path: Path to the cache directory
        """
        super().__init__(data_path, cache_path=cache_path)
        self.region = region
        self.download = download
        try:
            self.aqua_fetch = CAMELS_FR(data_path)
        except Exception as e:
            print(e)
            check_zip_extract = False
            # The zip files that should be downloaded for CAMELS-CH
            zip_files = [
                "ADDITIONAL_LICENSES.zip",
                "CAMELS_FR_attributes.zip",
                "CAMELS_FR_geography.zip",
                "CAMELS_FR_time_series.zip",
            ]
            for filename in tqdm(zip_files, desc="Checking zip files"):
                # The extracted directory name (without .zip extension)
                extracted_dir = self.data_source_dir.joinpath(
                    "CAMELS_FR", filename[:-4]
                )
                if not extracted_dir.exists():
                    check_zip_extract = True
                    break
            if check_zip_extract:
                hydro_file.zip_extract(self.data_source_dir.joinpath("CAMELS_FR"))
            self.aqua_fetch = CAMELS_FR(data_path)

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

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

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

    def cache_attributes_xrdataset(self):
        """Override base method to add calculated p_mean from precipitation timeseries.

        This method:
        1. Calls parent method to create base attribute cache
        2. Reads precipitation timeseries data
        3. Calculates mean precipitation (p_mean) for each basin
        4. Adds p_mean to the attribute dataset
        5. Saves the updated cache
        """
        # Step 1: Create base attribute cache using parent method
        print("Creating base attribute cache...")
        super().cache_attributes_xrdataset()

        # Step 2: Load the base cache file
        cache_file = self.cache_dir.joinpath(self._attributes_cache_filename)
        with xr.open_dataset(cache_file) as ds_attr:
            ds_attr = ds_attr.load()  # Load into memory

        print("Calculating p_mean from precipitation timeseries...")

        # Step 3: Read precipitation timeseries for all basins
        basin_ids = self.read_object_ids().tolist()

        try:
            # Read full precipitation timeseries
            prcp_ts = self.read_ts_xrdataset(
                gage_id_lst=basin_ids,
                t_range=self.default_t_range,
                var_lst=["precipitation"],
            )

            # Step 4: Calculate temporal mean for each basin
            p_mean_values = prcp_ts["precipitation"].mean(dim="time")

            # Add units attribute
            p_mean_values.attrs["units"] = "mm/day"
            p_mean_values.attrs["description"] = (
                "Mean daily precipitation (calculated from timeseries)"
            )

            # Step 5: Add p_mean to the attribute dataset
            ds_attr["p_mean"] = p_mean_values

            print(f"Successfully calculated p_mean for {len(basin_ids)} basins")

        except Exception as e:
            print(f"Warning: Could not calculate p_mean from precipitation data: {e}")
            print("Creating p_mean with NaN values as placeholder")
            # Create p_mean with NaN values if calculation fails
            p_mean_nan = xr.DataArray(
                np.full(len(basin_ids), np.nan),
                coords={"basin": basin_ids},
                dims=["basin"],
                attrs={
                    "units": "mm/day",
                    "description": "Mean daily precipitation (not available)",
                },
            )
            ds_attr["p_mean"] = p_mean_nan

        # Step 6: Save the updated cache file
        print(f"Saving updated attribute cache with p_mean to: {cache_file}")
        ds_attr.to_netcdf(cache_file, mode="w")
        print("Successfully saved attribute cache with p_mean")

    # get the information of features from dataset file"CAMELS-FR_description"
    _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"},
        "elev_mean": {"specific_name": "elev_mean", "unit": "m"},
        "pet_mean": {"specific_name": "pet_mean", "unit": "mm/day"},
    }

    _dynamic_variable_mapping = {
        StandardVariable.STREAMFLOW: {
            "default_source": "hydroportail",
            "sources": {
                "hydroportail": {"specific_name": "q_cms_obs", "unit": "L/s"},
                "camelsfr": {"specific_name": "q_mm_obs", "unit": "mm/day"},
            },
        },
        StandardVariable.PRECIPITATION: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "pcp_mm", "unit": "mm/day"},
            },
        },
        StandardVariable.TEMPERATURE_MEAN: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "airtemp_C_mean", "unit": "°C"},
            },
        },
        StandardVariable.TEMPERATURE_MIN: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "airtemp_C_min", "unit": "°C"},
            },
        },
        StandardVariable.TEMPERATURE_MAX: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "airtemp_C_max", "unit": "°C"},
            },
        },
        StandardVariable.POTENTIAL_EVAPOTRANSPIRATION: {
            "default_source": "oudin",
            "sources": {
                "oudin": {"specific_name": "pet_mm_ou", "unit": "mm/day"},
                "penman": {"specific_name": "pet_mm_pe", "unit": "mm/day"},
                "penman_monteith": {"specific_name": "pet_mm_pm", "unit": "mm/day"},
            },
        },
        StandardVariable.WIND_SPEED: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "windspeed_mps", "unit": "m/s"},
            },
        },
        StandardVariable.SOLAR_RADIATION: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "solrad_wm2", "unit": "J/cm^2"},
            },
        },
        StandardVariable.LONGWAVE_SOLAR_RADIATION: {
            "default_source": "SIM2-SAFRAN",
            "sources": {
                "SIM2-SAFRAN": {"specific_name": "lwdownrad_wm2", "unit": "J/cm^2"},
            },
        },
        StandardVariable.SNOW_WATER_EQUIVALENT: {
            "default_source": "isba_model",
            "sources": {
                "isba_model": {"specific_name": "tsd_swe_isba", "unit": "mm/day"},
            },
        },
        StandardVariable.SOIL_MOISTURE: {
            "default_source": "gr",
            "sources": {
                "gr": {"specific_name": "tsd_swi_gr", "unit": "mm/day"},
                "isba": {"specific_name": "tsd_swi_isba", "unit": "mm/day"},
            },
        },      
        StandardVariable.SPECIFIC_HUMIDITY: {
            "default_source": "isba_model",
            "sources": {
                "isba_model": {"specific_name": "spechum_gkg", "unit": "mm/day"},
            },
        },
    }

default_t_range property

__init__(data_path, region=None, download=False, cache_path=None)

Initialize CAMELS_FR dataset.

Parameters:

Name Type Description Default
data_path str

Path to the CAMELS_FR data directory

 required
region Optional[str]

Geographic region identifier (optional)

 None
download bool

Whether to download data automatically (default: False)

 False
cache_path Optional[str]

Path to the cache directory

 None
Source code in hydrodataset/camels_fr.py 
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
def __init__(
    self,
    data_path: str,
    region: Optional[str] = None,
    download: bool = False,
    cache_path: Optional[str] = None,
) -> None:
    """Initialize CAMELS_FR dataset.

    Args:
        data_path: Path to the CAMELS_FR data directory
        region: Geographic region identifier (optional)
        download: Whether to download data automatically (default: False)
        cache_path: Path to the cache directory
    """
    super().__init__(data_path, cache_path=cache_path)
    self.region = region
    self.download = download
    try:
        self.aqua_fetch = CAMELS_FR(data_path)
    except Exception as e:
        print(e)
        check_zip_extract = False
        # The zip files that should be downloaded for CAMELS-CH
        zip_files = [
            "ADDITIONAL_LICENSES.zip",
            "CAMELS_FR_attributes.zip",
            "CAMELS_FR_geography.zip",
            "CAMELS_FR_time_series.zip",
        ]
        for filename in tqdm(zip_files, desc="Checking zip files"):
            # The extracted directory name (without .zip extension)
            extracted_dir = self.data_source_dir.joinpath(
                "CAMELS_FR", filename[:-4]
            )
            if not extracted_dir.exists():
                check_zip_extract = True
                break
        if check_zip_extract:
            hydro_file.zip_extract(self.data_source_dir.joinpath("CAMELS_FR"))
        self.aqua_fetch = CAMELS_FR(data_path)