bias_correction

bias_correction provides bias-correction methods for one-dimensional NumPy/Pandas series and labeled Xarray objects. Use XBiasCorrection for multi-dimensional or gridded data, such as (time, lat, lon) climate grids, as long as they include the time dimension used for correction. It is commonly used to adjust model or scenario data against a reference data set.

Implemented methods include:

• basic_quantile: empirical quantile mapping.
• modified_quantile: modified quantile mapping with median and IQR scaling.
• gamma_mapping: scaled distribution mapping for non-negative precipitation-like data.
• normal_mapping: scaled distribution mapping for approximately normally distributed data.

Installation

Install with pip:

pip install bias-correction

Install the latest code directly from GitHub:

pip install git+https://github.com/pankajkarman/bias_correction.git

Install with conda:

conda install -c conda-forge bias_correction

Documentation

Latest documentation is available here.

Quickstart

Use BiasCorrection for one-dimensional NumPy arrays or Pandas Series:

import numpy as np
from bias_correction import BiasCorrection

reference = np.array([0.2, 0.4, 0.8, 1.3, 2.1])
model = np.array([0.1, 0.3, 0.6, 1.0, 1.7])
scenario = np.array([0.2, 0.5, 1.1, 1.8, 2.4])

bc = BiasCorrection(reference, model, scenario)
corrected = bc.correct(method="basic_quantile")

Use XBiasCorrection for Xarray DataArray or Dataset inputs:

import xarray as xr
from bias_correction import XBiasCorrection

reference = xr.DataArray([0.2, 0.4, 0.8, 1.3, 2.1], dims=["time"])
model = xr.DataArray([0.1, 0.3, 0.6, 1.0, 1.7], dims=["time"])
scenario = xr.DataArray([0.2, 0.5, 1.1, 1.8, 2.4], dims=["time"])

xbc = XBiasCorrection(reference, model, scenario, dim="time")
corrected = xbc.correct(method="basic_quantile")

For multi-dimensional Xarray data, pass the name of the time dimension with dim. Corrections are applied along that dimension at each remaining grid point:

reference = xr.DataArray(ref_values, dims=["time", "lat", "lon"])
model = xr.DataArray(model_values, dims=["time", "lat", "lon"])
scenario = xr.DataArray(scenario_values, dims=["time", "lat", "lon"])

xbc = XBiasCorrection(reference, model, scenario, dim="time")
corrected = xbc.correct(method="modified_quantile")

Method Guide

All methods compare three aligned data sets:

• obs_data / reference: observed or trusted reference data.
• mod_data / model: model data over the reference period.
• sce_data / scenario: model-period data to correct, such as a future projection or forecast.

Choose a method with correct(method=...):

corrected = bc.correct(method="modified_quantile")

gamma_mapping treats values below lower_limit as dry or zero events. By default, lower_limit=0.1. It is best suited for precipitation-like data with many zeros and positive skew.

normal_mapping detrends each input series before fitting normal distributions, then adds the scenario trend back into the corrected values.

When BiasCorrection receives a Pandas Series as sce_data, it returns a Series with the original index preserved. BiasCorrection expects one-dimensional inputs; use XBiasCorrection for netCDF-style or gridded data. XBiasCorrection preserves Xarray coordinates and restores the corrected output to the original sce_data dimension order. For multi-dimensional Xarray inputs, each input must include the correction dimension, usually time.

By default, correction methods preserve the underlying SciPy/statsmodels behavior and may raise when inputs contain NaNs. Pass skipna=True to ignore non-finite values in the reference/model samples, correct only finite scenario values, and keep NaNs in the scenario output. This is useful for masked gridded data, such as ocean cells in land-only climate variables:

corrected = xbc.correct(method="normal_mapping", skipna=True)

Examples by Method

The examples below use the same input arrays so the method differences are easy to compare:

import numpy as np
from bias_correction import BiasCorrection

reference = np.array([0.0, 0.2, 0.6, 1.0, 1.7, 2.4, 3.1, 4.0])
model = np.array([0.0, 0.1, 0.4, 0.8, 1.3, 1.9, 2.5, 3.2])
scenario = np.array([0.0, 0.3, 0.7, 1.2, 1.8, 2.6, 3.3, 4.5])

bc = BiasCorrection(reference, model, scenario)

Basic quantile mapping:

corrected = bc.correct(method="basic_quantile")

Modified quantile mapping:

corrected = bc.correct(method="modified_quantile")

Gamma mapping for precipitation-like data:

corrected = bc.correct(method="gamma_mapping", lower_limit=0.1)

Normal scaled distribution mapping:

corrected = bc.correct(method="normal_mapping")

The same method names work with Xarray inputs:

import xarray as xr
from bias_correction import XBiasCorrection

reference = xr.DataArray(reference, dims=["time"])
model = xr.DataArray(model, dims=["time"])
scenario = xr.DataArray(scenario, dims=["time"])

xbc = XBiasCorrection(reference, model, scenario, dim="time")
corrected = xbc.correct(method="modified_quantile")

Multi-dimensional Xarray grids work the same way when they include the correction dimension:

reference = xr.DataArray(ref_values, dims=["time", "lat", "lon"])
model = xr.DataArray(model_values, dims=["time", "lat", "lon"])
scenario = xr.DataArray(scenario_values, dims=["time", "lat", "lon"])

xbc = XBiasCorrection(reference, model, scenario, dim="time")
corrected = xbc.correct(method="gamma_mapping", lower_limit=0.1)