API reference¶

This page provides an auto-generated summary of metsim’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

MetSim¶

The main object of the MetSim package. The MetSim object is used to set up and launch forcing generation and/or disaggregation routines.

The MetSim object uses a class dictionary to refer to the model setup, which can be modified after instantiation if necessary. Before calling run or launch on the instance it is required to call the load function to ensure that all of the required parameters have been set and that the input data is sufficient to provide the output specified.

class metsim.metsim.MetSim(params: dict)[source]¶

MetSim handles the distribution of jobs that write to a common file by launching muliple processes and queueing up their writeback so that work can be done while IO is happening.

ascii_out_preprocess()[source]¶: Dummy function

find_elevation(lat: float, lon: float) → float[source]¶: Use the domain file to get the elevation

launch(job_list: list)[source]¶: Farm out the jobs to separate processes

load(job_list: list)[source]¶: Load the necessary datasets into memory

netcdf_in_preprocess(filename: str)[source]¶: Get the extent and load the data

netcdf_out_preprocess()[source]¶: Initialize the output file

read(fpath: str) → xarray.core.dataset.Dataset[source]¶: Dispatch to the right function based on the file extension

read_ascii(fpath: str) → xarray.core.dataset.Dataset[source]¶: Read in an ascii forcing file

read_binary(fpath: str) → xarray.core.dataset.Dataset[source]¶: Reads a binary forcing file (VIC 4 format)

read_netcdf(fpath: str) → xarray.core.dataset.Dataset[source]¶: Read in a NetCDF file and add elevation information

run(locations: list)[source]¶: Kicks off the disaggregation and queues up data for IO

vic_in_preprocess(job_list: list)[source]¶: Process all files to find spatial extent

write()[source]¶: Dispatch to the right function based on the configuration given

write_ascii()[source]¶: Write out as ASCII to the output file

write_netcdf()[source]¶: Write out as NetCDF to the output file

metsim.metsim.wrap_run(func: <built-in function callable>, loc: dict, ds: xarray.core.dataset.Dataset, disagg: bool)[source]¶

Iterate over a chunk of the domain. This is wrapped so we can return a tuple of locs and df.

Parameters:	func (callable) – The function to call to do the work loc (dict) – Some subset of the domain to do work on met_data (xr.Dataset) – Input forcings and domain disagg (bool) – Whether or not we should run a disagg routine
Returns:	A list of tuples arranged as (location, output)
Return type:	results

Physics¶

physics

metsim.physics.atm_pres(elev: float) → float[source]¶

Atmospheric pressure (Pa) as a function of elevation (m)

[1]	Iribane, J.V., and W.L. Godson, 1981. Atmospheric Thermodynamics, 2nd Edition. D. Reidel Publishing Company, Dordrecht, The Netherlands (p. 168)

Parameters:	elev – Elevation in meters
Returns:	Atmospheric pressure (Pa)
Return type:	pressure

metsim.physics.calc_pet(rad: pandas.core.series.Series, ta: pandas.core.series.Series, dayl: pandas.core.series.Series, pa: float, dt: float=0.2) → pandas.core.series.Series[source]¶

Calculates the potential evapotranspiration for aridity corrections in calc_vpd(), according to Kimball et al., 1997

Parameters:	rad – daylight average incident shortwave radiation (W/m2) ta – daylight average air temperature (deg C) dayl – daylength (s) pa – air pressure (Pa) dt – offset for saturation vapor pressure calculation
Returns:	Potential evapotranspiration (cm/day)
Return type:	pet

metsim.physics.solar_geom[source]¶

Flat earth assumption

Parameters:	elev – Elevation in meters lat – Latitude in decimal format
Returns:	(tiny_rad_fract, daylength, flat_potrad, tt_max0)
Return type:	sg

metsim.physics.svp[source]¶

Compute the saturated vapor pressure.

[1]	Maidment, David R. Handbook of hydrology. McGraw-Hill Inc., 1992 Equation 4.2.2.

Parameters:	temp – Temperature (degrees Celsius) a – (optional) parameter b – (optional) parameter c – (optional) parameter
Returns:	Saturated vapor pressure (Pa)
Return type:	svp

