API reference

earthcarekit.calval

Functions for EarthCARE calibration and validation.

Notes

This module depends on other internal modules:

• earthcarekit.constants
• earthcarekit.filter
• earthcarekit.plot
• earthcarekit.data
• earthcarekit.read
• earthcarekit.site
• earthcarekit.typing
• earthcarekit.utils

---

compare_bsc_ext_lr_depol

compare_bsc_ext_lr_depol(
    input_ec: str | Dataset,
    input_ground: str | Dataset | None = None,
    time_var_ground: str = "time",
    height_var_ground: str = "height",
    bsc_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    ext_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    lr_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    depol_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    input_ec2: str | Dataset | None = None,
    input_ec3: str | Dataset | None = None,
    input_ec4: str | Dataset | None = None,
    input_ground2: str | Dataset | None = None,
    input_ground3: str | Dataset | None = None,
    input_ground4: str | Dataset | None = None,
    time_var_ground2: str | None = None,
    height_var_ground2: str | None = None,
    time_var_ground3: str | None = None,
    height_var_ground3: str | None = None,
    time_var_ground4: str | None = None,
    height_var_ground4: str | None = None,
    bsc_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    bsc_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    bsc_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    site: SiteLike | None = None,
    radius_km: float = 100.0,
    resolution: str = "_low_resolution",
    resolution2: str | None = None,
    resolution3: str | None = None,
    resolution4: str | None = None,
    height_range: tuple[float, float] | None = (0, 30000.0),
    selection_height_range: tuple[float, float] | None = None,
    selection_height_range_bsc: tuple[float, float] | None = None,
    selection_height_range_ext: tuple[float, float] | None = None,
    selection_height_range_lr: tuple[float, float] | None = None,
    selection_height_range_depol: tuple[float, float] | None = None,
    value_range_bsc: ValueRangeLike | None = (0, 8e-06),
    value_range_ext: ValueRangeLike | None = (0, 0.0003),
    value_range_lr: ValueRangeLike | None = (0, 100),
    value_range_depol: ValueRangeLike | None = (0, 0.6),
    colors_ec: list[str] = ["ec:red", "ec:orange", "ec:yellow", "ec:purple"],
    colors_ground: list[str] = [
        "ec:blue",
        "ec:darkblue",
        "ec:lightgreen",
        "ec:darkgreen",
        "ec:purple",
    ],
    linewidth_ec: list[float | int] | float | int = 1.5,
    linewidth_ground: list[float | int] | float | int = 1.5,
    linestyle_ec: list[str] | str = "solid",
    linestyle_ground: list[str] | str = "solid",
    label_ec: list[str | None] = [],
    label_ground: list[str | None] = [],
    alpha: float = 1.0,
    show_steps: bool = DEFAULT_PROFILE_SHOW_STEPS,
    show_error_ec: bool = False,
    show_quality_status: bool = False,
    show_rebinned: bool = False,
    quality_status_width_scale: float = 1.0,
    quality_status_var: str = "quality_status",
    quality_status_value_range: tuple[float | None, float | None] | None = None,
    to_mega: bool = False,
    single_figsize: tuple[float | int, float | int] = (5 * CM_AS_INCH, 12 * CM_AS_INCH),
    label_bsc: str = "Bsc. coeff.",
    label_ext: str = "Ext. coeff.",
    label_lr: str = "Lidar ratio",
    label_depol: str = "Depol. ratio",
    units_bsc: str = "m$^{-1}$ sr$^{-1}$",
    units_ext: str = "m$^{-1}$",
    units_lr: str = "sr",
    units_depol: str = "",
    verbose: bool = True,
) -> _CompareBscExtLRDepolResults

Compares Lidar profiles from up to 4 EarthCARE and 4 ground-based datasets.

Creates plots and statistics for backscatter, extinction, lidar ratio, and depolarization.

Parameters:

