easy_vic_build.tools.utilities

General utility functions for path handling, resource loading, dataset I/O, and so on

Functions

`checkGaugeBasin`(basinShp, usgs_streamflow, ...)	Compares the basin shapefile data with the USGS streamflow, BasinAttribute, and forcingDaymet gauge attributes to check for mismatches.
`check_and_mkdir`(dir)	Create a directory if it does not exist.
`clearParam`(evb_dir)	Deletes the parameter NetCDF files from disk.
`exportToCsv`(basin_shp, fpath_dir)	Exports data from the provided basin shapefile to CSV files.
`readBasinMap`(evb_dir)	Reads the basin map shapefile.
`readCalibrateCp`(evb_dir)	Reads the calibration control points from a pickle file.
`readDomain`(evb_dir[, name])	Reads the domain data from a NetCDF file.
`readGlobalParam`(evb_dir)	Reads the global parameters from a configuration file.
`readHCDNBasins`([home])	Read HCDN basin polygons and add `AREA_km2`.
`readHCDNGrids`([home])	Reads HCDN grid data.
`readParam`(evb_dir[, mode])	Reads parameter data from NetCDF files at levels 0 and 1.
`readRVICParam`(evb_dir)	Reads the RVIC parameter files from disk.
`read_NLDAS_Veg_monthly`()	Reads monthly vegetation data from NLDAS.
`read_NLDAS_annual_prec`()	Reads the NLDAS annual precipitation data.
`read_cfg_to_dict`(cfg_file_path)	Reads a configuration file and converts it to a dictionary.
`read_globalParam_reference`()	Reads the global parameter reference file.
`read_one_HCDN_basin_shp`(basin_index[, home])	Reads a specific basin shapefile from the HCDN dataset.
`read_rvic_conv_cfg_file_reference`()	Reads the RVIC convolution configuration reference file.
`read_rvic_param_cfg_file_reference`()	Reads the RVIC parameter configuration reference file.
`read_veg_param_json`()	Reads updated vegetation attributes from a JSON file.
`read_veg_type_attributes_umd`()	Reads vegetation type attributes from UMD.
`readdpc`(dpc_fpath, dpc_class)	Instantiate a DPC object from a serialized path.
`remove_and_mkdir`(dir)	Remove a directory and recreate it as an empty directory.
`remove_files`(dir)	Remove files in a directory while keeping subdirectories.
`setHomePath`([root])	Sets the home path for the CAMELS dataset.

easy_vic_build.tools.utilities.check_and_mkdir(dir)[source]

Create a directory if it does not exist.

Parameters:: dir (str) – The directory path to check and create.

easy_vic_build.tools.utilities.remove_and_mkdir(dir)[source]

Remove a directory and recreate it as an empty directory.

Parameters:: dir (str) – The directory path to remove and create.

easy_vic_build.tools.utilities.remove_files(dir)[source]

Remove files in a directory while keeping subdirectories.

Parameters:: dir (str) – The directory from which files will be removed.

easy_vic_build.tools.utilities.setHomePath(root='E:')[source]

Sets the home path for the CAMELS dataset.

Parameters:

root (str, optional) – The root directory for the CAMELS dataset, default is “E:”.

Returns:

root (str) – The root directory path.
home (str) – The home directory path.

easy_vic_build.tools.utilities.exportToCsv(basin_shp, fpath_dir)[source]

Exports data from the provided basin shapefile to CSV files.

Parameters:

basin_shp (geopandas.GeoDataFrame) – The basin shapefile containing the required data.
fpath_dir (str) – The directory path to save the exported CSV files.

easy_vic_build.tools.utilities.checkGaugeBasin(basinShp, usgs_streamflow, BasinAttribute, forcingDaymetGaugeAttributes)[source]

Compares the basin shapefile data with the USGS streamflow, BasinAttribute, and forcingDaymet gauge attributes to check for mismatches.

Parameters:

basinShp (geopandas.GeoDataFrame) – The basin shapefile containing basin IDs.
usgs_streamflow (list) – A list of USGS streamflow data.
BasinAttribute (pandas.DataFrame) – A dataframe containing basin attributes.
forcingDaymetGaugeAttributes (list) – A list of forcing Daymet gauge attributes.

easy_vic_build.tools.utilities.read_NLDAS_annual_prec()[source]

Reads the NLDAS annual precipitation data.

Returns:

data_annual_P (np.ndarray) – The annual precipitation data.
annual_P_lon (np.ndarray) – The longitude data.
annual_P_lat (np.ndarray) – The latitude data.

easy_vic_build.tools.utilities.read_globalParam_reference()[source]

Reads the global parameter reference file.

Returns:: globalParam – The global parameter object.
Return type:: GlobalParamParser

easy_vic_build.tools.utilities.read_rvic_param_cfg_file_reference()[source]

Reads the RVIC parameter configuration reference file.

Returns:: cfg_file – The configuration file parser object.
Return type:: ConfigParser

easy_vic_build.tools.utilities.read_rvic_conv_cfg_file_reference()[source]

Reads the RVIC convolution configuration reference file.

Returns:: cfg_file – The configuration file parser object.
Return type:: ConfigParser

easy_vic_build.tools.utilities.read_veg_type_attributes_umd()[source]

Reads vegetation type attributes from UMD.

Returns:: veg_params_json – A dictionary of vegetation parameters.
Return type:: dict