metsim.physics.svp_slope(temp: pandas.core.series.Series, a: float=0.61078, b: float=17.269, c: float=237.3)[source]¶

Compute the gradient of the saturated vapor pressure as a function of temperature.

[1]	Maidment, David R. Handbook of hydrology. McGraw-Hill Inc., 1992. Equation 4.2.3.

Parameters:	temp – Temperature (degrees Celsius)
Returns:	Gradient of d(svp)/dT.
Return type:	dsvp_dT

MtClim¶

MTCLIM

metsim.methods.mtclim.calc_prec(df: pandas.core.frame.DataFrame, params: dict)[source]¶

Adjust precitation according to ratio of isohyet ratio of the given site to some base value.

Parameters:	df – Dataframe containing daily precipitation timeseries. params – Dictionary containing isohyet values

metsim.methods.mtclim.calc_snowpack(df: pandas.core.frame.DataFrame, snowpack: float=0.0)[source]¶

Estimate snowpack as swe.

Parameters:	df – Dataframe with daily timeseries of precipitation and minimum temperature. snowpack – (Optional - defaults to 0) Initial snowpack

metsim.methods.mtclim.calc_srad_hum(df: pandas.core.frame.DataFrame, sg: dict, elev: float, params: dict, win_type: str='boxcar')[source]¶

Calculate shortwave, humidity

Parameters:	df – Dataframe containing daily timeseries elev – Elevation in meters params – A dictionary of parameters from the MetSim object win_type – (Optional) The method used to calculate the 60 day rolling average of precipitation

metsim.methods.mtclim.calc_t_air(df: pandas.core.frame.DataFrame, elev: float, params: dict)[source]¶

Adjust temperatures according to lapse rates and calculate t_day

Parameters:	df – Dataframe with daily max and min temperatures elev – Elevation in meters params – Dictionary containing parameters from a MetSim object. Lapse rates are used in this calculation.

metsim.methods.mtclim.run(forcing: pandas.core.frame.DataFrame, params: dict, elev: float, lat: float, disagg=True)[source]¶

Run all of the mtclim forcing generation

Parameters:	forcing – The daily forcings given from input solar_geom – Solar geometry of the site
Returns:	Dataframe of daily or subdaily forcings
Return type:	forcing

metsim.methods.mtclim.sw_hum_iter(df: pandas.core.frame.DataFrame, sg: dict, pa: float, pva: pandas.core.series.Series, parray: pandas.core.series.Series, dtr: pandas.core.series.Series, params: dict)[source]¶

Calculated updated values for dewpoint temperature and saturation vapor pressure.

Parameters:	df – Dataframe containing daily timeseries of cloud cover fraction, tfmax, swe, and shortwave radiation sg – Solar geometry dictionary, calculated with metsim.physics.solar_geom. pa – Air pressure in Pascals pva – Vapor presure in Pascals parray – 60 day rolling average of precipitation in cm dtr – Daily temperature range params – A dictionary of parameters from a MetSim object
Returns:	A tuple of dewpoint temperature and saturation vapor pressure
Return type:	(tdew, svp)

Disagg¶

Disaggregates daily data down to finer grained data using some heuristics

metsim.disaggregate.disaggregate(df_daily: pandas.core.frame.DataFrame, params: dict, solar_geom: dict)[source]¶

Take a daily timeseries and scale it down to a finer time scale.

Parameters:	df_daily – Dataframe containing daily timeseries. Should be the result of one of the methods provided in the methods directory. params – A dictionary containing the class parameters of the MetSim object. solar_geom – A dictionary of solar geometry variables
Returns:	A dataframe with sub-daily timeseries.
Return type:	df_disagg

metsim.disaggregate.longwave(air_temp: pandas.core.series.Series, vapor_pressure: pandas.core.series.Series, tskc: pandas.core.series.Series, params: dict)[source]¶

Calculate longwave. This calculation can be performed using a variety of parameterizations for both the clear sky and cloud covered emissivity. Options for choosing these parameterizations should be passed in via the params argument.

