API Reference

Core API Functions

salientsdk.forecast_timeseries(loc, date='-default', debias=False, field='anom', format='nc', model='blend', reference_clim='salient', timescale='all', variable='temp', version='-default', destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, strict=True, **kwargs)

Get time series of S2S meteorological forecasts.

This function is a convenience wrapper to the Salient API.

Parameters:

Name	Type	Description	Default
loc	Location	The location to query	required
date	str | list[str]	The date the forecast was generated. Defaults to find the most recent forecast. Can be a specific date in the format YYYY-MM-DD. May be a vector of dates or a comma separated list of dates, in which case the function will return a DataFrame.	'-default'
debias	bool	If True, debias the data to local observations. Valid only for model = blend. detail	False
field	str	The field to query, defaults to anom which is an anomaly value from climatology. Also available: vals, which will return absolute values without regard to climatology.	'anom'
format	str	The file format of the response. Defaults to nc which returns a multivariate NetCDF file. Also available: csv which returns a CSV file.	'nc'
model	str | list[str]	The model to query. Defaults to blend, which is the Salient blended forecast. May be a list of strings or comma-separated string, which downloads multiple models.	'blend'
reference_clim	str	Reference climatology for calculating anomalies. Ignored when field=vals since there are no anomalies to calculate. Defaults to salient, which is Salient's proprietary climatology.	'salient'
timescale	str	Forecast look-ahead. - sub-seasonal is 1-5 weeks. Will return a coordinate forecast_date_weekly and a data variable anom_weekly or vals_weekly. - seasonal is 1-3 months. Will return a coordinate forecast_date_monthly and a data variable anom_monthly or vals_monthly. - long-range is 1-4 quarters. Will return a coordinate forecast_date_quarterly and a data variable anom_quarterly or vals_quarterly. - all (default) will include sub-seasonal, seasonal, and long-range timescales	'all'
variable	str	The variable to query, defaults to temp To request multiple variables, separate them with a comma temp,precip or use a list. This will download one file per variable See the Data Fields documentation for a full list of available historical variables.	'temp'
version	str	The model version of the Salient blend forecast. To request multiple versions, provide a list or comma-separated string. -default calls get_default_version().	'-default'
destination	str	The destination directory for downloaded files. -default uses get_file_destination()	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate. Defaults to use the value returned by get_verify_ssl()	None
verbose	bool	If True (default False) print status messages	False
strict	bool	If True (default) error if query is invalid. If False, return NA for the file name and continue processing.	True
**kwargs		Additional arguments to pass to the API	{}

Other Parameters:

Name	Type	Description
units	str	SI or US

Returns:

Type	Description
str | DataFrame	str | pd.DataFrame: the file name(s) of the downloaded data. File names are a hash of the query parameters. When force=False and the file already exists, the function will return the file name almost instantaneously without querying the API. If multiple variables, dates, or models are requested, returns a DataFrame with column file_name additional columns for vectorized queries.

salientsdk.downscale(loc, variables='temp,precip', date='-today', members=50, debias=False, frequency='daily', reference_clim='salient', version='-default', weights=None, destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, **kwargs)

Temporal downscale of forecasts.

Convert temporally coarse probabilistic forecasts into granular daily ensembles. For more detail, see the api doc.

Parameters:

Name	Type	Description	Default
loc	Location	The location to query. If using a shapefile or location_file, may input a vector of file names which will trigger multiple calls to downscale. This is useful because downscale requires that all points in a file be from the same continent.	required
variables	str | list[str]	The variables to query, separated by commas or as a list See the Data Fields documentation for a full list of available variables. Note that downscale natively supports a list of variables, so passing a list of variables here will not necessarily trigger downloading multiple files.	'temp,precip'
date	str	The start date of the time series. If date is -today, use the current date.	'-today'
members	int	The number of ensemble members to download	50
frequency	str	The temporal resolution of the time series, daily (default) or hourly.	'daily'
reference_clim	str	Reference period to calculate anomalies	'salient'
debias	bool	If True, debias the data	False
version	str	The model version of the Salient blend forecast.	'-default'
weights	str	The variable that will be used to weight each grid point within a shapefile. Defaults to unweighted, can also weight by population.	None
destination	str	The destination directory for downloaded files.	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate	None
verbose	bool	If True (default False) print status messages	False
**kwargs		Additional arguments to pass to the API	{}