easy_vic_build.tools.utilities.read_NLDAS_Veg_monthly()[source]

Reads monthly vegetation data from NLDAS.

Returns:

NLDAS_Veg_monthly_veg_rough (pandas.DataFrame) – A dataframe containing vegetation roughness data.
NLDAS_Veg_monthly_veg_displacement (pandas.DataFrame) – A dataframe containing vegetation displacement data.

easy_vic_build.tools.utilities.read_veg_param_json()[source]

Reads updated vegetation attributes from a JSON file.

Returns:: veg_params_json – A dictionary of updated vegetation parameters.
Return type:: dict

easy_vic_build.tools.utilities.readHCDNGrids(home='E:\\data\\hydrometeorology\\CAMELS')[source]

Reads HCDN grid data.

Parameters:: home (str, optional) – The directory containing the grid data, default is “E:datahydrometeorologyCAMELS”.
Returns:: grid_shp – The grid shapefile data with added point geometry.
Return type:: geopandas.GeoDataFrame

easy_vic_build.tools.utilities.readHCDNBasins(home='E:\\data\\hydrometeorology\\CAMELS')[source]

Read HCDN basin polygons and add AREA_km2.

Parameters:: home (str, optional) – The root directory where the CAMELS dataset is stored, by default “E:datahydrometeorologyCAMELS”.
Returns:: HCDN_shp – Basin shapefile with area converted from m2 to km2.
Return type:: geopandas.GeoDataFrame

easy_vic_build.tools.utilities.read_one_HCDN_basin_shp(basin_index, home='E:\\data\\hydrometeorology\\CAMELS')[source]

Reads a specific basin shapefile from the HCDN dataset.

Parameters:

basin_index (int) – The index of the basin to read from the HCDN shapefile.
home (str, optional) – The root directory where the CAMELS dataset is stored, by default “E:datahydrometeorologyCAMELS”.

Returns:

basin_shp_all (geopandas.GeoDataFrame) – The full HCDN shapefile GeoDataFrame.
basin_shp (geopandas.GeoDataFrame) – The specific basin’s GeoDataFrame.

easy_vic_build.tools.utilities.readdpc(dpc_fpath, dpc_class)[source]

Instantiate a DPC object from a serialized path.

Parameters:

dpc_fpath (str) – Path to DPC serialized data.
dpc_class (type) – DPC class constructor that accepts dpc_fpath.

Returns:

DPC instance created by dpc_class.

Return type:

object

easy_vic_build.tools.utilities.readDomain(evb_dir, name=None)[source]

Reads the domain data from a NetCDF file.

Parameters:

evb_dir (Evb_dir) – Case directory manager.
name (str, optional) – Optional suffix; if provided, read domain_<name>.nc.

Returns:

domain_dataset – The domain dataset loaded from the NetCDF file.

Return type:

netCDF4.Dataset

easy_vic_build.tools.utilities.readParam(evb_dir, mode='r')[source]

Reads parameter data from NetCDF files at levels 0 and 1.

Parameters:

evb_dir (Evb_dir) – Case directory manager.
mode (str, optional) – The mode to open the files, by default “r”.

Returns:

params_dataset_level0 (netCDF4.Dataset) – The parameter dataset at level 0.
params_dataset_level1 (netCDF4.Dataset) – The parameter dataset at level 1.

easy_vic_build.tools.utilities.clearParam(evb_dir)[source]

Deletes the parameter NetCDF files from disk.

Parameters:: evb_dir (Evb_dir) – Case directory manager.

easy_vic_build.tools.utilities.readRVICParam(evb_dir)[source]

Reads the RVIC parameter files from disk.

Parameters:

evb_dir (Evb_dir) – Case directory manager. Also expects evb_dir.cfg_file_path.

Returns:

flow_direction_dataset (netCDF4.Dataset) – The flow direction dataset.
pourpoint_file (pandas.DataFrame) – The pourpoint file data.
uhbox_file (pandas.DataFrame) – The unit hydrograph box file data.
cfg_file (ConfigParser) – The configuration file parser object.

easy_vic_build.tools.utilities.read_cfg_to_dict(cfg_file_path)[source]

Reads a configuration file and converts it to a dictionary.

Parameters:: cfg_file_path (str) – The path to the configuration file.
Returns:: cfg_file_dict – A dictionary containing the configuration parameters.
Return type:: dict

easy_vic_build.tools.utilities.readGlobalParam(evb_dir)[source]

Reads the global parameters from a configuration file.

Parameters:: evb_dir (Evb_dir) – Case directory manager.
Returns:: globalParam – A global parameter object loaded from the specified file.
Return type:: GlobalParamParser

easy_vic_build.tools.utilities.readCalibrateCp(evb_dir)[source]

Reads the calibration control points from a pickle file.

Parameters:

evb_dir (Evb_dir) – Case directory manager.

Returns:

state –

A dictionary containing the state information from the calibration file. The keys of the dictionary are:

current_generation
initial_population
population
history
front_fitness

Return type:

dict

easy_vic_build.tools.utilities.readBasinMap(evb_dir)[source]

Reads the basin map shapefile.

Parameters:: evb_dir (Evb_dir) – Case directory manager.
Returns:: stream_gdf – The stream basin shapefile data.
Return type:: geopandas.GeoDataFrame