Python API#

Note

For questions or request for support, please reach out to the development team. Your feedback is much appreciated in evolving this API!

Core functionality#

Define Parameters#

class basd.Parameters(step_size=1, distribution=None, months=None, lower_bound: Optional[float] = None, lower_threshold: Optional[float] = None, upper_bound: Optional[float] = None, upper_threshold: Optional[float] = None, n_iterations=0, halfwin_ubc=0, trend_preservation='additive', n_quantiles=50, p_value_eps=1e-10, max_change_factor=100.0, max_adjustment_factor=9.0, randomization_seed=1, if_all_invalid_use=None, adjust_p_values=False, detrend=False, unconditional_ccs_transfer=False, trendless_bound_frequency=False, repeat_warnings=False, invalid_value_warnings=False, adjust_obs=True)[source]#

Initialize Bias Adjustment#

basd.init_bias_adjustment(obs_hist: Dataset, sim_hist: Dataset, sim_fut: Dataset, variable: str, params: Parameters, lat_chunk_size: int = 5, lon_chunk_size: int = 5, temp_path: str = 'basd_temp_path', periodic: bool = True)[source]#

Prepares data for bias adjustment process. Reshapes data to be conforming with one-another, asserts that data is suited for bias adjustment, saves details important to be passed along to bias adjustment process, and saves reshaped data to a temp directory with the correct chunks and format to be read in later.

Parameters:

  • obs_hist (xr.Dataset) – Historical observation data grid

  • sim_hist (xr.Dataset) – Historical simulation data grid

  • sim_fut (xr.Dataset) – Future simulation data grid

  • variable (str) – Name of the variable of interest

  • params (Parameters) – Object that specifies the parameters for the variable’s SD routine

  • lat_chunk_size (int) – Size of Dask chunks in latitude dimension to perform bias adjustment. If getting errors or warnings for memory, go for smaller chunks. 5x5 is an already pretty small default.

  • lon_chunk_size (int) – Size of Dask chunks in longitude dimension to perform bias adjustment

  • temp_path (str) – path to directory where intermediate files are stored

  • periodic (bool) – Whether grid wraps around globe longitudinally. Used during regridding interpolation.

Returns:

init_output – Dictionary of details that need to be passed along into the bias adjustment process

Return type:

dict

Perform Bias Adjustment#

basd.adjust_bias(init_output, output_dir: Optional[str] = None, clear_temp: bool = True, day_file: Optional[str] = None, month_file: Optional[str] = None, encoding=None, ba_attrs: Optional[dict] = None, ba_attrs_mon: Optional[dict] = None, variable_attrs: Optional[dict] = None)[source]#

Does bias adjustment at every location of input data. Save data as NetCDF (if file name(s) supplied), and save diagnostic output file.

Parameters:

  • init_output (dict) – Dictionary of details relevant to Bias Adjustment, created during initialization

  • output_dir (str) – Path to where we save the data

  • clear_temp (bool) – Whether or not to clear temporary directory when done. Cleared by default.

  • day_file (str) – Name of the output daily data .nc file. (Optional, don’t need to save daily data)

  • month_file (str) – Name of the output monthly data .nc file. (Optional, don’t need to save monthly data)

  • encoding (dict) – Parameter for to_netcdf function

  • ba_attrs (dict) – Dictionary that contains the daily data global attributes to save in the NetCDF output file metadata.

  • ba_attrs_mon (dict) – Dictionary that contains the monthly data global attributes to save in the NetCDF output file metadata.

  • variable_attrs (dict) – Dictionary that contains the variable-specific attributes to save in the NetCDF output file metadata.

Returns:

  • sim_fut_ba (xr.Dataset) – Temporal grid of adjusted observations

  • unadjusted_array (xr.Dataset) – 2D array (lat/lon), where each cell value is the number of windows which were left unadjusted at that lat/lon

  • non_standard_array (xr.Dataset) – 2D array (lat/lon), where each cell value is the number of windows which were adjusted using a non-default method

Initialize Downscaling#

basd.init_downscaling(obs_fine: Dataset, sim_coarse: Dataset, variable: str, params: Parameters, lat_chunk_size: int = 5, lon_chunk_size: int = 5, temp_path: str = 'basd_temp_path', periodic: bool = True)[source]#
Parameters:

  • obs_fine (xr.Dataset) – Fine grid of observational data

  • sim_coarse (xr.Dataset) – Coarse grid of simulated data

  • variable (str) – Name of the variable of interest

  • params (Parameters) – Object that specifies the parameters for the variable’s SD routine

  • lat_chunk_size (int) – Size of Dask chunks in latitude dimension to perform downscaling. If getting errors or warnings for memory, go for smaller chunks. 5x5 is an already pretty small default.

  • lon_chunk_size (int) – Size of Dask chunks in longitude dimension to perform downscaling.

  • temp_path (str) – path to directory where intermediate files are stored

  • periodic (bool) – Whether grid wraps around globe longitudinally. Used during regridding interpolation.

Returns:

init_output – Dictionary of details that need to be passed along into the downscaling process

Return type:

dict

Perform Downscaling#

basd.downscale(init_output, output_dir: Optional[str] = None, clear_temp: bool = True, day_file: Optional[str] = None, month_file: Optional[str] = None, encoding=None, basd_attrs: Optional[dict] = None, basd_attrs_mon: Optional[dict] = None, variable_attrs: Optional[dict] = None)[source]#

Function to downscale climate data using MBCn_SD method

Parameters:

  • init_output (dict) – Output of init_downscaling. Holds details relevant to the downscaling process scraped from input data.

  • output_dir (str) – Path to save NetCDF output

  • clear_temp (bool) – Whether or not to clean/remove intermediate files/directory

  • day_file (str) – Name of the daily output data file. None if not keeping daily data.

  • month_file (str) – Name of the monthly output data file. None if not keeping monthly data.

  • encoding (dict) – Parameter for save as netcdf function

  • basd_attrs (dict) – Dictionary of global attributes to write to output daily NetCDF

  • basd_attrs_mon (dict) – Dictionary of global attributes to write to output monthly NetCDF

  • variable_attrs (dict) – Dictionary of variable attributes to write to output NetCDF

Returns:

sim_fine – Downscaled data. Same spatial resolution as input obs_fine

Return type:

xr.Dataset