Name	Type	Description	Default
input_ec	str | Dataset	EarthCARE dataset or path (primary).	required
input_ground	str | Dataset | None	Ground-based dataset or path (primary).	None
time_var_ground	str	Time variable name in ground dataset.	'time'
height_var_ground	str	Height variable name in ground dataset.	'height'
bsc_var_ground	str | tuple[str, str] | list[str | tuple[str, str]]	Backscatter variable name(s) in ground dataset (e.g., "bsc" or [("bsc", "bsc_err"), "bsc2"]).	[]
ext_var_ground	str | tuple[str, str] | list[str | tuple[str, str]]	Extinction variable name(s) in ground dataset.	[]
lr_var_ground	str | tuple[str, str] | list[str | tuple[str, str]]	Lidar ratio variable name(s) in ground dataset.	[]
depol_var_ground	str | tuple[str, str] | list[str | tuple[str, str]]	Depolarization ratio variable name(s) in ground dataset.	[]
input_ec2	str | Dataset | None	Optional second EarthCARE dataset.	None
input_ec3	str | Dataset | None	Optional third EarthCARE dataset.	None
input_ec4	str | Dataset | None	Optional fourth EarthCARE dataset.	None
input_ground2	str | Dataset | None	Optional second ground-based dataset.	None
input_ground3	str | Dataset | None	Optional third ground-based dataset.	None
input_ground4	str | Dataset | None	Optional fourth ground-based dataset.	None
time_var_ground2	str | None	Time variable name in second ground dataset.	None
height_var_ground2	str | None	Height variable name in second ground dataset.	None
time_var_ground3	str | None	Time variable name in third ground dataset.	None
height_var_ground3	str | None	Height variable name in third ground dataset.	None
time_var_ground4	str | None	Time variable name in fourth ground dataset.	None
height_var_ground4	str | None	Height variable name in fourth ground dataset.	None
bsc_var_ground2	str | tuple[str, str] | list[str | tuple[str, str]] | None	Backscatter variable name(s) in second ground dataset.	None
ext_var_ground2	str | tuple[str, str] | list[str | tuple[str, str]] | None	Extinction variable name(s) in second ground dataset.	None
lr_var_ground2	str | tuple[str, str] | list[str | tuple[str, str]] | None	Lidar ratio variable name(s) in second ground dataset.	None
depol_var_ground2	str | tuple[str, str] | list[str | tuple[str, str]] | None	Depolarization ratio variable name(s) in second ground dataset.	None
bsc_var_ground3	str | tuple[str, str] | list[str | tuple[str, str]] | None	Backscatter variable name(s) in third ground dataset.	None
ext_var_ground3	str | tuple[str, str] | list[str | tuple[str, str]] | None	Extinction variable name(s) in third ground dataset.	None
lr_var_ground3	str | tuple[str, str] | list[str | tuple[str, str]] | None	Lidar ratio variable name(s) in third ground dataset.	None
depol_var_ground3	str | tuple[str, str] | list[str | tuple[str, str]] | None	Depolarization ratio variable name(s) in third ground dataset.	None
bsc_var_ground4	str | tuple[str, str] | list[str | tuple[str, str]] | None	Backscatter variable name(s) in fourth ground dataset.	None
ext_var_ground4	str | tuple[str, str] | list[str | tuple[str, str]] | None	Extinction variable name(s) in fourth ground dataset.	None
lr_var_ground4	str | tuple[str, str] | list[str | tuple[str, str]] | None	Lidar ratio variable name(s) in fourth ground dataset.	None
depol_var_ground4	str | tuple[str, str] | list[str | tuple[str, str]] | None	Depolarization ratio variable name(s) in fourth ground dataset.	None
site	SiteLike | None	Ground site for spatial filtering.	None
radius_km	float	Search radius around site in kilometers.	100.0
resolution	str	EarthCARE resolution suffix (e.g., "_low_resolution").	'_low_resolution'
resolution2	str | None	Resolution suffix for second EarthCARE dataset.	None
resolution3	str | None	Resolution suffix for third EarthCARE dataset.	None
resolution4	str | None	Resolution suffix for fourth EarthCARE dataset.	None
height_range	tuple[float, float] | None	Plot height range in meters.	(0, 30000.0)
selection_height_range	tuple[float, float] | None	Height range for statistics (applies to all variables).	None
selection_height_range_bsc	tuple[float, float] | None	Height range for backscatter statistics.	None
selection_height_range_ext	tuple[float, float] | None	Height range for extinction statistics.	None
selection_height_range_lr	tuple[float, float] | None	Height range for lidar ratio statistics.	None
selection_height_range_depol	tuple[float, float] | None	Height range for depolarization statistics.	None
value_range_bsc	ValueRangeLike | None	X-axis limits for backscatter plot.	(0, 8e-06)
value_range_ext	ValueRangeLike | None	X-axis limits for extinction plot.	(0, 0.0003)
value_range_lr	ValueRangeLike | None	X-axis limits for lidar ratio plot.	(0, 100)
value_range_depol	ValueRangeLike | None	X-axis limits for depolarization plot.	(0, 0.6)
colors_ec	list[str]	Colors for EarthCARE profiles.	['ec:red', 'ec:orange', 'ec:yellow', 'ec:purple']
colors_ground	list[str]	Colors for ground-based profiles.	['ec:blue', 'ec:darkblue', 'ec:lightgreen', 'ec:darkgreen', 'ec:purple']
linewidth_ec	list[float | int] | float | int	Line width(s) for EarthCARE profiles.	1.5
linewidth_ground	list[float | int] | float | int	Line width(s) for ground-based profiles.	1.5
linestyle_ec	list[str] | str	Line style(s) for EarthCARE profiles.	'solid'
linestyle_ground	list[str] | str	Line style(s) for ground-based profiles.	'solid'
label_ec	list[str | None]	Legend labels for EarthCARE profiles.	[]
label_ground	list[str | None]	Legend labels for ground-based profiles.	[]
alpha	float	Line transparency (0-1).	1.0
show_steps	bool	Plot step functions instead of bin centers if True.	DEFAULT_PROFILE_SHOW_STEPS
show_error_ec	bool	Plot error ribbons for EarthCARE profiles if True.	False
show_rebinned	bool	Rebin ground data to EarthCARE grid if True.	False
show_quality_status	bool	Plot quality status bars if True.	False
show_rebinned	bool	Rebin ground data to EarthCARE grid if True.	False
quality_status_width_scale	float	Scale factor for quality status bar width.	1.0
quality_status_var	str	Variable name for quality status.	'quality_status'
quality_status_value_range	tuple[float | None, float | None] | None	Value range for quality status display.	None
to_mega	bool	Convert units to Mm-1 sr-1/Mm-1 if True.	False
single_figsize	tuple[float | int, float | int]	Subfigure size (width, height) in inches.	(5 * CM_AS_INCH, 12 * CM_AS_INCH)
label_bsc	str	Label for backscatter subfigure.	'Bsc. coeff.'
label_ext	str	Label for extinction subfigure.	'Ext. coeff.'
label_lr	str	Label for lidar ratio subfigure.	'Lidar ratio'
label_depol	str	Label for depolarization subfigure.	'Depol. ratio'
units_bsc	str	Units for backscatter axis.	'm$^{-1}$ sr$^{-1}$'
units_ext	str	Units for extinction axis.	'm$^{-1}$'
units_lr	str	Units for lidar ratio axis.	'sr'
units_depol	str	Units for depolarization axis.	''
verbose	bool	Print logs to console if True.	True

