farms.utilities module

Common utilities FARMS module.

farms.utilities.check_range(data, name, rang=(0, 1))

Ensure that data values are in correct range.

farms.utilities.ti_to_radius_csv(time_index, n_cols=1)

Convert a time index to radius.

Parameters:

• time_index (pandas.core.indexes.datetimes.DatetimeIndex) – NSRDB time series. Can extract from h5 as follows: time_index = pd.to_datetime(h5[‘time_index’][…].astype(str))

• n_cols (int) – Number of columns to output. The radius vertical 1D array will be copied this number of times horizontally (np.tile).

Returns:

radius (np.array) – Array of radius values matching the time index. Shape is (len(time_index), n_cols).

farms.utilities.ti_to_radius(time_index, n_cols=1)

Calculates Earth-Sun Radius Vector.

Reference: http://www.nrel.gov/docs/fy08osti/34302.pdf

Parameters:

• time_index (pandas.core.indexes.datetimes.DatetimeIndex) – NSRDB time series. Can extract from h5 as follows: time_index = pd.to_datetime(h5[‘time_index’][…].astype(str))

• n_cols (int) – Number of columns to output. The radius vertical 1D array will be copied this number of times horizontally (np.tile).

Returns:

radius (np.array) – Array of radius values matching the time index. Shape is (len(time_index), n_cols).

farms.utilities.calc_beta(aod, alpha)

Calculate the Angstrom turbidity coeff. (beta).

Parameters:

• aod (np.ndarray) – Array of aerosol optical depth (AOD) values. Shape must match alpha.

• alpha (np.ndarray) – Array of angstrom wavelength exponent values. Shape must match aod.

Returns:

beta (np.ndarray) – Array of Angstrom turbidity coeff., i.e. AOD at 1000 nm. Shape will be same as aod and alpha. Will be tested for compliance with the mandatory interval [0, 2.2].

farms.utilities.calc_dhi(dni, ghi, sza)

Calculate the diffuse horizontal irradiance and correct the direct.

Parameters:

• dni (np.ndarray) – Direct normal irradiance.

• ghi (np.ndarray) – Global horizontal irradiance.

• sza (np.ndarray) – Solar zenith angle (degrees).

Returns:

• dhi (np.ndarray) – Diffuse horizontal irradiance. This is ensured to be non-negative.

• dni (np.ndarray) – Direct normal irradiance. This is set to zero where dhi < 0

farms.utilities.rayleigh(dhi, cs_dhi, fill_flag, rayleigh_flag=7)

Perform Rayleigh violation check (all-sky diffuse >= clearsky diffuse).

Decided not to use this in all-sky on 7/3/2019

Failed data gets filled with farms data

Parameters:

• dhi (np.ndarray) – All-sky diffuse irradiance.

• cs_dhi (np.ndarray) – Clearsky (rest) diffuse irradiance.

• fill_flag (np.ndarray) – Array of integers signifying whether irradiance has been filled.

• rayleigh_flag (int) – Fill flag for rayleigh violation.

Returns:

fill_flag (np.ndarray) – Array of integers signifying whether irradiance has been filled, with rayleigh violations marked with the rayleigh flag.

farms.utilities.merge_rest_farms(clearsky_irrad, cloudy_irrad, cloud_type)

Combine clearsky and rest data into all-sky irradiance array.

Parameters:

• clearsky_irrad (np.ndarray) – Clearsky irradiance data from REST.

• cloudy_irrad (np.ndarray) – Cloudy irradiance data from FARMS.

• cloud_type (np.ndarray) – Cloud type array which acts as a mask specifying where to take cloud/clear data.

Returns:

all_sky_irrad (np.ndarray) – All-sky (cloudy + clear) irradiance data, merged dataset from FARMS and REST.

farms.utilities.screen_cld(cld_data, rng=(0, 160))

Enforce a numeric range on cloud property data.

Parameters:

• cld_data (np.ndarray) – Cloud property data (cld_opd_dcomp, cld_reff_dcomp).

• rng (list | tuple) – Inclusive intended range of the cloud data.

Parameters:

cld_data (np.ndarray) – Cloud property data (cld_opd_dcomp, cld_reff_dcomp) with min/max values equal to rng.

farms.utilities.screen_sza(sza, lim=89.0)

Enforce an upper limit on the solar zenith angle.

Parameters:

• sza (np.ndarray) – Solar zenith angle in degrees.

• lim (int | float) – Upper limit of SZA in degrees.

Returns:

sza (np.ndarray) – Solar zenith angle in degrees with max value = lim.

farms.utilities.dark_night(irrad_data, sza, lim=89.0)

Enforce zero irradiance when solar angle >= threshold.

