Swim Package (swimrs.swim)¶
Configuration parsing and helpers for SWIM-RS projects.
ProjectConfig
¶
Configuration manager for SWIM-RS projects.
Loads and resolves project configuration from TOML files, handling path resolution, parameter validation, and mode-specific setup for calibration and forecasting workflows.
Attributes:
| Name | Type | Description |
|---|---|---|
project_name |
Name of the project from TOML config. |
|
root_path |
Resolved root directory path. |
|
project_ws |
Project workspace directory. |
|
fields_shapefile |
Path to the fields geometry shapefile. |
|
start_dt |
Simulation start date. |
|
end_dt |
Simulation end date. |
|
calibrate |
Whether calibration mode is enabled. |
|
forecast |
Whether forecast mode is enabled. |
|
met_source |
Meteorology data source ('gridmet' or 'era5'). |
|
runoff_process |
Runoff method ('cn' for Curve Number, 'ier' for infiltration-excess). |
Example
config = ProjectConfig() config.read_config("project.toml") print(config.project_name) 'my_project' print(config.start_dt) Timestamp('2020-01-01 00:00:00')
resolved_config = {}
instance-attribute
¶
project_name = None
instance-attribute
¶
root_path = None
instance-attribute
¶
project_dir = None
instance-attribute
¶
project_ws = None
instance-attribute
¶
conf_file_path = None
instance-attribute
¶
data_dir = None
instance-attribute
¶
landsat_dir = None
instance-attribute
¶
sentinel_dir = None
instance-attribute
¶
met_dir = None
instance-attribute
¶
gis_dir = None
instance-attribute
¶
fields_shapefile = None
instance-attribute
¶
gridmet_mapping_shp = None
instance-attribute
¶
gridmet_centroids = None
instance-attribute
¶
correction_tifs = None
instance-attribute
¶
gridmet_factors = None
instance-attribute
¶
properties_dir = None
instance-attribute
¶
irr_csv = None
instance-attribute
¶
ssurgo_csv = None
instance-attribute
¶
lulc_csv = None
instance-attribute
¶
properties_json = None
instance-attribute
¶
snodas_in_dir = None
instance-attribute
¶
snodas_out_json = None
instance-attribute
¶
dynamics_data_json = None
instance-attribute
¶
ee_bucket = None
instance-attribute
¶
feature_id_col = None
instance-attribute
¶
gridmet_mapping_index_col = None
instance-attribute
¶
gridmet_id_col = None
instance-attribute
¶
state_col = None
instance-attribute
¶
irrigation_threshold = None
instance-attribute
¶
irr_threshold = None
instance-attribute
¶
elev_units = None
instance-attribute
¶
refet_type = None
instance-attribute
¶
runoff_process = None
instance-attribute
¶
start_dt = None
instance-attribute
¶
end_dt = None
instance-attribute
¶
kc_proxy = None
instance-attribute
¶
cover_proxy = None
instance-attribute
¶
pest_run_dir = None
instance-attribute
¶
etf_target_model = None
instance-attribute
¶
etf_ensemble_members = None
instance-attribute
¶
workers = None
instance-attribute
¶
realizations = None
instance-attribute
¶
calibration_dir = None
instance-attribute
¶
obs_folder = None
instance-attribute
¶
initial_values_csv = None
instance-attribute
¶
spinup = None
instance-attribute
¶
python_script = None
instance-attribute
¶
forecast_parameters_csv = None
instance-attribute
¶
met_source = None
instance-attribute
¶
snow_source = None
instance-attribute
¶
soil_source = None
instance-attribute
¶
mask_mode = None
instance-attribute
¶
bucket_uri = None
instance-attribute
¶
era5_params = None
instance-attribute
¶
era5_param_mapping = None
instance-attribute
¶
era5_extracts_dir = None
instance-attribute
¶
hwsd_csv = None
instance-attribute
¶
container_path = None
instance-attribute
¶
ecostress_dir = None
instance-attribute
¶
calibrate = None
instance-attribute
¶
forecast = None
instance-attribute
¶
input_data = None
instance-attribute
¶
plot_timeseries = None
instance-attribute
¶
calibration_dir_override = None
instance-attribute
¶
parameter_set_json = None
instance-attribute
¶
parameter_list = None
instance-attribute
¶
forecast_param_csv = None
instance-attribute
¶
forecast_parameters = None
instance-attribute
¶
forecast_parameter_groups = None
instance-attribute
¶
__init__()
¶
Initialize ProjectConfig with default None values for all attributes.
read_config(conf_file_path: str, project_root_override: str | None = None, calibrate: bool = False, forecast: bool = False, calibration_dir_override: str | None = None, parameter_set_json: str | None = None, forecast_param_csv: str | None = None) -> None
¶
Load and parse a TOML configuration file.
Reads the configuration file, resolves path templates (e.g., {root}, {project}), validates required fields, and sets up mode-specific parameters for calibration or forecasting.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
conf_file_path
|
str
|
Path to the TOML configuration file. |
required |
project_root_override
|
str | None
|
Override the root path from the TOML file. |
None
|
calibrate
|
bool
|
Enable calibration mode. |
False
|
forecast
|
bool
|
Enable forecast mode. |
False
|
calibration_dir_override
|
str | None
|
Override the calibration directory path. |
None
|
parameter_set_json
|
str | None
|
Path to JSON file with parameter values. |
None
|
forecast_param_csv
|
str | None
|
Path to CSV file with forecast parameters. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If required configuration keys are missing. |
FileNotFoundError
|
If the configuration file doesn't exist. |
Example
config = ProjectConfig() config.read_config("project.toml", calibrate=True)
read_calibration_parameters(sites: list[str] | None = None) -> None
¶
Load calibration parameter files from the calibration directory.
Reads the initial values CSV and sets up the mapping from parameter names to their multiplier files in the calibration directory.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sites
|
list[str] | None
|
Optional list of site IDs to filter parameters. If provided, only parameters containing these site IDs will be loaded. |
None
|
Raises:
| Type | Description |
|---|---|
FileNotFoundError
|
If the initial values CSV doesn't exist and
|
read_forecast_parameters() -> None
¶
Load forecast parameters from CSV or JSON file.
Reads parameter distributions from forecast_param_csv, forecast_parameters_csv, or parameter_set_json and computes mean values for each parameter.
Sets
forecast_parameters: pandas Series of mean parameter values. parameter_list: List of parameter names. forecast_parameter_groups: Parameter groupings (if loaded from JSON).
Raises:
| Type | Description |
|---|---|
ValueError
|
If no forecast parameter source is configured. |
__str__() -> str
¶
sync_from_bucket(dry_run: bool = False, subdirs: list[str] | None = None) -> subprocess.CompletedProcess | list[subprocess.CompletedProcess]
¶
Sync Earth Engine exports from GCS bucket to local filesystem.
Uses gsutil rsync to mirror the bucket structure to local data directory. Bucket structure: gs://{bucket}/{project}/remote_sensing/... Local structure: {data_dir}/remote_sensing/...
Parameters¶
dry_run : bool, optional If True, show what would be synced without making changes. subdirs : list of str, optional Specific subdirectories to sync (e.g., ['remote_sensing', 'properties']). If None, syncs the entire bucket prefix.
Returns¶
subprocess.CompletedProcess Result of the gsutil command.
Raises¶
ValueError If bucket or data_dir is not configured. subprocess.CalledProcessError If gsutil command fails.
Example¶
cfg = ProjectConfig() cfg.read_config("project.toml") cfg.sync_from_bucket(dry_run=True) # Preview cfg.sync_from_bucket() # Actually sync cfg.sync_from_bucket(subdirs=['remote_sensing']) # Sync only remote sensing