Returns:

Type	Description
_CompareBscExtLRDepolResults	Results as a _CompareBscExtLRDepolResults object with figures and statistics results.fig: The matplotlib figure results.fig_bsc: Backscatter subfigure as ProfileFigure results.fig_ext: Extinction subfigure as ProfileFigure results.fig_lr: Lidar ratio subfigure as ProfileFigure results.fig_depol: Depol. ratio subfigure as ProfileFigure results.stats: Statistical results as a pandas.DataFrame

Source code in earthcarekit/calval/_compare_bsc_ext_lr_depol.py

def compare_bsc_ext_lr_depol(
    input_ec: str | xr.Dataset,
    input_ground: str | xr.Dataset | None = None,
    time_var_ground: str = "time",
    height_var_ground: str = "height",
    bsc_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    ext_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    lr_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    depol_var_ground: str | tuple[str, str] | list[str | tuple[str, str]] = [],
    input_ec2: str | xr.Dataset | None = None,
    input_ec3: str | xr.Dataset | None = None,
    input_ec4: str | xr.Dataset | None = None,
    input_ground2: str | xr.Dataset | None = None,
    input_ground3: str | xr.Dataset | None = None,
    input_ground4: str | xr.Dataset | None = None,
    time_var_ground2: str | None = None,
    height_var_ground2: str | None = None,
    time_var_ground3: str | None = None,
    height_var_ground3: str | None = None,
    time_var_ground4: str | None = None,
    height_var_ground4: str | None = None,
    bsc_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground2: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground2: (str | tuple[str, str] | list[str | tuple[str, str]] | None) = None,
    bsc_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground3: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground3: (str | tuple[str, str] | list[str | tuple[str, str]] | None) = None,
    bsc_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    ext_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    lr_var_ground4: str | tuple[str, str] | list[str | tuple[str, str]] | None = None,
    depol_var_ground4: (str | tuple[str, str] | list[str | tuple[str, str]] | None) = None,
    site: SiteLike | None = None,
    radius_km: float = 100.0,
    resolution: str = "_low_resolution",
    resolution2: str | None = None,
    resolution3: str | None = None,
    resolution4: str | None = None,
    height_range: tuple[float, float] | None = (0, 30e3),
    selection_height_range: tuple[float, float] | None = None,
    selection_height_range_bsc: tuple[float, float] | None = None,
    selection_height_range_ext: tuple[float, float] | None = None,
    selection_height_range_lr: tuple[float, float] | None = None,
    selection_height_range_depol: tuple[float, float] | None = None,
    value_range_bsc: ValueRangeLike | None = (0, 8e-6),
    value_range_ext: ValueRangeLike | None = (0, 3e-4),
    value_range_lr: ValueRangeLike | None = (0, 100),
    value_range_depol: ValueRangeLike | None = (0, 0.6),
    colors_ec: list[str] = [
        "ec:red",
        "ec:orange",
        "ec:yellow",
        "ec:purple",
    ],
    colors_ground: list[str] = [
        "ec:blue",
        "ec:darkblue",
        "ec:lightgreen",
        "ec:darkgreen",
        "ec:purple",
    ],
    linewidth_ec: list[float | int] | float | int = 1.5,
    linewidth_ground: list[float | int] | float | int = 1.5,
    linestyle_ec: list[str] | str = "solid",
    linestyle_ground: list[str] | str = "solid",
    label_ec: list[str | None] = [],
    label_ground: list[str | None] = [],
    alpha: float = 1.0,
    show_steps: bool = DEFAULT_PROFILE_SHOW_STEPS,
    show_error_ec: bool = False,
    show_quality_status: bool = False,
    show_rebinned: bool = False,
    quality_status_width_scale: float = 1.0,
    quality_status_var: str = "quality_status",
    quality_status_value_range: tuple[float | None, float | None] | None = None,
    to_mega: bool = False,
    single_figsize: tuple[float | int, float | int] = (5 * CM_AS_INCH, 12 * CM_AS_INCH),
    label_bsc: str = "Bsc. coeff.",
    label_ext: str = "Ext. coeff.",
    label_lr: str = "Lidar ratio",
    label_depol: str = "Depol. ratio",
    units_bsc: str = "m$^{-1}$ sr$^{-1}$",
    units_ext: str = "m$^{-1}$",
    units_lr: str = "sr",
    units_depol: str = "",
    verbose: bool = True,
) -> _CompareBscExtLRDepolResults:
    """Compares Lidar profiles from up to 4 EarthCARE and 4 ground-based datasets.

    Creates plots and statistics for backscatter, extinction, lidar ratio, and depolarization.

    Args:
        input_ec: EarthCARE dataset or path (primary).
        input_ground: Ground-based dataset or path (primary).
        time_var_ground: Time variable name in ground dataset.
        height_var_ground: Height variable name in ground dataset.
        bsc_var_ground: Backscatter variable name(s) in ground dataset (e.g., `"bsc"` or `[("bsc", "bsc_err"), "bsc2"]`).
        ext_var_ground: Extinction variable name(s) in ground dataset.
        lr_var_ground: Lidar ratio variable name(s) in ground dataset.
        depol_var_ground: Depolarization ratio variable name(s) in ground dataset.
        input_ec2: Optional second EarthCARE dataset.
        input_ec3: Optional third EarthCARE dataset.
        input_ec4: Optional fourth EarthCARE dataset.
        input_ground2: Optional second ground-based dataset.
        input_ground3: Optional third ground-based dataset.
        input_ground4: Optional fourth ground-based dataset.
        time_var_ground2: Time variable name in second ground dataset.
        height_var_ground2: Height variable name in second ground dataset.
        time_var_ground3: Time variable name in third ground dataset.
        height_var_ground3: Height variable name in third ground dataset.
        time_var_ground4: Time variable name in fourth ground dataset.
        height_var_ground4: Height variable name in fourth ground dataset.
        bsc_var_ground2: Backscatter variable name(s) in second ground dataset.
        ext_var_ground2: Extinction variable name(s) in second ground dataset.
        lr_var_ground2: Lidar ratio variable name(s) in second ground dataset.
        depol_var_ground2: Depolarization ratio variable name(s) in second ground dataset.
        bsc_var_ground3: Backscatter variable name(s) in third ground dataset.
        ext_var_ground3: Extinction variable name(s) in third ground dataset.
        lr_var_ground3: Lidar ratio variable name(s) in third ground dataset.
        depol_var_ground3: Depolarization ratio variable name(s) in third ground dataset.
        bsc_var_ground4: Backscatter variable name(s) in fourth ground dataset.
        ext_var_ground4: Extinction variable name(s) in fourth ground dataset.
        lr_var_ground4: Lidar ratio variable name(s) in fourth ground dataset.
        depol_var_ground4: Depolarization ratio variable name(s) in fourth ground dataset.
        site: Ground site for spatial filtering.
        radius_km: Search radius around site in kilometers.
        resolution: EarthCARE resolution suffix (e.g., "_low_resolution").
        resolution2: Resolution suffix for second EarthCARE dataset.
        resolution3: Resolution suffix for third EarthCARE dataset.
        resolution4: Resolution suffix for fourth EarthCARE dataset.
        height_range: Plot height range in meters.
        selection_height_range: Height range for statistics (applies to all variables).
        selection_height_range_bsc: Height range for backscatter statistics.
        selection_height_range_ext: Height range for extinction statistics.
        selection_height_range_lr: Height range for lidar ratio statistics.
        selection_height_range_depol: Height range for depolarization statistics.
        value_range_bsc: X-axis limits for backscatter plot.
        value_range_ext: X-axis limits for extinction plot.
        value_range_lr: X-axis limits for lidar ratio plot.
        value_range_depol: X-axis limits for depolarization plot.
        colors_ec: Colors for EarthCARE profiles.
        colors_ground: Colors for ground-based profiles.
        linewidth_ec: Line width(s) for EarthCARE profiles.
        linewidth_ground: Line width(s) for ground-based profiles.
        linestyle_ec: Line style(s) for EarthCARE profiles.
        linestyle_ground: Line style(s) for ground-based profiles.
        label_ec: Legend labels for EarthCARE profiles.
        label_ground: Legend labels for ground-based profiles.
        alpha: Line transparency (0-1).
        show_steps: Plot step functions instead of bin centers if True.
        show_error_ec: Plot error ribbons for EarthCARE profiles if True.
        show_rebinned: Rebin ground data to EarthCARE grid if True.
        show_quality_status: Plot quality status bars if True.
        show_rebinned: Rebin ground data to EarthCARE grid if True.
        quality_status_width_scale: Scale factor for quality status bar width.
        quality_status_var: Variable name for quality status.
        quality_status_value_range: Value range for quality status display.
        to_mega: Convert units to Mm-1 sr-1/Mm-1 if True.
        single_figsize: Subfigure size (width, height) in inches.
        label_bsc: Label for backscatter subfigure.
        label_ext: Label for extinction subfigure.
        label_lr: Label for lidar ratio subfigure.
        label_depol: Label for depolarization subfigure.
        units_bsc: Units for backscatter axis.
        units_ext: Units for extinction axis.
        units_lr: Units for lidar ratio axis.
        units_depol: Units for depolarization axis.
        verbose: Print logs to console if True.

    Returns:
        Results as a `_CompareBscExtLRDepolResults` object with figures and statistics

            - `results.fig`: The `matplotlib` figure
            - `results.fig_bsc`: Backscatter subfigure as `ProfileFigure`
            - `results.fig_ext`: Extinction subfigure as `ProfileFigure`
            - `results.fig_lr`: Lidar ratio subfigure as `ProfileFigure`
            - `results.fig_depol`: Depol. ratio subfigure as `ProfileFigure`
            - `results.stats`: Statistical results as a `pandas.DataFrame`
    """
    _logger = logging.getLogger()
    ctx = nullcontext() if verbose else silence_logger(_logger)
    with ctx:
        _vars_main: list[str | tuple[str, str]] = _get_ec_vars(
            input_ec,
            resolution,
            show_error=show_error_ec,
        )
        _closest: bool = _get_ec_is_closest(input_ec)

        label = [
            label_bsc,
            label_ext,
            label_lr,
            label_depol,
        ]

        units = [
            units_bsc,
            units_ext,
            units_lr,
            units_depol,
        ]

        if not isinstance(resolution2, str):
            resolution2 = resolution
        if not isinstance(resolution3, str):
            resolution3 = resolution
        if not isinstance(resolution4, str):
            resolution4 = resolution

        if not isinstance(time_var_ground2, str):
            time_var_ground2 = time_var_ground
        if not isinstance(time_var_ground3, str):
            time_var_ground3 = time_var_ground
        if not isinstance(time_var_ground4, str):
            time_var_ground4 = time_var_ground

        if not isinstance(height_var_ground2, str):
            height_var_ground2 = height_var_ground
        if not isinstance(height_var_ground3, str):
            height_var_ground3 = height_var_ground
        if not isinstance(height_var_ground4, str):
            height_var_ground4 = height_var_ground

        if bsc_var_ground2 is None:
            bsc_var_ground2 = bsc_var_ground
        if bsc_var_ground3 is None:
            bsc_var_ground3 = bsc_var_ground
        if bsc_var_ground4 is None:
            bsc_var_ground4 = bsc_var_ground

        if ext_var_ground2 is None:
            ext_var_ground2 = ext_var_ground
        if ext_var_ground3 is None:
            ext_var_ground3 = ext_var_ground
        if ext_var_ground4 is None:
            ext_var_ground4 = ext_var_ground

        if lr_var_ground2 is None:
            lr_var_ground2 = lr_var_ground
        if lr_var_ground3 is None:
            lr_var_ground3 = lr_var_ground
        if lr_var_ground4 is None:
            lr_var_ground4 = lr_var_ground

        if depol_var_ground2 is None:
            depol_var_ground2 = depol_var_ground
        if depol_var_ground3 is None:
            depol_var_ground3 = depol_var_ground
        if depol_var_ground4 is None:
            depol_var_ground4 = depol_var_ground

        _vars_main2: list[str | tuple[str, str]] | None = None
        _closest2: bool | None = None
        if input_ec2 is not None:
            _vars_main2 = _get_ec_vars(
                input_ec2,
                resolution2,
                show_error=show_error_ec,
            )
            _closest2 = _get_ec_is_closest(input_ec2)

        _vars_main3: list[str | tuple[str, str]] | None = None
        _closest3: bool | None = None
        if input_ec3 is not None:
            _vars_main3 = _get_ec_vars(
                input_ec3,
                resolution3,
                show_error=show_error_ec,
            )
            _closest3 = _get_ec_is_closest(input_ec3)

        _vars_main4: list[str | tuple[str, str]] | None = None
        _closest4: bool | None = None
        if input_ec4 is not None:
            _vars_main4 = _get_ec_vars(
                input_ec4,
                resolution4,
                show_error=show_error_ec,
            )
            _closest4 = _get_ec_is_closest(input_ec4)

        with (
            read_product(input_ec) as ds_ec,
            nullcontext(None if input_ec2 is None else read_product(input_ec2)) as ds_ec2,
            nullcontext(None if input_ec3 is None else read_product(input_ec3)) as ds_ec3,
            nullcontext(None if input_ec4 is None else read_product(input_ec4)) as ds_ec4,
            nullcontext(None if input_ground is None else read_any(input_ground)) as ds_target,
            nullcontext(None if input_ground2 is None else read_any(input_ground2)) as ds_target2,
            nullcontext(None if input_ground3 is None else read_any(input_ground3)) as ds_target3,
            nullcontext(None if input_ground4 is None else read_any(input_ground4)) as ds_target4,
        ):
            ncols: int = 4
            width_scale: float | list[float] = 1.0
            if show_quality_status:
                ncols = 5
                width_scale = [1.0, 1.0, 1.0, 1.0, quality_status_width_scale]
            _output = create_column_figure_layout(
                ncols=ncols,
                single_figsize=single_figsize,
                margin=0.6,
                width_scale=width_scale,
            )
            fig = _output.fig
            axs = _output.axs

            vars_target: list[str | tuple[str, str] | list[str | tuple[str, str]]] = [
                bsc_var_ground,
                ext_var_ground,
                lr_var_ground,
                depol_var_ground,
            ]

            vars_target2: list[str | tuple[str, str] | list[str | tuple[str, str]]] = [
                bsc_var_ground2,
                ext_var_ground2,
                lr_var_ground2,
                depol_var_ground2,
            ]

            vars_target3: list[str | tuple[str, str] | list[str | tuple[str, str]]] = [
                bsc_var_ground3,
                ext_var_ground3,
                lr_var_ground3,
                depol_var_ground3,
            ]

            vars_target4: list[str | tuple[str, str] | list[str | tuple[str, str]]] = [
                bsc_var_ground4,
                ext_var_ground4,
                lr_var_ground4,
                depol_var_ground4,
            ]

            value_range: list = [
                value_range_bsc,
                value_range_ext,
                value_range_lr,
                value_range_depol,
            ]

            if selection_height_range_bsc is None:
                selection_height_range_bsc = selection_height_range
            if selection_height_range_ext is None:
                selection_height_range_ext = selection_height_range
            if selection_height_range_lr is None:
                selection_height_range_lr = selection_height_range
            if selection_height_range_depol is None:
                selection_height_range_depol = selection_height_range

            _selection_height_range = [
                selection_height_range_bsc,
                selection_height_range_ext,
                selection_height_range_lr,
                selection_height_range_depol,
            ]

            pfs: list[ProfileFigure] = []
            dfs: list[pd.DataFrame] = []
            for i in range(len(_vars_main)):
                _flip_height_axis: bool = False
                _show_height_ticks: bool = True
                _show_height_label: bool = False

                if i == 0:
                    _show_height_label = True
                    _show_height_ticks = True
                _pf, _df = compare_ec_profiles_with_target(
                    ds_ec=ds_ec,
                    ds_ec2=ds_ec2,
                    ds_ec3=ds_ec3,
                    ds_ec4=ds_ec4,
                    ds_target=ds_target,
                    ds_target2=ds_target2,
                    ds_target3=ds_target3,
                    ds_target4=ds_target4,
                    var_ec=_vars_main[i],
                    var_ec2=None if _vars_main2 is None else _vars_main2[i],
                    var_ec3=None if _vars_main3 is None else _vars_main3[i],
                    var_ec4=None if _vars_main4 is None else _vars_main4[i],
                    var_target=vars_target[i],
                    var_target2=vars_target2[i],
                    var_target3=vars_target3[i],
                    var_target4=vars_target4[i],
                    selection_height_range=_selection_height_range[i],
                    height_range=height_range,
                    site=site,
                    radius_km=radius_km,
                    closest=_closest,
                    closest2=False if _closest2 is None else _closest2,
                    closest3=False if _closest3 is None else _closest3,
                    closest4=False if _closest4 is None else _closest4,
                    time_var_target=time_var_ground,
                    height_var_target=height_var_ground,
                    time_var_target2=time_var_ground2,
                    height_var_target2=height_var_ground2,
                    time_var_target3=time_var_ground3,
                    height_var_target3=height_var_ground3,
                    time_var_target4=time_var_ground4,
                    height_var_target4=height_var_ground4,
                    ax=axs[i],
                    label=label[i],
                    units=units[i],
                    value_range=value_range[i],
                    flip_height_axis=_flip_height_axis,
                    show_height_ticks=_show_height_ticks,
                    show_height_label=_show_height_label,
                    colors_ec=colors_ec,
                    colors_ground=colors_ground,
                    linewidth_ec=linewidth_ec,
                    linewidth_ground=linewidth_ground,
                    linestyle_ec=linestyle_ec,
                    linestyle_ground=linestyle_ground,
                    label_ec=label_ec,
                    label_ground=label_ground,
                    alpha=alpha,
                    show_steps=show_steps,
                    show_rebinned=show_rebinned,
                    to_mega=False if i > 1 else to_mega,
                    single_figsize=single_figsize,
                )
                pfs.append(_pf)
                dfs.append(_df)
            df = pd.concat(dfs, ignore_index=True)

            # Optional: plot quality status
            if show_quality_status:
                _dss: list = []
                _var: str = quality_status_var
                _ps_qs: list[Profile] = []
                for _ds in [ds_ec, ds_ec2, ds_ec3, ds_ec4]:
                    if (
                        isinstance(_ds, xr.Dataset)
                        and not any([_ds.equals(x) for x in _dss])
                        and _var in _ds
                    ):
                        p_qs = _extract_earthcare_profile(
                            ds=_ds,
                            var=_var,
                            site=site,
                            radius_km=radius_km,
                            closest=True,
                        )
                        p_qs.platform = (
                            "EC"
                            if p_qs.platform is None
                            else (
                                p_qs.platform.replace("res.", "")
                                .replace("low", "")
                                .replace("medium", "")
                                .replace("high", "")
                                .strip()
                            )
                        )
                        _ps_qs.append(p_qs)
                        _dss.append(_ds)
                vrange = quality_status_value_range
                if vrange is None and _var == "quality_status":
                    vrange = (-0.2, 4.2)
                _plot_profiles(
                    _ps_qs,
                    ax=axs[-1],
                    selection_height_range=selection_height_range,
                    height_range=height_range,
                    value_range=vrange,
                    flip_height_axis=False,
                    show_height_ticks=True,
                    show_height_label=False,
                    colors_ec=colors_ec,
                    linewidth_ec=linewidth_ec,
                    linestyle_ec=linestyle_ec,
                    label_ec=label_ec,
                    alpha=alpha,
                    show_steps=show_steps,
                    figsize=single_figsize,
                )

    return _CompareBscExtLRDepolResults(
        fig=fig,
        fig_bsc=pfs[0],
        fig_ext=pfs[1],
        fig_lr=pfs[2],
        fig_depol=pfs[3],
        stats=df,
    )