Other Parameters:

Name	Type	Description
gdd_base	int	The base temperature for growing degree days
units	str	US or SI

Returns:

Type	Description
str | DataFrame	str | pd.DataFrame : If only one file was downloaded, return the name of the file. If multiple files were downloaded, return a table with column file_name and additional columns documenting the vectorized input arguments such as location_file.

salientsdk.data_timeseries(loc, variable='temp', field='anom', debias=False, start='1950-01-01', end='-today', format='nc', frequency='daily', destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, **kwargs)

Get a historical time series of ERA5 data.

This function is a convenience wrapper to the Salient API.

Parameters:

Name	Type	Description	Default
loc	Location	The location to query. If using a shapefile or location_file, may input a vector of file names which will trigger multiple calls to data_timeseries.	required
variable	str | list[str]	The variable to query, defaults to temp To request multiple variables, separate them with a comma temp,precip This will download one file per variable See the Data Fields documentation for a full list of available historical variables.	'temp'
field	str	The field to query, defaults to "anom"	'anom'
debias	bool	If True, debias the data to local observations. Disabled for shapefile locations. detail	False
start	str	The start date of the time series	'1950-01-01'
end	str	The end date of the time series	'-today'
format	str	The format of the response	'nc'
frequency	str	The frequency of the time series	'daily'
destination	str	The directory to download the data to	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request. If None (default) uses get_current_session().	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate	None
verbose	bool	If True (default False) print status messages	False
**kwargs		Additional arguments to pass to the API	{}

Other Parameters:

Name	Type	Description
units	str	SI or US

Returns:

Type

Description

str | DataFrame

str | pd.DataFrame: the file name of the downloaded data. File names are a hash of the query parameters. When force=False and the file already exists, the function will return the file name almost instantaneously without querying the API. If multiple variables are requested, returns a pd.DataFrame with columns file_name and additional columns documenting the vectorized input arguments such as location_file or variable

salientsdk.hindcast_summary(loc, metric='crps', reference='-auto', season='all', split_set='all', timescale='all', variable='temp', version='-default', interp_method='nearest', destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, **kwargs)

Get summary of accuracy metrics.

This function is a convenience wrapper to the Salient API.

Parameters:

Name	Type	Description	Default
loc	Location	The location to query	required
metric	str	The accuracy metric to calculate. Defaults to "crps".	'crps'
interp_method	str	The interpolation method to use. - nearest (default) selects the nearest native gridpoint - linear interpolates from the native grid to the input point	'nearest'
reference	str	The reference dataset to compare against. Defaults to "-auto".	'-auto'
season	str | list[str]	Meteorological season to consider. Defaults to "all". May also be a list of strings or a comma-separated string to vectorize the query. Also valid: DJF, MAM, JJA, SON.	'all'
split_set	str	The date range over which to calculate scores. all (default) calculates scores back to 2000. test uses post-2015 data which was never used for model training.	'all'
timescale	str	Forecast look-ahead. - sub-seasonal is 1-5 weeks. Will return a coordinate forecast_date_weekly and a data variable anom_weekly or vals_weekly. - seasonal is 1-3 months. Will return a coordinate forecast_date_monthly and a data variable anom_monthly or vals_monthly. - long-range is 1-4 quarters. Will return a coordinate forecast_date_quarterly and a data variable anom_quarterly or vals_quarterly. - all (default) will include sub-seasonal, seasonal, and long-range timescales	'all'
variable	str | list[str]	The variable to query, defaults to temp To request multiple variables, separate them with a comma temp,precip or use a list. This will download one file per variable See the Data Fields documentation for a full list of available historical variables.	'temp'
version	str | list[str]	The model version of the Salient blend forecast. To compare multiple versions, provide a list or comma-separated string. -default calls get_default_version().	'-default'
destination	str	The destination directory for downloaded files. -default uses get_file_destination()	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The Session object to use for the request. Defaults to use get_current_session(), typically set during login().	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	Verify the SSL certificate. Defaults to use get_verify_ssl(), typically set during login().	None
verbose	bool	If True (default False) print status messages.	False
**kwargs		Additional arguments to pass to the API	{}

