disdrodb.viz package

Submodules

disdrodb.viz.metadata module

disdrodb.viz.plots module

DISDRODB Plotting Tools.

disdrodb.viz.plots.compute_dense_lines(da: DataArray, coord: str, x_bins: list, y_bins: list, normalization='max')

Compute a 2D density-of-lines histogram from an xarray.DataArray.

Parameters:

• da (xarray.DataArray) – Input data array. One of its dimensions (named by coord) is taken as the horizontal coordinate. All other dimensions are collapsed into “series,” so that each combination of the remaining dimension values produces one 1D line along coord.

• coord (str) – The name of the coordinate/dimension of the DataArray to bin over. da.coords[coord] must be a 1D numeric array (monotonic is recommended).

• x_bins (array-like) – Bin edges to bin the coordinate/dimension with shape (nx+1,). Must be monotonically increasing. The number of x-bins will be nx = len(x_bins) - 1.

• y_bins (array-like) – Bin edges for the DataArray values with shape (ny+1,). Must be monotonically increasing. The number of y-bins will be ny = len(y_bins) - 1.

• normalization (bool, optional) – If ‘none’, returns the raw histogram. By default, the function normalize the histogram by its global maximum (‘max’). Log-normalization (‘log’) is also available.

Returns:

2D histogram of shape (ny, nx). Dimensions are ('y', 'x'), where:

• x: the bin-center coordinate of x_bins (length nx)

• y: the bin-center coordinate of y_bins (length ny)

Each element out.values[y_i, x_j] is the count (or normalized count) of how many “series-values” from da fell into the rectangular bin x_bins[j] ≤ x_value < x_bins[j+1] and y_bins[i] ≤ data_value < y_bins[i+1].

Return type:

xarray.DataArray

References

Moritz, D., Fisher, D. (2018). Visualizing a Million Time Series with the Density Line Chart https://doi.org/10.48550/arXiv.1808.06019

disdrodb.viz.plots.get_dataset_dsd_variable_name(ds, variables=None)

Return N(D) or n(D) variable name present in the xarray.Dataset.

disdrodb.viz.plots.get_dsd_variable(xr_obj, variable=None, diameter_dim='diameter_bin_center')

Return N(D), n(d) DataArray.

If N(D) or n(d) not available, derive n(d) from n(D,V).

Parameters:

• xr_obj (xr.Dataset or xr.DataArray) – Input xarray object.

• variable (str, optional) –

  Variable name to extract from the xarray object. If xr_obj is a DataArray, will return the DataArray and its name directly’. If xr_obj is a Dataset, if None, will search for candidate variables in order: [‘drop_number_concentration’, ‘drop_counts’, ‘raw_drop_counts’,

  ’raw_particle_counts’, ‘raw_drop_concentration’].

Returns:

(DataArray, variable_name)

Return type:

tuple

disdrodb.viz.plots.get_precipitation_legend_style(name)

Return (colors_dict, labels_dict) for supported categorical variables.

Supported:

• rain_type

• precipitation_type

• hydrometeor_type

disdrodb.viz.plots.max_blend_images(ds_rgb, dim)

Max blend a RGBA DataArray across a samples dimensions.

disdrodb.viz.plots.normalize_array(arr, method='max')

Normalize a NumPy array according to the chosen method.

Parameters:

• arr (numpy.ndarray) – Input array.

• method (str) –

  Normalization method. Options:

  • ’max’ : Divide by the maximum value.

  • ’minmax’: Scale to [0, 1] range.

  • ’zscore’: Standardize to mean 0, std 1.

  • ’log’ : Apply log10 transform (shifted if min <= 0).

  • ’none’ : No normalization (return original array).

Returns:

Normalized array.

Return type:

numpy.ndarray

disdrodb.viz.plots.plot_confusion_matrix(cm, labels, cmap='Blues', norm=None, xlabel='', ylabel='', title='', add_colorbar=False)

Plot confusion matrix.

disdrodb.viz.plots.plot_contour(contour, ax=None, **kwargs)

Plot contour [X,Y].

disdrodb.viz.plots.plot_dsd(xr_obj, variable=None, cmap=None, norm=None, yscale='linear', ax=None, velocity_method='theoretical_velocity')

Plot drop number concentration N(D) or drop counts n(D) timeseries.

Parameters:

• xr_obj (xr.Dataset or xr.DataArray) – Input xarray object containing drop data.

• variable (str, optional) – Variable name to plot. If None and xr_obj is a Dataset, will search for candidate variables in order: [‘drop_number_concentration’, ‘raw_particle_counts’, ‘drop_counts’]. If xr_obj is a DataArray, it will be plotted directly.

• cmap (matplotlib colormap, optional) – Colormap to use for the plot.

• norm (matplotlib normalization, optional) – Normalization for the colormap.

• yscale (str, optional) – Scale for y-axis (‘linear’ or ‘log’). Default is ‘linear’.

• ax (matplotlib axes, optional) – Axes to plot on.