compute_anom_depol_statistics

compute_anom_depol_statistics(
    ds_anom: Dataset,
    selection_height_range: DistanceRangeLike,
    is_rayleigh_corrected: bool = False,
    rayleigh_correction_factor: float = 0.004,
    **kwargs
) -> _ANOMDepolCalculationResults

Calculate depolarization statistics and uncertainties within a height range.

This function adds the depol. ratio (DPOL) calculated from co- (CPOL) and cross-polarized (XPOL) attenuated backscatter to the dataset (ATL_NOM_1B) and computes related statistics. Mean values and standard deviations are calculated for CPOL, XPOL, and DPOL within the selected height range. Variability is separated into vertical and temporal components. Errors of DPOL are derived using error propagation for the XPOL/CPOL ratio.

Parameters:

Name	Type	Description	Default
ds_anom	Dataset	ATL_NOM_1B dataset with cross- and co-polar signals.	required
selection_height_range	DistanceRangeLike	Height range for statistics.	required
is_rayleight_corrected		If True, the mean cross-polar profile is corrected by substracting the mean rayleigh profile scaled by a correction factor. Defaults to False.	required
rayleigh_correction_factor	float	The scaling factor used when is_rayleight_corrected is True. Defaults to 0.004.	0.004

Returns:

Type	Description
_ANOMDepolCalculationResults	Results as a data container with Mean and standard deviation of depolarization ratio. Mean, vertical, temporal, and combined spreads for co- and cross-polar signals. Propagated uncertainty of δ (total, vertical, temporal). Input dataset with depolarization ratio added.