Parameters:

• irrad_data (np.ndarray) – DHI, DNI, or GHI.

• sza (np.ndarray) – Solar zenith angle in degrees.

• lim (int | float) – Upper limit of SZA in degrees.

Returns:

irrad_data (np.ndarray) – DHI, DNI, or GHI with zero values when sza >= lim.

farms.utilities.cloud_variability(irrad, cs_irrad, cloud_type, var_frac=0.05, distribution='uniform', option='tri', tri_center=0.9, random_seed=123)

Add syntehtic variability to irradiance when it’s cloudy.

Parameters:

• irrad (np.ndarray) – Full FARMS + REST2 merged irradiance 2D array.

• cs_irrad (np.ndarray) – REST2 clearsky irradiance without bad or missing data.

• cloud_type (np.ndarray) – Array of numerical cloud types.

• var_frac (float) – Maximum variability fraction (0.05 is 5% variability) or if distribution is “normal” this is the maximum relative standard deviation of the Variability.

• distribution (str) – Distribution shape of the Variability. Can be uniform or normal.

• option (str) – Variability function option (‘tri’ or ‘linear’).

• random_seed (int | NoneType) – Number to seed the numpy random number generator. Used to generate reproducable psuedo-random cloud variability. Numpy random will be seeded with the system time if this is None.

Returns:

irrad (np.ndarray) – Full FARMS + REST2 merged irradiance 2D array with variability added to cloudy timesteps.

farms.utilities.uniform_variability(csr, cloud_type, var_frac, option='tri', tri_center=0.9)

Get an array with uniform variability scalars centered at 1 that can be multiplied by a irradiance array with the same shape as csr.

Parameters:

• csr (np.ndarray) – REST2 clearsky irradiance without bad or missing data. This is a 2D array with (time, sites).

• cloud_type (np.ndarray) – Array of numerical cloud types.

• var_frac (float) – Maximum variability fraction (0.05 is 5% variability).

• option (str) – Variability function option (‘tri’ or ‘linear’).

• tri_center (float) – Value of the clearsky ratio at which there is maximum variability (only used for the triangular distribution).

Returns:

variability_scalar (np.ndarray) – Array with shape matching csr with uniform random numbers centered at 1 with range (1 - var_frac) to (1 + var_frac). This array can be multiplied by an irradiance array with the same shape as csr

farms.utilities.normal_variability(csr, cloud_type, var_frac, option='tri', tri_center=0.9)

Get an array with a normal distribution of variability scalars centered at 1 that can be multiplied by a irradiance array with the same shape as csr.

Parameters:

• csr (np.ndarray) – REST2 clearsky irradiance without bad or missing data. This is a 2D array with (time, sites).

• cloud_type (np.ndarray) – Array of numerical cloud types.

• var_frac (float) – One relative standard deviation variability (0.05 is a relative standard deviation of 5% variability).

• option (str) – Variability function option (‘tri’ or ‘linear’).

• tri_center (float) – Value of the clearsky ratio at which there is maximum variability (only used for the triangular distribution).

Returns:

variability_scalar (np.ndarray) – Array with shape matching csr with normally distributed random numbers centered at 1 with range (1 - var_frac) to (1 + var_frac). This array can be multiplied by an irradiance array with the same shape as csr

farms.utilities.linear_variability(csr, var_frac)

Return an array with a linear relation between clearsky ratio and maximum variability fraction. Each value in the array is the maximum variability fraction for the corresponding clearsky ratio.

Parameters:

• csr (np.ndarray) – REST2 clearsky irradiance without bad or missing data. This is a 2D array with (time, sites).

• var_frac (float) – Maximum variability fraction (0.05 is 5% variability).

Returns:

out (np.ndarray) – Array with shape matching csr with maximum variability (var_frac) when the csr = 1 (clear or thin clouds). Each value in the array is the maximum variability fraction for the corresponding clearsky ratio.

farms.utilities.tri_variability(csr, var_frac, tri_center=0.9)

Return an array with a triangular distribution between clearsky ratio and maximum variability fraction. Each value in the array is the maximum variability fraction for the corresponding clearsky ratio.

The max variability occurs when csr==tri_center, and zero variability when csr==0 or csr==1

Parameters:

• csr (np.ndarray) – REST2 clearsky irradiance without bad or missing data. This is a 2D array with (time, sites).

• var_frac (float) – Maximum variability fraction (0.05 is 5% variability).

• tri_center (float) – Value of the clearsky ratio at which there is maximum variability.

Returns:

tri (np.ndarray) – Array with shape matching csr with maximum variability (var_frac) when the csr==tri_center. Each value in the array is the maximum variability fraction for the corresponding clearsky ratio.