Other Parameters:

Name	Type	Description
units	str	SI or US

Returns:

Name	Type	Description
str	str	the file name of the downloaded data. File names are a hash of the query parameters. When force=False and the file already exists, the function will return the file name almost instantaneously without querying the API. If multiple files are requested, they will be concatenated into a single table.

salientsdk.geo(loc, variables='elevation', resolution=0.25, format='nc', destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, **kwargs)

Get static geo-data.

Parameters:

Name	Type	Description	Default
loc	Location	The location to query. If using a shapefile or location_file, may input a vector of file names which will trigger multiple calls to downscale. This is useful because downscale requires that all points in a file be from the same continent.	required
variables	str	The variables to query, defaults to "elevation". Supports a comma separated list or list of variables.	'elevation'
resolution	float	The spatial resolution of the data in degrees.	0.25
format	str	The file format of the response. Defaults to nc which returns a multivariate NetCDF file. Also available: csv which returns a CSV file.	'nc'
destination	str	The destination directory for downloaded files.	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate	None
verbose	bool	If True (default False) print status messages	False
**kwargs		Additional arguments to pass to the API	{}

Returns:

Type	Description
str | list[str]	str | pd.DataFrame : If only one file was downloaded, return the name of the file. If multiple files were downloaded, return a table with column file_name and additional columns documenting the vectorized input arguments such as location_file.

salientsdk.login(username='username', password='password', apikey=None, verify=None, verbose=False)

Login to the Salient API.

This function is a local convenience wrapper around the Salient API login endpoint. It will use your credentials to create a persistent session you can use to execute API calls.

Parameters:

Name	Type	Description	Default
username	str	The username to login with	'username'
password	str	The password to login with	'password'
apikey	str | None	The API key to use instead of a login. If None (default) uses username and password to create a Session. If specified bypasses login and ignores username / password	None
verify	bool	Whether to verify the SSL certificate. If None (default) will try True and then False, remembering the last successful setting and preserving it for future calls in get_verify_ssl().	None
verbose	bool	Whether to print the response status	False

Returns:

Type	Description
Session | None	Session | None: Session object to pass to other API calls. As a side effect, will also set the default session for use with get_current_session()

Geo-Inputs

salientsdk.Location

Define geographical parameters for an API query.

The Salient API defines location by a single latitude/longitude, multiple latitude/longitude pairs in a single location_file, or a polygon defined in a shapefile. This class manages these options.

__init__(lat=None, lon=None, location_file=None, shapefile=None, region=None)

Initialize a Location object.

Only one of the following 4 options should be used at a time: lat/lon, location_file, shapefile, or region.

Parameters:

Name	Type	Description	Default
lat	float	Latitude in degrees, -90 to 90.	None
lon	float	Longitude in degrees, -180 to 180.	None
location_file	str | list[str]	Path(s) to CSV file(s) with latitude and longitude columns.	None
shapefile	str | list[str]	Path(s) to a shapefile(s) with a polygon defining the location.	None
region	str | list[str]	Accepts continents, countries, or U.S. states (e.g. "usa") Only available for hindcast_summary()	None

load_location_file(destination='-default')

Load the location file(s) into a DataFrame.

Parameters:

Name	Type	Description	Default
destination	str	The directory where the file is located. Defaults to the default directory via get_file_destination.	'-default'

Returns:

Type	Description
GeoDataFrame	gpd.GeoDataFrame: The location data in a DataFrame. If multiple files are loaded, the DataFrames will be concatenated into a single DataFrame with an additional column file_name that documents the source file. location_file suports a variety of column names for latitude and longitude. This method standardizes them to lat and lon.

_as_geoframe(geo) staticmethod

Normalize column names on a DataFrame and convert to a GeoDataFrame.

Regardless of the column names in the input DataFrame, this method will return a GeoDataFrame with columns lat,lon, and name

plot_locations(title=None, weight=None, pad=1.0)

Show location points on a map.

Parameters:

Name	Type	Description	Default
title	str	The title of the plot.	None
weight	str	The column name in the location file to use to weight the points.	None
pad	float	Adds extent to the lat/lon bounding boxon the map.	1.0

salientsdk.upload_file(file, verbose=True, session=None)

Uploads a geography file to the Salient API.

An interface to to the Salient upload_file API endpoint.

Parameters:

Name	Type	Description	Default
file	str	the file to upload (e.g. a shapefile or CSV).	required
verbose	bool	whether to print status messages.	True
session	Session	the session to use for the upload.	None

salientsdk.upload_bounding_box(north, south, east, west, geoname, destination='-default', force=False, verbose=False, session=None)

Upload a bounding box.

Create and upload a GeoJSON shapefile with a rectangular bounding box for later use with the shapefile location argument.

Parameters:

Name	Type	Description	Default
north	float	Northern extent decimal latitude	required
south	float	Southern extent decimal latitude	required
east	float	Eastern extent decimal longitude	required
west	float	Western extent decimal longitude	required
geoname	str	Name of the GeoJSON file and object to create	required
destination	str	The destination directory for the generated file	'-default'
force	bool	If the file already exists, don't upload it	False
verbose	bool	Whether to print status messages	False
session	Session	The session object to use for the request	None

Returns:

Name	Type	Description
str	str	File name of the GeoJSON file

salientsdk.upload_shapefile(coords, geoname, destination='-default', force=False, verbose=False, session=None)

Upload a custom shapefile defined by a a list of lat/lon pairs.

This will often be used with Location(shapefile...)

Parameters:

Name	Type	Description	Default
coords	list[tuple]	List of (longitude, latitude) pairs defining the polygon.	required
geoname	str	Name of the GeoJSON file and object to create.	required
destination	str	The destination directory for the generated file.	'-default'
force	bool	If True, overwrite the existing file if it exists.	False
verbose	bool	Whether to print status messages.	False
session	Session	The session object to use for the request.	None

Returns:

Name	Type	Description
str		File name of the GeoJSON file.

salientsdk.upload_location_file(lats, lons, names, geoname, destination='-default', force=False, verbose=False, session=None, **kwargs)

Upload a vector of locations.

Create and upload a CSV file with a list of locations for later use with the location_file location argument.

Parameters:

Name	Type	Description	Default
lats	list[float] | Series	List of decimal latitudes	required
lons	list[float] | Series	List of decimal longitudes	required
names	list[str] | Series	List of names for the locations	required
geoname	str	Name of the CSV file and object to create	required
destination	str	The destination directory for the generated file	'-default'
force	bool	When False, if the file already exists don't upload it	False
verbose	bool	If True, print status messages	False
session	Session	The session object to use for the request	None
**kwargs		Additional columns to include in the CSV file	{}

Returns:

Name	Type	Description
str	str	File name of the CSV file

salientsdk.user_files(destination='-default', session=None, verify=None, verbose=False)

List the location and shape files uploaded by the user.

Parameters:

Name	Type	Description	Default
destination	str	The destination directory for the resulting JSON file	'-default'
session	Session	The session object to use for the request	None
verify	bool	Whether to verify the SSL certificate. Defaults to use the value returned by get_verify_ssl()	None
verbose	bool	If True, print the full contents of the file.	False