Parameters:	air_temp – Sub-daily temperature vapor_pressure – Sub-daily vapor pressure tskc – Daily cloud fraction params – A dictionary of parameters, which contains information about which emissivity and cloud fraction methods to use.
Returns:	A sub-daily timeseries of the longwave radiation as well as a sub-daily timeseries of the cloud cover fraction.
Return type:	(lwrad, tskc)

metsim.disaggregate.prec(prec: pandas.core.series.Series, ts: float)[source]¶

Splits the daily precipitation evenly throughout the day

Parameters:	prec – Daily timeseries of precipitation ts – Timestep to disaggregate down to
Returns:	A sub-daily timeseries of precipitation
Return type:	prec

metsim.disaggregate.relative_humidity(vapor_pressure: pandas.core.series.Series, temp: pandas.core.series.Series)[source]¶

Calculate relative humidity from vapor pressure and temperature.

Parameters:	vapor_pressure – A sub-daily timeseries of vapor pressure temp – A sub-daily timeseries of temperature
Returns:	A sub-daily timeseries of relative humidity
Return type:	rh

metsim.disaggregate.set_min_max_hour(disagg_rad: pandas.core.series.Series, n_days: int, ts: float, params: dict)[source]¶

Determine the time at which min and max temp is reached for each day.

Parameters:	disagg_rad – Shortwave radiation disaggregated to sub-daily timesteps. n_days – The number of days being disaggregated ts – Timestep used for disaggregation params – A dictionary of class parameters of the MetSim object.
Returns:	A tuple containing 2 timeseries, corresponding to time of min and max temp, respectively
Return type:	(t_t_min, t_t_max)

metsim.disaggregate.shortwave(sw_rad: pandas.core.series.Series, daylength: pandas.core.series.Series, day_of_year: pandas.core.series.Series, tiny_rad_fract: <built-in function array>, params: dict)[source]¶

Disaggregate shortwave radiation down to a subdaily timeseries.

Parameters:	sw_rad – Daily incoming shortwave radiation daylength – List of daylength time for each day of year day_of_year – Timeseries of index of days since Jan-1 tiny_rad_fract – Fraction of the daily potential radiation during a radiation time step defined by SW_RAD_DT params – Dictionary of parameters from the MetSim object
Returns:	A sub-daily timeseries of shortwave radiation.
Return type:	disaggrad

metsim.disaggregate.temp(df_daily: pandas.core.frame.DataFrame, df_disagg: pandas.core.frame.DataFrame, t_t_min: <built-in function array>, t_t_max: <built-in function array>, ts: float)[source]¶

Disaggregate temperature using a Hermite polynomial interpolation scheme.

Parameters:	df_daily – A dataframe of daily values. df_disagg – A dataframe of sub-daily values. t_t_min – Times at which minimum daily temperatures are reached. t_t_max – Times at which maximum daily temperatures are reached. ts – Timestep for disaggregation
Returns:	A sub-daily timeseries of temperature.
Return type:	temps

metsim.disaggregate.vapor_pressure(vp_daily: pandas.core.series.Series, temp: pandas.core.series.Series, t_t_min: <built-in function array>, n_out: int, ts: float)[source]¶

Calculate vapor pressure. First a linear inerpolation of the daily values is calculated. Then this is compared to the saturated vapor pressure calculated using the disaggregated temperature. When the interpolated vapor pressure is greater than the calculated saturated vapor pressure, the interpolation is replaced with the saturation value.

Parameters:	vp_daily – Daily vapor pressure temp – Sub-daily temperature t_t_min – Timeseries of minimum daily temperature n_out – Number of output observations ts – Timestep to disaggregate down to
Returns:	A sub-daily timeseries of the vapor pressure
Return type:	vp

metsim.disaggregate.wind(wind: pandas.core.series.Series, ts: float)[source]¶

Wind is assumed constant throughout the day

Parameters:	wind – Daily timeseries of wind ts – Timestep to disaggregate down to
Returns:	A sub-daily timeseries of wind
Return type:	wind