• velocity_method (str, optional) – If the dataset has a velocity_method dimension, select the method to use for plotting. The default is “theoretical_velocity”.

Return type:

matplotlib axes or plot object

disdrodb.viz.plots.plot_dsd_quicklook(xr_obj, hours_per_slice=3, max_rows=6, aligned=True, verbose=False, variable=None, cbar_label=None, cmap=None, norm=None, d_dim='diameter_bin_center', d_lim=(0.3, 5.5), d_label='Diameter [mm]', cbar_as_legend=True, cbar_xpos=0.73, cbar_width=0.25, bottom_right_str=None, bottom_right_str_fontsize=8, secondary_var=None, secondary_ylim=None, secondary_yscale='linear', secondary_color='black', secondary_alpha=1, secondary_linewidth=1, secondary_linestyle='-', secondary_label=None, secondary_hlines=None, precipitation_type=None, precipitation_legend_fontsize=7, precipitation_legend_colors=None, precipitation_legend_labels=None, precipitation_legend_ncol=None, precipitation_legend_height=0.3, add_dm=True, add_sigma_m=True, sigma_label='$2\\sigma_m$', sigma_linewidth=0.5, dm_linewidth=0.5, dpi=300)

Display multi-rows quicklook of N(D).

disdrodb.viz.plots.plot_l1_dsd_quicklook(xr_obj, precipitation_type='precipitation_type', **kwargs)

Define L1 DSD default quicklook.

disdrodb.viz.plots.plot_l2_dsd_quicklook(xr_obj, precipitation_type='rain_type', secondary_var='R', secondary_label=None, secondary_ylim=None, secondary_hlines=None, secondary_yscale=None, secondary_linestyle=':', **kwargs)

Define L2 DSD default quicklook.

disdrodb.viz.plots.plot_mask_contour(mask, ax=None, **kwargs)

Plot mask contour.

disdrodb.viz.plots.plot_raw_and_filtered_spectra(ds, cmap=None, norm=None, extend='max', add_theoretical_average_velocity=True, add_measured_average_velocity=True, figsize=(6.9, 3.2), dpi=300)

Plot raw and filtered drop spectrum.

disdrodb.viz.plots.plot_spectrum(xr_obj, variable='raw_drop_number', ax=None, cmap=None, norm=None, extend='max', add_colorbar=True, cbar_kwargs=None, title=None, plot_hc_rain_mask_boundary=False, **plot_kwargs)

Plot the spectrum.

Parameters:

• xr_obj (xarray.Dataset or xarray.DataArray) – Input xarray object. If Dataset, the variable to plot must be specified. If DataArray, it must have both diameter and velocity dimensions.

• variable (str) – Name of the variable to plot if xr_obj is a Dataset.

• ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, uses current axes or creates a new one.

• cmap (matplotlib.colors.Colormap, optional) – Colormap to use. If None, uses ‘Spectral_r’ with ‘under’ set to ‘none’.

• norm (matplotlib.colors.Normalize, optional) – Normalization for colormap. If None, uses LogNorm with vmin=1.

• extend (str, optional) – Whether to draw arrows on the colorbar to indicate out-of-range values. Valid options are ‘neither’, ‘min’, ‘max’, ‘both’. Default is ‘max’.

• add_colorbar (bool, optional) – Whether to add a colorbar. Default is True.

• cbar_kwargs (dict, optional) – Additional keyword arguments for colorbar. If None, uses {‘label’: ‘Number of particles ‘}.

• title (str, optional) – Title of the plot. If not provided, defaults to the timestep or time range of the spectrum.

• **plot_kwargs (dict) – Additional keyword arguments passed to xarray’s plot.pcolormesh method.

Notes

If the input DataArray has a time dimension, it is summed over time before plotting unless FacetGrid options (e.g., col, row) are specified in plot_kwargs.

If FacetGrid options are used, the plot will create a grid of subplots for each time slice.

To create a FacetGrid plot, use:

ds.isel(time=slice(0, 9)).disdrodb.plot_spectrum(col=”time”, col_wrap=3)

disdrodb.viz.plots.plot_spectrum_evolution(ds, legend_variables=None, legend_ncol=1, xlim=None, ylim=None, plot_hc_rain_mask_boundary=False, **plot_kwargs)

Plot the evolution of disdrodb spectra over time.

Parameters:

• ds (xarray.Dataset) – Dataset containing ‘time’ dimension and ‘disdrodb’.

• legend_variables (list of str, optional) – Dataset variables to display in the legend.

• legend_ncol (int, optional) – Number of legend entries per row (horizontal layout).

• xlim (tuple, optional) – Axis limits passed to matplotlib.

• ylim (tuple, optional) – Axis limits passed to matplotlib.

• plot_kwargs (dict) – Additional keyword arguments passed to plot_spectrum().

disdrodb.viz.plots.to_rgba(obj, cmap='viridis', norm=None, scaling='none')

Map a xarray DataArray (or numpy array) to RGBA with optional alpha-scaling.

Module contents

DISDRODB Visualization Module.