Returns:

Name	Type	Description
str	str	the location of the JSON file containing top-level entries coordinates (for location_file inputs) and shapefiles.

salientsdk.merge_location_data(ds, loc_file)

Merge additional data columns from a location_file into a dataset.

Will add any additional columns from loc_file to ds.

Parameters:

Name	Type	Description	Default
ds	Dataset	A Dataset with a vector location coordinate, typically resulting from requesting a location_file	required
loc_file	str | Location	Path to a CSV file containing location data or a Location object with a location_file attribute.	required

Returns:

Type	Description
	xr.Dataset: A new Dataset with the additional columns from loc_file along the location coordinate.

Utilities

Data Utilities

salientsdk.load_multihistory(files, fields=['vals'])

Load multiple .nc history files and merge them into a single dataset.

Parameters:

Name	Type	Description	Default
files	DataFramme	Table of the type returned by data_timeseries when multiple variables, location_files or shapefiles are requested e.g. data_timeseries(..., variable = "temp,precip")	required
fields	list[str]	List of fields to extract from the history files. Useful if when calling data_timeseries(..., field = "all")	['vals']

Returns:

Type	Description
Dataset	xr.Dataset: The merged dataset, where each field and variable is renamed to <variable>_<field> or simply variable if field = "vals". This will cause the format of a multi-variable file to match the data variable names of downscale, which natively supports multi-variable queries.

salientsdk.transpose_hindcast_summary(scores, min_score=0.0, weight_weeks=1.0, weight_months=0.5, weight_quarters=0.25)

Transpose hindcast_summary long to wide, preserving groups.

Transposes the hindcast summary data from a long format to a wide format where each 'Lead' row becomes a column. Adds a column mean with a weighted average of the scores.

Parameters:

Name	Type	Description	Default
scores	str | DataFrame	The hindcast scores data. This can be either a file path as a string or a pre-loaded DataFrame of the type returned by hindcast_summary()	required
min_score	float	Render any scores below this threshold as NA	0.0
weight_weeks	float	Weight for weeks 3-5, defaults to 1.0	1.0
weight_months	float	Weight for months 2-3, defaults to 0.5	0.5
weight_quarters	float	Weight for quarters 2-4, defaults to 0.25	0.25

Returns:

Type	Description
DataFrame	pd.DataFrame: The transposed DataFrame with 'Lead' categories as columns.

Wind Utilities

salientsdk.wind.calc_wind_power_all(met, wspd='wspd', wspd100='wspd100', temp='temp', turbine_model='turbine_model', hub_height='hub_height', elevation='elevation')

Calculate wind power from meteorological data.

This is a convenience function that shears wind to hub height, density-corrects it, then calculates wind power. It operates on a single dataset as a source of the necessary data.

The arguments wspd, wspd100, temp, turbine_model, hub_height, and elevation can be either strings or xr.DataArray objects. If they are strings, they are assumed to be keys in the met dataset.

Parameters:

Name	Type	Description	Default
met	Dataset	Meteorological data.	required
wspd	str | DataArray	Wind speed at hub height.	'wspd'
wspd100	str | DataArray	Wind speed at 100m.	'wspd100'
temp	str | DataArray	Temperature	'temp'
turbine_model	str | DataArray	Turbine model.	'turbine_model'
hub_height	str | DataArray	Hub height (m).	'hub_height'
elevation	str | DataArray	Elevation above sea level (m).	'elevation'

Returns:

Type	Description
Dataset	xr.Dataset: with fields wspdhh for density-corrected wind speed at hub height power for generated wind power in MW.

salientsdk.wind.calc_wind_power(wind_speed, turbine_model='default', keep_dims=None)

Calculate power from power curve & density-corrected hub-height wind.

Parameters:

