CAMELSH-KR¶

Overview¶

CAMELSH-KR is the South Korea hourly hydrological dataset. Hourly resolution hydrological dataset for South Korean catchments with monsoon climate characteristics.

Dataset Information¶

Region: South Korea
Temporal Resolution: Hourly
Module: hydrodataset.camelsh_kr
Class: CamelshKr

Key Features¶

Hourly Resolution¶

Unlike daily CAMELS datasets, CAMELSH provides hourly timeseries data, enabling: - Sub-daily hydrological process analysis - Flash flood and storm event studies - High-frequency streamflow dynamics - Detailed precipitation event analysis

Static Attributes¶

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

Dynamic Variables¶

Hourly timeseries variables available: - Streamflow (hourly) - Precipitation (hourly) - Temperature - Potential evapotranspiration - Solar radiation - And more...

Usage¶

Basic Usage¶

from hydrodataset.camelsh_kr import CamelshKr
from hydrodataset import SETTING

# Initialize dataset
data_path = SETTING["local_data_path"]["datasets-origin"]
ds = CamelshKr(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 hourly timeseries data
timeseries = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:5],
    t_range=["2015-01-01", "2015-01-31"],  # One month of hourly data
    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)

Analyzing Storm Events¶

# Read hourly data for a specific storm event
storm_data = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:3],
    t_range=["2015-06-15 00:00:00", "2015-06-20 23:00:00"],
    var_lst=["streamflow", "precipitation", "temperature_mean"]
)

# Analyze sub-daily patterns
import xarray as xr
hourly_precip = storm_data["precipitation"]
daily_total = hourly_precip.resample(time="1D").sum()
print("Daily precipitation totals:", daily_total)

Reading Specific Variables¶

# Read with specific time range (note hourly timestamps)
ts_data = ds.read_ts_xrdataset(
    gage_id_lst=basin_ids[:10],
    t_range=["2015-01-01 00:00:00", "2015-12-31 23:00:00"],
    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 Considerations¶

Large Data Volumes¶

Hourly data results in significantly larger datasets compared to daily data: - 24x more data points per day - Larger cache files - Longer initial cache generation time

Time Range Selection¶

When working with hourly data:

# Specify full datetime for hourly data
t_range = ["2015-01-01 00:00:00", "2015-01-31 23:00:00"]

# Or use date strings (defaults to 00:00:00)
t_range = ["2015-01-01", "2015-01-31"]

API Reference¶

`hydrodataset.camelsh_kr.CamelshKr` ¶

Bases: HydroDataset

CAMELSH_KR dataset class extending RainfallRunoff.

This class provides access to the CAMELSH_KR 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/camelsh_kr.py

class CamelshKr(HydroDataset):
    """CAMELSH_KR dataset class extending RainfallRunoff.

    This class provides access to the CAMELSH_KR 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 CAMELSH_KR dataset.

        Args:
            data_path: Path to the CAMELSH_KR 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
        # In aqua_fetch, CAMELS_SK is the alias of CAMELSH_KR
        self.aqua_fetch = CAMELS_SK(data_path)

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

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

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

    # not find information of features
    _subclass_static_definitions = {
        "p_mean": {"specific_name": "p_mean", "unit": "mm/day"},
        "area": {"specific_name": "area_km2", "unit": "km^2"},
    }

    _dynamic_variable_mapping = {
        StandardVariable.STREAMFLOW: {
            "default_source": "obs",
            "sources": {
                "obs": {"specific_name": "q_cms_obs", "unit": "m^3/s"},
            },
        },
        StandardVariable.WATER_LEVEL: {
            "default_source": "obs",
            "sources": {
                "obs": {"specific_name": "water_level", "unit": "m"},
            },
        },
        StandardVariable.PRECIPITATION: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "total_precipitation", "unit": "mm/day"},
                "obs": {"specific_name": "precip_obs", "unit": "mm/day"},
            },
        },
        StandardVariable.TEMPERATURE_MEAN: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "temperature_2m", "unit": "°C"},
                "obs": {"specific_name": "air_temp_obs", "unit": "°C"},
                "dewpoint": {"specific_name": "dewpoint_temperature_2m", "unit": "°C"},
            },
        },
        StandardVariable.VAPOR_PRESSURE: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "dewpoint_temperature_2m", "unit": "°C"},
            },
        },
        StandardVariable.SNOW_DEPTH: {
            "default_source": "era5_depth",
            "sources": {
                "era5_depth": {"specific_name": "snow_depth", "unit": "m"},
            },
        },
        StandardVariable.SNOW_COVER: {
            "default_source": "era5_cover",
            "sources": {
                "era5_cover": {"specific_name": "snow_cover", "unit": "fraction"},
            },
        },
        StandardVariable.POTENTIAL_EVAPOTRANSPIRATION: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "potential_evaporation", "unit": "mm/day"},
            },
        },
        StandardVariable.U_WIND_SPEED: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "u_component_of_wind_10m", "unit": "m/s"},
            },
        },
        StandardVariable.V_WIND_SPEED: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "v_component_of_wind_10m", "unit": "m/s"},
            },
        },
        StandardVariable.WIND_SPEED: {
            "default_source": "obs_speed",
            "sources": {
                "obs_speed": {"specific_name": "wind_sp_obs", "unit": "m/s"},
            },
        },
        StandardVariable.WIND_DIR: {
            "default_source": "obs_dir",
            "sources": {
                "obs_dir": {"specific_name": "wind_dir_obs", "unit": "degree"},
            },
        },
        StandardVariable.SURFACE_PRESSURE: {
            "default_source": "era5",
            "sources": {
                "era5": {"specific_name": "surface_pressure", "unit": "Pa"},
            },
        },
        StandardVariable.THERMAL_RADIATION: {
            "default_source": "era5",
            "sources": {
                "era5": {
                    "specific_name": "surface_net_thermal_radiation",
                    "unit": "W/m^2",
                },
            },
        },
        StandardVariable.SOLAR_RADIATION: {
            "default_source": "era5",
            "sources": {
                "era5": {
                    "specific_name": "surface_net_solar_radiation",
                    "unit": "W/m^2",
                },
            },
        },
    }

`default_t_range` `property` ¶

`init(data_path, region=None, download=False, cache_path=None)` ¶

Initialize CAMELSH_KR dataset.

Parameters:

Name	Type	Description	Default
`data_path`	`str`	Path to the CAMELSH_KR 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`