Examples:

>>> import earthcarekit as eck
>>> ds = eck.ecload("ATL_NOM_1B", "01508B", download=True)
>>> ds = eck.filter_radius(ds, radius_km=100, site="dushanbe")
>>> results = eck.perform_anom_depol_statistics(
...     ds_anom=ds,
...     selection_height_range=(1000, 4000),
... )
>>> results.print()
>>> # results.stats.to_csv("./stats.csv")  # Optionally, save as CSV table
===========================================
Statistics: A-NOM depol ratio calculation
===========================================
Height range = 1000.0 to 4000.0 meters
mean(depol)  = 0.2270
std(depol)   = 0.0367
-------------------------------------------
error_t      = 0.0551
error_z      = 0.0542
error        = 0.1093
-------------------------------------------
mean(cpol)   = 4.6728e-07
std_t(cpol)  = 4.6008e-08
std_z(cpol)  = 5.0832e-08
std(cpol)    = 9.6840e-08
-------------------------------------------
mean(xpol)   = 1.0639e-07
std_t(xpol)  = 2.3535e-08
std_z(xpol)  = 2.2550e-08
std(xpol)    = 4.6085e-08
===========================================

>>> fig = results.plot(height_range=(0, 10e3))

Source code in earthcarekit/calval/_compute_anom_depol_statistics.py