Name	Type	Description	Default
wind_speed	DataArray	Wind speed at hub height.	required
turbine_model	str | DataArray	Turbine model to use. If a string, call get_power_curve(turbine_model) If a DataArray, iterate over locations to apply a different power curve at each location.	'default'
keep_dims	set | None	Set of coordinates to preserve in the output. If None (default) uses wind_speed.dims.	None

Returns:

Type	Description
DataArray	xr.DataArray: Wind power in MW.

salientsdk.wind.correct_wind_density(wspd, dens=1.225, temp=286.0, elev=0.0)

Correct wind speed for air density.

Values dens, temp, and elev can be scalar numbers or DataArrays with coordinates compatible with wspd.

Parameters:

Name	Type	Description	Default
wspd	DataArray	Wind speed at hub height.	required
dens	DataArray | float	Target air density to correct to (kg/m^3). Corrects to sea level air density by default.	1.225
temp	DataArray | float	Temperature (degrees C)	286.0
elev	DataArray | float	Elevation above sea level (m). Corrects to sea level by default.	0.0

Returns:

Type	Description
DataArray	xr.DataArray: Wind speed corrected for air density.

salientsdk.wind.shear_wind(wnd_hi, wnd_lo, hgt_hh, hgt_hi=100.0, hgt_lo=10.0)

Shear wind speed to hub height.

Uses the Power Law to shear wind speed from two heights to a hub height. Will interpolate or extrapolate, as needed.

Parameters:

Name	Type	Description	Default
wnd_hi	DataArray	Wind speed at height hgt_hi.	required
wnd_lo	DataArray	Wind speed at height hgt_lo.	required
hgt_hh	DataArray	Hub height above ground level	required
hgt_hi	float	Height above ground level of wnd_hi.	100.0
hgt_lo	float	Height above ground level of wnd_lo.	10.0

Returns:

Type	Description
DataArray	xr.DataArray: Wind speed at hub height, same dimensions as wnd_hi.

salientsdk.wind.get_power_curve(turbine_model='default')

Get a power curve for a specific turbine model.

Parameters:

Name	Type	Description	Default
turbine_model	None | str | list[str] | DataArray	Turbine model to select. If None, return all available models. If a string, return the model with that name. If string is default, chooses a popular turbine model. If a list of strings or a string DataArray, will load all turbines in the list.	'default'

Return

xr.DataArray: Power curve for the selected turbine model(s). Coordinate wind_speed is the wind speed at hub height.

Solar Utilities

salientsdk.solar.data_timeseries_solar(loc, start='1950-01-01', end='-today', variable=SOLAR_VARIABLES, debias=False, destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False)

Get a historical time series of pvlib-compatible solar weather inputs.

A convenience wrapper around data_timeseries() to get solar weather data. Generates a past weather dataset suitable to pass to run_pvlib_dataset().

Parameters:

Name	Type	Description	Default
loc	Location	The location to query.	required
start	str	The start date of the time series	'1950-01-01'
end	str	The end date of the time series	'-today'
variable	list[str]	The variables to download. Defaults to ["temp", "wspd", "tsi", "dhi", "dni"] which are the inputs needed for run_pvlib_dataset().	SOLAR_VARIABLES
debias	bool	If True, debias the data to local observations. Defaults to False since debiasing does not currently support solar components like tsi, dhi, and dni.	False
destination	str	The directory to download the data to	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request. If None (default) uses get_current_session().	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate	None
verbose	bool	If True (default False) print status messages and check for NaN.	False

Returns:

Type	Description
Dataset	xr.Dataset: An hourly dataset with the following variables: - temp: temperature (C) - wspd: wind speed (m/s) - tsi: total solar irradiance, aka Global Horizontal Irradiance (W/m^2) - dhi: diffuse horizontal irradiance (W/m^2) - dni: direct normal irradiance (W/m^2) - elevation: elevation (m)

salientsdk.solar.downscale_solar(loc, date='-today', members=50, variables=SOLAR_VARIABLES, destination='-default', force=False, session=None, apikey=None, verify=None, verbose=False, **kwargs)

Get a forecast time series of pvlib-compatible solar weather inputs.

A convenience wrapper around downscale() to get solar weather data. Generates a future weather dataset suitable to pass to run_pvlib_dataset().

Parameters:

Name	Type	Description	Default
loc	Location	The location to query.	required
date	str	The start date of the time series. If date is -today, use the current date.	'-today'
members	int	The number of ensemble members to download	50
variables	list[str]	The variables to download. Defaults to ["temp", "wspd", "tsi", "dhi", "dni"] which are the inputs needed for run_pvlib_dataset().	SOLAR_VARIABLES
destination	str	The directory to download the data to	'-default'
force	bool	If False (default), don't download the data if it already exists	False
session	Session	The session object to use for the request. If None (default) uses get_current_session().	None
apikey	str | None	The API key to use for the request. In most cases, this is not needed if a session is provided.	None
verify	bool	If True (default), verify the SSL certificate	None
verbose	bool	If True (default False) print status messages and check for NaN	False
**kwargs		Additional arguments to pass to downscale()	{}

Other Parameters:

Name	Type	Description
reference_clim	str	Reference period to calculate anomalies.
version	str	The model version of the Salient blend forecast.
debias	bool	Defaults to False, note that tsi, dhi, and dni are not debiased.

Returns:

Type	Description
Dataset	xr.Dataset: An hourly dataset with the following variables: - temp: temperature (C) - wspd: wind speed (m/s) - tsi: total solar irradiance, aka Global Horizontal Irradiance (W/m^2) - dhi: diffuse horizontal irradiance (W/m^2) - dni: direct normal irradiance (W/m^2) - elevation: elevation (m)

salientsdk.solar.run_pvlib_dataset(weather, timedim='time', model_chain=None, nan_check=0.01)

Execute pvlib multiple times on a weather-inputs dataset.

Parameters:

Name	Type	Description	Default
weather	Dataset | str	Solar meteorological inputs, of the form returned by data_timeseries_solar() May also be the filename to a valid dataset.	required
timedim	str	The name of the time dimension	'time'
model_chain	ModelChain	The model chain(s) to use. If None, calls dataset_to_modelchain(weather).	None
nan_check	float	issue a warning if any month in the dataset contains more than this ratio of NaNs. Suppress with None.	0.01

Returns:

Type

Description

Dataset

xr.Dataset: A dataset with matching coordinates to ds containing data * ac = Alternating Current power * dc = Direct Current power * effective_irradiance = Effective Irradiance * poa_direct = Plane of Array Direct * poa_sky_diffuse = Plane of Array Sky Diffuse * poa_ground_diffuse = Plane of Array Ground Diffuse poa_global = poa_direct + poa+diffuse poa_diffuse = poa_sky_diffuse + poa_ground_diffuse

Hydrological Utilities

salientsdk.hydro.calc_swe(met, timedim='forecast_day')

Call the snow17 model for each location and ensemble member.

Acknowledgements: Based on Anderson (2006) and Mark Raleigh's matlab code.

Primary Citations: 1. Anderson, E. A. (1973), National Weather Service River Forecast System Snow Accumulation and Ablation Model, NOAA Tech. Memo. NWS HYDro-17, 217 pp., U.S. Dep. of Commer., Silver Spring, Md. 2. Anderson, E. A. (1976), A point energy and mass balance model of a snow cover, NOAA Tech. Rep. 19, 150 pp., U.S. Dep. of Commer., Silver Spring, Md.

Written by Joe Hamman April, 2013

Parameters:

Name	Type	Description	Default
met	Dataset	a dataset containing timedim, precip, temp, & lat	required
timedim	str	the name of the time dimension in met	'forecast_day'

Returns:

Type	Description
DataArray	xr.DataArray: a dataset containing snow water equivalent (mm)

Validation Utilities

salientsdk.skill.crps(observations, forecasts, qnt_dim='quantiles')