def compute_anom_depol_statistics(
    ds_anom: xr.Dataset,
    selection_height_range: DistanceRangeLike,
    is_rayleigh_corrected: bool = False,
    rayleigh_correction_factor: float = 0.004,
    **kwargs,
) -> _ANOMDepolCalculationResults:
    """
    Calculate depolarization statistics and uncertainties within a height range.

    This function adds the depol. ratio (`DPOL`) calculated from co- (`CPOL`) and cross-polarized (`XPOL`)
    attenuated backscatter to the dataset (ATL_NOM_1B) and computes related statistics.
    Mean values and standard deviations are calculated for `CPOL`, `XPOL`, and `DPOL` within the selected
    height range. Variability is separated into vertical and temporal components. Errors of `DPOL` are derived
    using error propagation for the `XPOL`/`CPOL` ratio.

    Args:
        ds_anom: ATL_NOM_1B dataset with cross- and co-polar signals.
        selection_height_range: Height range for statistics.
        is_rayleight_corrected: If True, the mean cross-polar profile is corrected by substracting the
            mean rayleigh profile scaled by a correction factor. Defaults to False.
        rayleigh_correction_factor: The scaling factor used when `is_rayleight_corrected` is True.
            Defaults to 0.004.

    Returns:
        Results as a data container with

            - Mean and standard deviation of depolarization ratio.
            - Mean, vertical, temporal, and combined spreads for co- and cross-polar signals.
            - Propagated uncertainty of δ (total, vertical, temporal).
            - Input dataset with depolarization ratio added.

    Examples:
        >>> import earthcarekit as eck
        >>> ds = eck.ecload("ATL_NOM_1B", "01508B", download=True)
        >>> ds = eck.filter_radius(ds, radius_km=100, site="dushanbe")
        >>> results = eck.perform_anom_depol_statistics(
        ...     ds_anom=ds,
        ...     selection_height_range=(1000, 4000),
        ... )
        >>> results.print()
        >>> # results.stats.to_csv("./stats.csv")  # Optionally, save as CSV table
        ===========================================
        Statistics: A-NOM depol ratio calculation
        ===========================================
        Height range = 1000.0 to 4000.0 meters
        mean(depol)  = 0.2270
        std(depol)   = 0.0367
        -------------------------------------------
        error_t      = 0.0551
        error_z      = 0.0542
        error        = 0.1093
        -------------------------------------------
        mean(cpol)   = 4.6728e-07
        std_t(cpol)  = 4.6008e-08
        std_z(cpol)  = 5.0832e-08
        std(cpol)    = 9.6840e-08
        -------------------------------------------
        mean(xpol)   = 1.0639e-07
        std_t(xpol)  = 2.3535e-08
        std_z(xpol)  = 2.2550e-08
        std(xpol)    = 4.6085e-08
        ===========================================

        >>> fig = results.plot(height_range=(0, 10e3))

        <img src="https://raw.githubusercontent.com/TROPOS-RSD/earthcarekit-docs-assets/refs/heads/main/assets/images/api/compute_anom_depol_statistics.png" alt="missing image" height="330">
    """

    selection_height_range = validate_numeric_range(selection_height_range)

    ds_anom = add_depol_ratio(ds_anom, **kwargs)

    cpol_p: Profile = Profile.from_dataset(ds_anom, var="cpol_cleaned_for_ratio_calculation")
    xpol_p: Profile = Profile.from_dataset(ds_anom, var="xpol_cleaned_for_ratio_calculation")
    ray_p: Profile = Profile.from_dataset(ds_anom, var="ray_cleaned_for_ratio_calculation")
    cpol_mean_p: Profile = cpol_p.mean()
    xpol_mean_p: Profile = xpol_p.mean()
    ray_mean_p: Profile = ray_p.mean()

    if is_rayleigh_corrected:
        xpol_mean_p = xpol_mean_p - (ray_mean_p * rayleigh_correction_factor)

    dpol_mean_p: Profile = xpol_mean_p / cpol_mean_p
    cpol_std_p: Profile = cpol_p.std()
    xpol_std_p: Profile = xpol_p.std()

    cpol_stats = cpol_p.stats(selection_height_range)
    if is_rayleigh_corrected:
        xpol_p_corr = xpol_p - (ray_p * rayleigh_correction_factor)
        xpol_stats = xpol_p_corr.stats(selection_height_range)
    else:
        xpol_stats = xpol_p.stats(selection_height_range)
    dpol_stats = dpol_mean_p.stats(selection_height_range)

    dpol_mean: float = dpol_stats.mean
    dpol_std: float = dpol_stats.std
    cpol_mean: float = cpol_stats.mean
    xpol_mean: float = xpol_stats.mean
    cpol_std_t: float = cpol_std_p.stats(selection_height_range).std
    xpol_std_t: float = xpol_std_p.stats(selection_height_range).std
    cpol_std_z: float = cpol_stats.std
    xpol_std_z: float = xpol_stats.std
    cpol_std: float = cpol_std_t + cpol_std_z
    xpol_std: float = xpol_std_t + xpol_std_z

    def calc_error(xsd, csd):
        return np.sqrt((xsd / cpol_mean) ** 2 + (((xpol_mean / (cpol_mean**2)) * csd) ** 2))

    error = calc_error(xpol_std, cpol_std)
    error_z = calc_error(xpol_std_z, cpol_std_z)
    error_t = calc_error(xpol_std_t, cpol_std_t)

    return _ANOMDepolCalculationResults(
        ds=ds_anom.copy(),
        selection_height_range=selection_height_range,
        dpol_mean=dpol_mean,
        dpol_std=dpol_std,
        cpol_mean=cpol_mean,
        cpol_std_t=cpol_std_t,
        cpol_std_z=cpol_std_z,
        cpol_std=cpol_std,
        xpol_mean=xpol_mean,
        xpol_std_t=xpol_std_t,
        xpol_std_z=xpol_std_z,
        xpol_std=xpol_std,
        error=error,
        error_t=error_t,
        error_z=error_z,
    )