Calculate Continuous Ranked Probability Score.

CRPS is used to calculate the skill of a probabilistic forecast. CRPS is defined as 2 times the integral of the quantile loss over the distribution. Zero CRPS indicates a perfect forecast.

Parameters:

Name	Type	Description	Default
observations	Dataset | DataArray | str	Dataset of observed values, aka "truth", or a nc filename. observations should usually have the same coordinates as forecasts. If observations has a daily timescale to match a weekly, monthly, or quarterly timescale for forecasts.	required
forecasts	Dataset | DataArray | str | list[str] | DataFrame	Dataset of forecasted values. May also be: - a file reference to a nc file - a vector of file references to nc files - a DataFrame with a file_name column	required
qnt_dim	str	Name of the quantile dimension in the forecast array. Defaults to quantiles, which is the dimension name returned by forecast_timeseries.	'quantiles'

Returns:

Type	Description
Dataset	xr.Dataset: The CRPS of the forecasts quantiles vs. the observations. If forecasts is a vector of multiple forecast_date_<timescale>s, will also return a data variable crps_<timescale>_all denominated by forecast_date to enable subsetting or trend analysis.

salientsdk.skill.align_daily_obs_to_lead(observations, forecasts, timescale='all')

Convert daily observations to match forecasts denominated by a coarse lead time.

Parameters:

Name	Type	Description	Default
observations	str | Dataset | DataArray	Daily observed values with coordinate time. If str load NetCDF.	required
forecasts	str | Dataset | DataArray	The forecasted values with coordinate lead_<timescale> and forecast_period_<timescale>. If str, load NetCDF.	required
timescale	str | Iterable[str]	The forecast period of the forecast, corresponding to data variables lead_<timescale> and forecast_period_<timescale>. Will typically be weekly, monthly, or quarterly. If all (default), will work across each of the possible timescales.	'all'

Returns:

Type	Description
Dataset | DataArray	xr.Dataset | xr.DataArray: An aggregated version of observations with coordinate(s) lead_<timescale> instead of time.

Observed Data Utilities

:: salientsdk.observed.make_observed_ds

Constants and Variables

salientsdk.get_model_version(version='-default')

Get the current default model version.

Parameters:

Name	Type	Description	Default
version	str	If -default, return the current model version. Otherwise, return the value of version.	'-default'

Returns:

Name	Type	Description
str	str	The current model version

salientsdk.set_model_version(version)

Set the default model version.

Parameters:

Name	Type	Description	Default
version	str	The model version to set	required

salientsdk.get_current_session()

Get the current session.

All calls to the Salient API have a session argument that defaults to None. If session is not passed to the function, the api call will use the output of this function.

Returns:

Type	Description
Session	requests.Session: The current session if one was set via login() or set_current_session(), or a temporary session for use with apikey.

salientsdk.set_current_session(session)

Set the current session.

This function is called internally as a side effect of login(). In most cases, users will never need to call it explicitly.

Parameters:

Name	Type	Description	Default
session	Session | None	The session that will be returned by get_current_session(). Set None to clear the session.	required

salientsdk.get_file_destination(destination='-default', make=True)

Get the default destination for downloaded files.

Parameters:

Name	Type	Description	Default
destination	str	If -default, return the destination set by set_file_destination. Otherwise, return the value of destination.	'-default'
make	bool	If True, create the directory if it doesn't exist.	True

Returns:

Name	Type	Description
str	str	The destination for downloaded files.

salientsdk.set_file_destination(destination='salient_data', force=False)

Set the default destination for downloaded files.

Parameters:

Name	Type	Description	Default
destination	str	The default destination for downloaded files.	'salient_data'
force	bool	If True (default False), clear the cached contents of the destination directory. This will force all subsequent downloads to re-download fresh versions of the files.	False

Returns:

Name	Type	Description
str	str	The destination that was set by the function.

Copyright 2024 Salient Predictions