disdrodb.psd package

disdrodb.psd package#

Submodules#

disdrodb.psd.fitting module#

Routines for PSD fitting.

disdrodb.psd.fitting.apply_exponential_gs(Nt, ND_obs, V, D, dD, Lambda, objectives, return_loss=False)[source][source]#

Estimate ExponentialPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameters (N0, Lambda) for the ExponentialPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nt (float) – Total number concentration.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are: - AE: Absolute Error - SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [N0, Lambda]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 1D array of total loss values. Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted. The best parameters correspond to the minimum total weighted loss.

disdrodb.psd.fitting.apply_gamma_gs(Nt, ND_obs, V, D, dD, mu, Lambda, objectives, return_loss=False)[source][source]#

Estimate GammaPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameters (mu, Lambda) for the GammaPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nt (float) – Total number concentration.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
mu (int, float or numpy.ndarray) – mu parameter values to search.
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [N0, Lambda, mu]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 2D array of total loss values reshaped to (len(mu), len(Lambda)). Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted The best parameters correspond to the minimum total weighted loss.

disdrodb.psd.fitting.apply_generalized_gamma_gs(Nt, ND_obs, V, D, dD, mu, c, Lambda, objectives, return_loss=False)[source][source]#

Estimate GeneralizedGammaPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameters (mu, c, Lambda) for the GeneralizedGammaPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nt (float) – Total number concentration.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
mu (int, float or numpy.ndarray) – mu parameter values to search.
c (int, float or numpy.ndarray) – c parameter values to search.
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [Lambda, mu, c]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 3D array of total loss values reshaped to (len(mu), len(Lambda), len(c)). Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted. The best parameters correspond to the minimum total weighted loss.

disdrodb.psd.fitting.apply_lognormal_gs(Nt, ND_obs, V, D, dD, mu, sigma, objectives, return_loss=False)[source][source]#

Estimate LognormalPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameters (mu, sigma) for the LognormalPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nt (float) – Total number concentration.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
mu (int, float or numpy.ndarray) – mu parameter values to search.
sigma (int, float or numpy.ndarray) – sigma parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [mu, sigma]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 2D array of total loss values reshaped to (len(mu), len(sigma)). Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted. The best parameters correspond to the minimum total weighted loss

disdrodb.psd.fitting.apply_normalized_gamma_gs(Nw, D50, ND_obs, V, D, dD, mu, objectives, return_loss=False)[source][source]#

Estimate NormalizedGammaPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameter (mu) for the NormalizedGammaPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nw (float) – Normalized intercept parameter.
D50 (float) – Median volume diameter parameter.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
mu (int, float or numpy.ndarray) – mu parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "H(x)" : Normalized drop number concentration [-]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)" or "H(x)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [Nw, mu, D50]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 1D array of total loss values. Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted. The best parameters correspond to the minimum total weighted loss

disdrodb.psd.fitting.apply_normalized_generalized_gamma_gs(Nc, Dc, ND_obs, V, D, dD, i, j, mu, c, objectives, return_loss=False)[source][source]#

Estimate NormalizedGeneralizedGammaPSD model parameters using Grid Search.

This function performs a grid search optimization to find the best parameters (mu, c) for the NormalizedGeneralizedGammaPSD model by minimizing a weighted cost function across one or more objectives.

Parameters:

Nc (float) – Normalized intercept parameter.
Dc (float) – Normalized characteristic diameter parameter.
ND_obs (numpy.ndarray) – Observed PSD data [#/mm/m3].
V (numpy.ndarray) – Fall velocity [m/s].
D (numpy.ndarray) – Diameter bins [mm].
dD (numpy.ndarray) – Diameter bin widths [mm].
i (int) – Moment order i of the NormalizedGeneralizedGammaPSD.
j (int) – Moment order j of the NormalizedGeneralizedGammaPSD.
mu (int, float or numpy.ndarray) – mu parameter values to search.
c (int, float or numpy.ndarray) – c parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "H(x)" : Normalized drop number concentration [-]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)" or "H(x)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters as [Nc, Dc, mu, c]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 2D array of total loss values reshaped to (len(mu), len(c)). Only returned if return_loss=True.

Notes

When multiple objectives are provided, losses are normalized and weighted. The best parameters correspond to the minimum total weighted loss.

disdrodb.psd.fitting.available_mom_methods(psd_model)[source][source]#: Implemented MOM methods for a given PSD model.

disdrodb.psd.fitting.available_optimization(psd_model)[source][source]#: Implemented fitting methods for a given PSD model.

disdrodb.psd.fitting.check_fixed_parameters(psd_model, fixed_parameters)[source][source]#: Check valid fixed_parameters argument.

disdrodb.psd.fitting.check_likelihood(likelihood)[source][source]#: Check valid likelihood argument.

disdrodb.psd.fitting.check_mom_methods(mom_methods, psd_model, allow_none=False)[source][source]#: Check valid mom_methods arguments.

disdrodb.psd.fitting.check_optimization(optimization)[source][source]#: Check valid optimization argument.

disdrodb.psd.fitting.check_optimization_settings(optimization_settings, optimization, psd_model)[source][source]#: Check valid optimization_settings.

disdrodb.psd.fitting.check_optimizer(optimizer)[source][source]#: Check valid optimizer argument.

disdrodb.psd.fitting.check_probability_method(probability_method)[source][source]#: Check valid probability_method argument.

disdrodb.psd.fitting.check_psd_model(psd_model, optimization)[source][source]#: Check valid psd_model argument.

disdrodb.psd.fitting.check_psd_parameters(psd_model, parameters)[source][source]#: Check valid psd_model parameters.

disdrodb.psd.fitting.check_search_space(search_space)[source][source]#: Check valid search_space dictionary.

disdrodb.psd.fitting.check_search_space_parameters(search_space, psd_model)[source][source]#: Check search_space parameters are PSD model parameters.

disdrodb.psd.fitting.check_truncated_likelihood(truncated_likelihood)[source][source]#: Check valid truncated_likelihood argument.

disdrodb.psd.fitting.compute_negative_log_likelihood(params, bin_edges, counts, cdf_func, pdf_func, param_constraints=None, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True)[source][source]#

General negative log-likelihood function for fitting distributions to binned data.

Parameters:

params (array-like) – Parameters of the distribution.
bin_edges (array-like) – Edges of the bins (length N+1).
counts (array-like) – obs counts in each bin (length N).
cdf_func (callable) – Cumulative distribution function of the distribution.
pdf_func (callable) – Probability density function of the distribution.
param_constraints (callable, optional) – Function that checks if parameters are valid.
probability_method (str, optional) – Method to compute expected probabilities, either ‘cdf’ or ‘pdf’. Default is ‘cdf’.
likelihood (str, optional) – Type of likelihood to compute, either ‘multinomial’ or ‘poisson’. Default is ‘multinomial’.
truncated_likelihood (bool, optional) – Whether to normalize the expected probabilities. Default is True.
nll (float) – Negative log-likelihood value.

Returns:

nll – The negative log-likelihood value.

Return type:

float

disdrodb.psd.fitting.define_gs_parameters(psd_model, fixed_parameters=None, search_space=None)[source][source]#

Define PSD model parameters for Grid Search optimization routines.

This function constructs a dictionary of parameter values ready for grid search, converting search space ranges into numpy arrays.

Parameters:

fixed_parameters (dict, optional) – Dictionary with parameter names as keys and scalar values as values. Example: {“mu”: 2.0}
search_space (dict, optional) – Dictionary defining search ranges for parameters. Each parameter can have: - ‘min’ : float, Minimum value - ‘max’ : float, Maximum value - ‘step’ : float, Step size for linspace interval Example: {“Lambda”: {“min”: 0, “max”: 10, “step”: 0.2}}

Returns:

Dictionary with PSD parameter names as keys and values as: - scalar (int or float) - numpy.ndarray for grid search Empty dict if both inputs are None or empty

Return type:

dict

disdrodb.psd.fitting.estimate_exponential_parameters(counts, Lambda, bin_edges, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, output_dictionary=True, optimizer='Nelder-Mead')[source][source]#

Estimate the parameters of an exponential distribution given histogram data.

Parameters:

counts (array-like) – The counts for each bin in the histogram.
Lambda (float) – The initial guess of the scale parameter. scale = 1 / lambda correspond to the scale parameter of the scipy.stats.expon distribution. A good default value is 1.
bin_edges (array-like) – The edges of the bins.
probability_method (str, optional) – The method to compute probabilities, either "cdf" or "pdf". The default value is "cdf".
likelihood (str, optional) – The likelihood function to use, either "multinomial" or "poisson". The default value is "multinomial".
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True.
output_dictionary (bool, optional) – Whether to return the output as a dictionary. If False, returns a numpy array. The default value is True
optimizer (str, optional) – The optimization method to use. Default is "Nelder-Mead".

Returns:

The estimated parameters of the exponential distribution. If output_dictionary is True, returns a dictionary with keys N0 and Lambda. If output_dictionary is False, returns a numpy array with [N0, Lambda].

Return type:

dict or numpy.ndarray

Notes

The exponential distribution is defined as:

N(D) = N0 * exp(-Lambda * D) = Nt * Lambda * exp(-Lambda * D) where Lambda = 1 / scale and N0 = Nt * Lambda.

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.expon.html

disdrodb.psd.fitting.estimate_gamma_parameters(counts, mu, Lambda, bin_edges, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, output_dictionary=True, optimizer='Nelder-Mead')[source][source]#

Estimate the parameters of a gamma distribution given histogram data.

Parameters:

counts (array-like) – The counts for each bin in the histogram.
mu (float) – The initial guess of the shape parameter. a = mu + 1 correspond to the shape parameter of the scipy.stats.gamma distribution. A good default value is 0.
lambda (float) – The initial guess of the scale parameter. scale = 1 / lambda correspond to the scale parameter of the scipy.stats.gamma distribution. A good default value is 1.
bin_edges (array-like) – The edges of the bins.
probability_method (str, optional) – The method to compute probabilities, either "cdf" or "pdf". The default value is "cdf".
likelihood (str, optional) – The likelihood function to use, either "multinomial" or "poisson". The default value is "multinomial".
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True.
output_dictionary (bool, optional) – Whether to return the output as a dictionary. If False, returns a numpy array. The default value is True
optimizer (str, optional) – The optimization method to use. Default is "Nelder-Mead".

Returns:

The estimated parameters of the gamma distribution. If output_dictionary is True, returns a dictionary with keys N0, mu and Lambda. If output_dictionary is False, returns a numpy array with [N0, mu, Lambda].

Return type:

dict or numpy.ndarray

Notes

The gamma distribution is defined as:

\[\]

N(D) = N_0 , D^{mu} , exp(-Lambda D)

where:

\(D\) is the particle diameter,
\(\Lambda = 1 / \text{scale}\) is the slope parameter,
\(\mu = a - 1\) is the shape parameter, with \(a\) the gamma distribution shape parameter.

The intercept parameter \(N_0\) is defined as:

\[\]

N_0 = N_t , frac{Lambda^{mu + 1}}{Gamma(mu + 1)}

where \(N_t\) is the total number concentration and \(\Gamma(\cdot)\) denotes the gamma function.

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.gamma.html

disdrodb.psd.fitting.estimate_lognormal_parameters(counts, mu, sigma, bin_edges, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, output_dictionary=True, optimizer='Nelder-Mead')[source][source]#

Estimate the parameters of a lognormal distribution given histogram data.

Parameters:

counts (array-like) – The counts for each bin in the histogram.
mu (float) – The initial guess of the mean of the log of the distribution. A good default value is 0.
sigma (float) – The initial guess of the standard deviation of the log distribution. A good default value is 1.
bin_edges (array-like) – The edges of the bins.
probability_method (str, optional) – The method to compute probabilities, either "cdf" or "pdf". The default value is "cdf".
likelihood (str, optional) – The likelihood function to use, either "multinomial" or "poisson". The default value is "multinomial".
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True.
output_dictionary (bool, optional) – Whether to return the output as a dictionary. If False, returns a numpy array. The default value is True
optimizer (str, optional) – The optimization method to use. Default is "Nelder-Mead".

Returns:

The estimated parameters of the lognormal distribution. If output_dictionary is True, returns a dictionary with keys Nt, mu, and sigma. If output_dictionary is False,returns a numpy array with values [Nt, mu, sigma].

Return type:

dict or numpy.ndarray

Notes

The lognormal distribution is defined as: N(D) = Nt / (sqrt(2 * pi) * sigma * D) * exp(-(ln(D) - mu)**2 / (2 * sigma**2)) where Nt is the total number of counts, mu is the mean of the log of the distribution, and sigma is the standard deviation of the log of the distribution.

References

https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.lognorm.html#scipy.stats.lognorm

disdrodb.psd.fitting.estimate_model_parameters(ds, psd_model, optimization, optimization_settings=None)[source][source]#

Estimate particle size distribution model parameters.

This is the main interface function for fitting PSD models to observed data. It supports three optimization methods: Maximum Likelihood (ML), Method of Moments (MOM), and Grid Search (GS).

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
Additional variables required for specific optimization methods:
- For ML: diameter_bin_lower, diameter_bin_upper
- For GS with target=’R’: fall_velocity (auto-computed if missing)
- For MOM: Moment variables M0, M1, …, M6 (depending on method)
psd_model (str) –
Name of the PSD model to fit. Valid options:
- "GammaPSD" : Gamma distribution
- "NormalizedGammaPSD" : Normalized gamma distribution
- "LognormalPSD" : Lognormal distribution
- "ExponentialPSD" : Exponential distribution
Use available_optimization(psd_model) to check which optimization methods are available for a given model.
optimization (str) –
Optimization method to use. Valid options:
- "ML" : Maximum Likelihood estimation
- "MOM" : Method of Moments
- "GS" : Grid Search
optimization_settings –
Dictionary of keyword arguments specific to the chosen optimization method.

For optimization="ML":
- init_method : str or list, Method(s) of moments for parameter initialization
- probability_method : str, Method to compute probabilities (default: ‘cdf’)
- likelihood : str, Likelihood function (‘multinomial’ or ‘poisson’, default: ‘multinomial’)
- truncated_likelihood : bool, Use truncated likelihood (default: True)
- optimizer : str, Optimization algorithm (default: ‘Nelder-Mead’)
For optimization="GS":
- fixed_parametersdict, optional
 Allows to specify PSD model parameters to fixed value(s). For example for psd_model=GammaPSD one can use fixed_parameters={“mu”: 3} For psd_model=NormalizedGeneralizedGammaPSD, it’s mandatory to specify i and j moment order with: fixed_parameters={“i”: 3, “j”: 4}
- objectives: dict, optional
 List of optimization objectives. If None (default), use DEFAULT_OBJECTIVES. Each objective dict must contain:
 "target"str
 Target quantity to optimize. Valid options: - "N(D)" : Drop number concentration [m⁻³ mm⁻¹] - "H(x)" : Normalized drop number concentration [-]. Only for Normalized PSD models. - "R" : Rain rate [mm h⁻¹] - "Z" : Radar reflectivity [mm⁶ m⁻³] - "LWC" : Liquid water content [g m⁻³] - "M" : Moment of order p
 
 "transformation"str
 Transformation applied before computing the error. Valid options: - "identity" : No transformation - "log" : Logarithmic transformation - "sqrt" : Square root transformation
 
 "censoring"str
 Censoring applied to observed PSD. Valid options: - "none" : No censoring applied - "left" : Left-censored (remove leading zero bins) - "right" : Right-censored (remove trailing zero bins) - "both" : Both sides censored
 
 "loss"str
 Error metric. For "N(D)" and "H(x)" valid options are "SSE", "SAE", "MAE", "MSE", "RMSE", "relMAE" "KLDiv", "JSD", "WD", "KS". For "R", "Z", "LWC", and "M" valid options are "AE", "SE".
 
 "loss_weight"float, optional
 Weight for this objective in the combined loss (default: 1.0 for single objective). When multiple objectives are provided, weights are normalized to sum to 1.0.

Returns:

ds_params – Dataset containing the estimated PSD model parameters with attributes. Variables depend on the selected psd_model:

GammaPSD : N0, mu, Lambda
NormalizedGammaPSD : Nw, mu, Dm
LognormalPSD : Nt, mu, sigma
ExponentialPSD : N0, Lambda

Each parameter variable includes attributes with parameter name, units, and optimization metadata.

Dataset attributes include:

disdrodb_psd_model : The fitted PSD model name
disdrodb_psd_optimization : The optimization method used
disdrodb_psd_optimization_settings : String representation of kwargs

Return type:

xarray.Dataset

disdrodb.psd.fitting.fit_ngg_on_normalized_space(x, ND_norm, i, j, mu=None, c=None, transformation='log', loss='SSE', return_loss=False)[source][source]#

Fit a NormalizedGeneralizedGammaPSD model in normalized space.

This function performs a grid search optimization to find the best parameters (mu, c) for the NormalizedGeneralizedGammaPSD model by minimizing a cost function.

Parameters:

x (numpy.ndarray) – Normalized diameter parameter (D/Dc) [-].
ND_norm (numpy.ndarray) – Observed normalized PSD data (N(D)/Nc [-].
i (int) – Moment order i of the NormalizedGeneralizedGammaPSD.
j (int) – Moment order j of the NormalizedGeneralizedGammaPSD.
mu (int, float or numpy.ndarray) – mu parameter values to search.
c (int, float or numpy.ndarray) – c parameter values to search.
transformation (str, optional) –
Transformation applied to the target quantity before computing the loss. The default is "log". Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
loss (int, optional) –
Loss function. The default is SSE. Valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

parameters (numpy.ndarray) – Best parameters [mu, c]. An array of NaN values is returned if no valid solution is found.
total_loss (numpy.ndarray, optional) – 2D array of total loss values reshaped to (len(mu), len(c)). Only returned if return_loss=True.

disdrodb.psd.fitting.get_adjusted_nt(cdf, params, Nt, bin_edges)[source][source]#: Adjust Nt for the proportion of missing drops. See Johnson’s et al., 2013 Eqs. 3 and 4.

disdrodb.psd.fitting.get_expected_probabilities(params, cdf_func, pdf_func, bin_edges, probability_method, normalized=False)[source][source]#

Compute the expected probabilities for each bin given the distribution parameters.

Parameters:

params (array-like) – Parameters for the CDF or PDF function.
cdf_func (callable) – Cumulative distribution function (CDF) that takes bin edges and parameters as inputs.
pdf_func (callable) – Probability density function (PDF) that takes a value and parameters as inputs.
bin_edges (array-like) – Edges of the bins for which to compute the probabilities.
probability_method (str) – Method to compute the probabilities. Valid values are ‘cdf’ and ‘pdf’. If ‘cdf’, use the CDF to compute probabilities. If ‘pdf’, integrate the PDF over each bin range.
normalized (bool, optional) – If True, normalize the probabilities to sum to 1. Default is False.

Returns:

expected_probabilities – Array of expected probabilities for each bin.

Return type:

numpy.ndarray

Notes

If the ‘cdf’ method is used, the probabilities are computed as the difference in CDF values at the bin edges.
If the ‘pdf’ method is used, the probabilities are computed by integrating the PDF over each bin range.
Any zero or negative probabilities are replaced with a very small positive number (1e-10) to ensure optimization.
If normalized is True, the probabilities are normalized to sum to 1.

disdrodb.psd.fitting.get_exponential_parameters(ds, init_method=None, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, optimizer='Nelder-Mead')[source][source]#

Estimate the parameters of an exponential particle size distribution (PSD) from the given dataset.

Fitting this model is equivalent to fitting a GammaPSD model fixing mu to 0.

Parameters:

ds (xarray.Dataset) – Input dataset containing drop number concentration data and diameter information. It must include the following variables: - drop_number_concentration: The number concentration of drops. - diameter_bin_width”: The width of each diameter bin. - diameter_bin_lower: The lower bounds of the diameter bins. - diameter_bin_upper: The upper bounds of the diameter bins. - diameter_bin_center: The center values of the diameter bins.
probability_method (str, optional) – Method to compute probabilities. The default value is cdf.
likelihood (str, optional) – Likelihood function to use for fitting. The default value is multinomial.
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True.
optimizer (str, optional) – Optimization method to use. The default value is Nelder-Mead.

Returns:

Dataset containing the estimated expontial distribution parameters: - N0: Intercept parameter. - Lambda: Scale parameter. The resulting dataset will have an attribute disdrodb_psd_model set to ExponentialPSD.

Return type:

xarray.Dataset

Notes

The function uses xr.apply_ufunc to fit the exponential distribution parameters in parallel, leveraging Dask for parallel computation.

disdrodb.psd.fitting.get_exponential_parameters_M34(moment_3, moment_4)[source][source]#

Compute exponential distribution parameters following Testud 2001.

References

Testud, J., S. Oury, R. A. Black, P. Amayenc, and X. Dou, 2001: The Concept of “Normalized” Distribution to Describe Raindrop Spectra: A Tool for Cloud Physics and Cloud Remote Sensing. J. Appl. Meteor. Climatol., 40, 1118-1140, https://doi.org/10.1175/1520-0450(2001)040<1118:TCONDT>2.0.CO;2

disdrodb.psd.fitting.get_exponential_parameters_Zhang2008(moment_l, moment_m, l, m)[source][source]#

Calculate Exponential DSD parameters using the method of moments (MOM).

The choice of moments is given in the parameters.

Parameters:

moment_l (float) – First moment to use.
moment_l – Second moment to use.
l (float) – Moment order.
m (float) – Moment order,

References

[1] Zhang, et. al., 2008, Diagnosing the Intercept Parameter for Exponential Raindrop Size: Distribution Based on Video Disdrometer Observations: Model Development. J. Appl. Meteor. Climatol., https://doi.org/10.1175/2008JAMC1876.1

disdrodb.psd.fitting.get_exponential_parameters_gs(ds, Lambda=None, objectives=None, return_loss=False)[source][source]#

Estimate Exponential PSD parameters using Grid Search optimization.

The parameter N_t is computed empirically from the observed DSD, while the shape parameter Lambda is estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Exponential distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_gamma_parameters(ds, init_method=None, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, optimizer='Nelder-Mead')[source][source]#

Estimate gamma distribution parameters for drop size distribution (DSD) data.

Parameters:

ds (xarray.Dataset) –
Input dataset containing drop size distribution data. It must include the following variables:
- drop_number_concentration: The number concentration of drops.
- diameter_bin_width”: The width of each diameter bin.
- diameter_bin_lower: The lower bounds of the diameter bins.
- diameter_bin_upper: The upper bounds of the diameter bins.
- diameter_bin_center: The center values of the diameter bins.
- The moments M0…M6 variables required to compute the initial parameters with the specified mom_method.
init_method (str or list) – The method(s) of moments used to initialize the gamma parameters. If None (or ‘None’), the scale parameter is set to 1 and mu to 0 (a=1).
probability_method (str, optional) – Method to compute probabilities. The default value is cdf.
likelihood (str, optional) – Likelihood function to use for fitting. The default value is multinomial.
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True. See Johnson et al., 2011 and 2011 for more information.
optimizer (str, optional) – Optimization method to use. The default value is Nelder-Mead.

Returns:

Dataset containing the estimated gamma distribution parameters:

N0: Intercept parameter.
mu: Shape parameter.
Lambda: Scale parameter.

The dataset will also have an attribute disdrodb_psd_model set to GammaPSD.

Return type:

xarray.Dataset

Notes

The function uses xr.apply_ufunc to fit the lognormal distribution parameters in parallel, leveraging Dask for parallel computation.

References

Johnson, R. W., D. V. Kliche, and P. L. Smith, 2011: Comparison of Estimators for Parameters of Gamma Distributions with Left-Truncated Samples. J. Appl. Meteor. Climatol., 50, 296-310, https://doi.org/10.1175/2010JAMC2478.1

Johnson, R.W., Kliche, D., & Smith, P.L. (2010). Maximum likelihood estimation of gamma parameters for coarsely binned and truncated raindrop size data. Quarterly Journal of the Royal Meteorological Society, 140. DOI:10.1002/qj.2209

disdrodb.psd.fitting.get_gamma_parameters_M234(M2, M3, M4)[source][source]#

Compute gamma distribution parameters following Cao et al., 2009.

References

Cao, Q., and G. Zhang, 2009: Errors in Estimating Raindrop Size Distribution Parameters Employing Disdrometer and Simulated Raindrop Spectra. J. Appl. Meteor. Climatol., 48, 406-425, https://doi.org/10.1175/2008JAMC2026.1.

disdrodb.psd.fitting.get_gamma_parameters_M246(M2, M4, M6)[source][source]#

Compute gamma distribution parameters following Ulbrich 1998.

References

Ulbrich, C. W., and D. Atlas, 1998: Rainfall Microphysics and Radar Properties: Analysis Methods for Drop Size Spectra. J. Appl. Meteor. Climatol., 37, 912-923, https://doi.org/10.1175/1520-0450(1998)037<0912:RMARPA>2.0.CO;2

Thurai, M., Williams, C.R., Bringi, V.N., 2014: Examining the correlations between drop size distribution parameters using data from two side-by-side 2D-video disdrometers. Atmospheric Research, 144, 95-110, https://doi.org/10.1016/j.atmosres.2014.01.002.

disdrodb.psd.fitting.get_gamma_parameters_M346(M3, M4, M6)[source][source]#

Compute gamma distribution parameters following Kozu 1991.

References

Kozu, T., and K. Nakamura, 1991: Rainfall Parameter Estimation from Dual-Radar Measurements Combining Reflectivity Profile and Path-integrated Attenuation. J. Atmos. Oceanic Technol., 8, 259-270, https://doi.org/10.1175/1520-0426(1991)008<0259:RPEFDR>2.0.CO;2

Tokay, A., and D. A. Short, 1996: Evidence from Tropical Raindrop Spectra of the Origin of Rain from Stratiform versus Convective Clouds. J. Appl. Meteor. Climatol., 35, 355-371, https://doi.org/10.1175/1520-0450(1996)035<0355:EFTRSO>2.0.CO;2

disdrodb.psd.fitting.get_gamma_parameters_M456(M4, M5, M6)[source][source]#

Compute gamma distribution parameters following Cao et al., 2009.

References

disdrodb.psd.fitting.get_gamma_parameters_gs(ds, mu=None, Lambda=None, objectives=None, return_loss=False)[source][source]#

Estimate Gamma PSD parameters using Grid Search optimization.

The parameter N_t is computed empirically from the observed DSD, while the shape parameters mu and Lambda are estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
mu (int, float or numpy.ndarray) – mu parameter values to search.
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Gamma distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_generalized_gamma_parameters_gs(ds, mu=None, c=None, Lambda=None, objectives=None, return_loss=False)[source][source]#

Estimate Generalized Gamma PSD parameters using Grid Search optimization.

The parameter N_t is computed empirically from the observed DSD, while the shape parameters mu, c, and Lambda are estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
mu (int, float or numpy.ndarray) – mu parameter values to search.
c (int, float or numpy.ndarray) – c parameter values to search.
Lambda (int, float or numpy.ndarray) – Lambda parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Generalized Gamma distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_gs_parameters(ds, psd_model, fixed_parameters=None, objectives=None, search_space=None, return_loss=False)[source][source]#

Estimate PSD model parameters using Grid Search optimization with multiple objectives.

This function estimates particle size distribution (PSD) model parameters by minimizing a weighted combination of errors across multiple objectives through grid search over the parameter space.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if any objective targets ‘R’)
psd_model (str) –
Name of the PSD model to fit. Valid options are:
- "GammaPSD" : Gamma distribution
- "NormalizedGammaPSD" : Normalized gamma distribution
- "LognormalPSD" : Lognormal distribution
- "ExponentialPSD" : Exponential distribution
- "NormalizedGeneralizedGammaPSD" : Normalized generalized gamma distribution
objectives (list of dict) –
List of optimization objectives. Each objective dict must contain:
- "target"str
 Target quantity to optimize. Valid options:
 - "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
 - "H(x)" : Normalized drop number concentration [-]. Only for Normalized PSD models.
 - "R" : Rain rate [mm h⁻¹]
 - "Z" : Radar reflectivity [mm⁶ m⁻³]
 - "LWC" : Liquid water content [g m⁻³]
 - "M" : Moment of order p
- "transformation"str
 Transformation applied before computing the error. Valid options:
 - "identity" : No transformation
 - "log" : Logarithmic transformation
 - "sqrt" : Square root transformation
- "censoring"str
 Censoring applied to observed PSD. Valid options:
 - "none" : No censoring applied
 - "left" : Left-censored (remove leading zero bins)
 - "right" : Right-censored (remove trailing zero bins)
 - "both" : Both sides censored
- "loss"str
 Error metric. For "N(D)" and "H(x)" valid options are "SSE", "SAE", "MAE", "MSE", "RMSE", "relMAE" "KLDiv", "JSD", "WD", "KS".
 
 For "R", "Z", "LWC", and "M" valid options are "AE", "SE".
- "loss_weight"float, optional
 Weight for this objective in the combined loss (default: 1.0 for single objective). When multiple objectives are provided, weights are normalized to sum to 1.0.
fixed_parameters (dict, optional) – Initial parameter values for the PSD model. Keys are parameter names, values are scalars. Example: {“mu”: 2.0, “Lambda”: 1.5}
search_space (dict, optional) –
Search space configuration for parameters. Each parameter can define:
- "min" : float, Minimum value
- "max" : float, Maximum value
- "step" : float, Step size for parameter grid
Example: {“mu”: {“min”: 0, “max”: 10, “step”: 0.2}}

Returns:

ds_params – Dataset containing the estimated PSD model parameters. Variables depend on the selected psd_model:

GammaPSD : N0, mu, Lambda
NormalizedGammaPSD : Nw, mu, D50
LognormalPSD : Nt, mu, sigma
ExponentialPSD : N0, Lambda
NormalizedGeneralizedGammaPSD : Nc, Dc, mu, c

Each parameter variable includes attributes with name, units, and description. Dataset attributes contain optimization metadata.

Return type:

xarray.Dataset

Raises:

ValueError – If objectives structure is invalid or fixed_parameters/search_space bounds are invalid
NotImplementedError – If psd_model is not supported for GS optimization

Notes

Grid search optimization explores a predefined parameter space to find the combination that minimizes the specified loss across all objectives. When multiple objectives are provided, losses are combined using normalized weights.

If drop_number_concentration values are all zeros or contain non-finite values, the output PSD parameters are set to NaN.

Examples

Single objective optimization:

>>> objectives = [{
...     "target": "N(D)",
...     "transformation": "log",
...     "censoring": "none",
...     "loss": "MAE"
... }]
>>> ds_params = get_gs_parameters(ds, psd_model="GammaPSD", objectives=objectives)

Multi-objective optimization:

>>> objectives = [
...     {
...         "target": "N(D)",
...         "transformation": "identity",
...         "censoring": "left",
...         "loss": "MAE",
...         "loss_weight": 0.6
...     },
...     {
...         "target": "LWC",
...         "transformation": "log",
...         "censoring": "both",
...         "loss": "AE",
...         "loss_weight": 0.4
...     }
... ]
>>> search_space = {
...     "mu": {"min": 0, "max": 10, "step": 0.2},
...     "Lambda": {"min": 0.1, "max": 5, "step": 0.1}
... }
>>> ds_params = get_gs_parameters(
...     ds, psd_model="GammaPSD", search_space=search_space
... )

disdrodb.psd.fitting.get_lognormal_parameters(ds, init_method=None, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, optimizer='Nelder-Mead')[source][source]#

Estimate lognormal distribution parameters for drop size distribution (DSD) data.

Parameters:

ds (xarray.Dataset) –
Input dataset containing drop size distribution data. It must include the following variables:
- drop_number_concentration: The number concentration of drops.
- diameter_bin_width: The width of each diameter bin.
- diameter_bin_lower: The lower bounds of the diameter bins.
- diameter_bin_upper: The upper bounds of the diameter bins.
- diameter_bin_center: The center values of the diameter bins.
probability_method (str, optional) – Method to compute probabilities. The default value is cdf.
likelihood (str, optional) – Likelihood function to use for fitting. The default value is multinomial.
truncated_likelihood (bool, optional) – Whether to use truncated likelihood. The default value is True.
optimizer (str, optional) – Optimization method to use. The default value is Nelder-Mead.

Returns:

Dataset containing the estimated lognormal distribution parameters:

Nt: Total number concentration.
mu: Mean of the lognormal distribution.
sigma: Standard deviation of the lognormal distribution.

The resulting dataset will have an attribute disdrodb_psd_model set to LognormalPSD.

Return type:

xarray.Dataset

Notes

The function uses xr.apply_ufunc to fit the lognormal distribution parameters in parallel, leveraging Dask for parallel computation.

disdrodb.psd.fitting.get_lognormal_parameters_M346(M3, M4, M6)[source][source]#

Compute lognormal distribution parameters following Kozu1991.

References

disdrodb.psd.fitting.get_lognormal_parameters_gs(ds, mu=None, sigma=None, objectives=None, return_loss=False)[source][source]#

Estimate Lognormal PSD parameters using Grid Search optimization.

The parameter N_t is computed empirically from the observed DSD, while the shape parameters mu and sigma are estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
mu (int, float or numpy.ndarray) – mu parameter values to search.
sigma (int, float or numpy.ndarray) – sigma parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Lognormal distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_ml_parameters(ds, psd_model, init_method=None, probability_method='cdf', likelihood='multinomial', truncated_likelihood=True, optimizer='Nelder-Mead')[source][source]#

Estimate model parameters for a given distribution using Maximum Likelihood.

Parameters:

ds (xarray.Dataset) –
Input dataset containing drop number concentration data and diameter information. It must include the following variables:
- drop_number_concentration: The number concentration of drops.
- diameter_bin_width”: The width of each diameter bin.
- diameter_bin_lower: The lower bounds of the diameter bins.
- diameter_bin_upper: The upper bounds of the diameter bins.
- diameter_bin_center: The center values of the diameter bins.
psd_model (str) – The PSD model to fit. See available_psd_models().
init_method (str or list) – The method(s) of moments used to initialize the PSD model parameters. Multiple methods can be specified. See available_mom_methods(psd_model).
probability_method (str, optional) – Method to compute probabilities. The default value is cdf.
likelihood (str, optional) – Likelihood function to use for fitting. The default value is multinomial.
truncated_likelihood (bool, optional) – Whether to use Truncated Maximum Likelihood (TML). The default value is True.
optimizer (str, optional) – Optimization method to use. The default value is Nelder-Mead.

Returns:

The dataset containing the estimated parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_mom_parameters(ds: Dataset, psd_model: str, mom_methods=None) → Dataset[source][source]#

Compute PSD model parameters using various method-of-moments (MOM) approaches.

The method is specified by the mom_methods abbreviations, e.g. ‘M012’, ‘M234’, ‘M246’.

Parameters:

ds (xarray.Dataset) – An xarray Dataset with the required moments M0…M6 as data variables.
mom_methods (str or list (optional)) – See valid values with disdrodb.psd.available_mom_methods(psd_model) If None (the default), compute model parameters with all available MOM methods.

Returns:

A Dataset containing mu, Lambda, and N0 variables. If multiple mom_methods are specified, the dataset has the dimension mom_method.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_normalized_gamma_parameters_gs(ds, mu=None, objectives=None, return_loss=False)[source][source]#

Estimate Normalized Gamma PSD parameters using Grid Search optimization.

The parameters N_w and D50 are computed empirically from the observed DSD moments, while the shape parameter mu is estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
mu (int, float or numpy.ndarray) – mu parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "H(x)" : Normalized drop number concentration [-]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)" or "H(x)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Normalized Gamma distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_normalized_generalized_gamma_parameters_gs(ds, i, j, mu=None, c=None, objectives=None, return_loss=False)[source][source]#

Estimate Normalized Generalized Gamma PSD parameters using Grid Search optimization.

The parameters N_c and Dc are computed empirically from the observed DSD moments, while the shape parameters mu and c are estimated through grid search by minimizing the error between observed and modeled quantities.

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
- fall_velocity : Drop fall velocity [m s⁻¹] (required if target=’R’)
i (int) – Moment order i of the NormalizedGeneralizedGammaPSD.
j (int) – Moment order j of the NormalizedGeneralizedGammaPSD.
mu (int, float or numpy.ndarray) – mu parameter values to search.
c (int, float or numpy.ndarray) – c parameter values to search.
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "H(x)" : Normalized drop number concentration [-]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)" or "H(x)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
return_loss (bool, optional) – If True, return both the loss surface and parameters. Default is False.

Returns:

ds_params – Dataset containing the estimated Normalized Generalized Gamma distribution parameters.

Return type:

xarray.Dataset

disdrodb.psd.fitting.get_psd_model_parameter_names(psd_model)[source][source]#: Get psd_model parameter names.

disdrodb.psd.fitting.sanitize_drop_number_concentration(drop_number_concentration)[source][source]#

Sanitize drop number concentration array.

If N(D) is all zero or contain not finite values, set everything to np.nan

disdrodb.psd.gof_metrics module#

Define Goodness-Of-Fit metrics for xarray objects.

disdrodb.psd.gof_metrics.compute_gof_stats(obs, pred, dim='diameter_bin_center')[source][source]#

Compute various goodness-of-fit (GoF) statistics between observed and predicted values.

Computes a comprehensive set of GOF metrics including Pearson correlation, error statistics, and distribution distance metrics (KL, JS, Wasserstein, KS).

Parameters:

obs (xarray.DataArray) – Observations DataArray with at least dimension dim. Should contain ‘diameter_bin_center’ and ‘diameter_bin_width’ coordinates.
pred (xarray.DataArray) – Predictions DataArray with at least dimension dim.
dim (str, optional) – DataArray dimension over which to compute GOF statistics. Default is DIAMETER_DIMENSION.

Returns:

ds – Dataset containing the following computed GoF statistics:

R2: Coefficient of determination (squared Pearson correlation)
MAE: Mean Absolute Error
MaxAE: Maximum Absolute Error
RelMaxAE: Relative Maximum Absolute Error
PeakDiff: Difference at distribution peak (N(D) max)
RelPeakDiff: Relative difference at peak
DmodeDiff: Difference in mode diameters
NtDiff: Difference in total number concentration
KLDiv: Kullback-Leibler divergence
JSD: Jensen-Shannon distance
WD: Wasserstein-1 distance
KS: Kolmogorov-Smirnov statistic

Return type:

xarray.Dataset

disdrodb.psd.gof_metrics.compute_jensen_shannon_distance(pk, qk, dim, eps=1e-12)[source][source]#

Compute Jensen-Shannon distance.

Symmetric and finite version of KL divergence. The Jensen-Shannon distance is the square root of the Jensen-Shannon divergence. Values are defined between 0 and np.sqrt(ln(2)) = 0.83256

Parameters:

pk (xarray.DataArray) – Observed / true probability distribution
qk (xarray.DataArray) – Predicted / model probability distribution
dim (str) – Name of the bin dimension
eps (float, optional) – Small value for numerical stability. Default is 1e-12.

Returns:

Jensen-Shannon distance

Return type:

xarray.DataArray

disdrodb.psd.gof_metrics.compute_kl_divergence(pk, qk, dim, eps=1e-12)[source][source]#

Compute Kullback-Leibler (KL) divergence.

Compares two probability distributions. When KL < 0.1 the two distributions are similar. When KL < 0.01 the two distributions are nearly indistinguishable.

Note that when qk is 0 but pk > 0 at some bin, KL divergence explodes.

Parameters:

pk (xarray.DataArray) – Observed / true / empirical probability distribution
qk (xarray.DataArray) – Predicted / model / approximating probability distribution
dim (str) – Name of the bin dimension.
eps (float, optional) – Small value for numerical stability. Default is 1e-12.

Returns:

Kullback-Leibler (KL) divergence.

Return type:

xarray.DataArray

disdrodb.psd.gof_metrics.compute_kolmogorov_smirnov_distance(pk, qk, dim)[source][source]#

Compute Kolmogorov-Smirnov (KS) distance.

The Kolmogorov-Smirnov (KS) distance is bounded between 0 and 1, where 0 indicates that the two distributions are identical. The associated KS test p-value ranges from 0 to 1, with a value of 1 indicating no evidence against the null hypothesis that the distributions are identical. When the p value is smaller than the significance level (e.g. < 0.05) the model is rejected.

If model parameters are estimated from the same data to which the model is compared, the standard KS p-values are invalid. The solution is to use a parametric bootstrap: 1. Fit model to your data 2. Simulate many datasets from that fitted gamma 3. Refit gamma for each simulated dataset 4. Compute KS statistic each time 5. Compare your observed KS statistic to the bootstrap distribution

Parameters:

pk (xarray.DataArray) – Observed / true probability distribution
qk (xarray.DataArray) – Predicted / model probability distribution
dim (str) – Name of the bin dimension

Returns:

ks_statistic (xarray.DataArray) – Kolmogorov-Smirnov statistic (maximum CDF difference) If 0, the two distributions are identical.
ks_p_value (xarray.DataArray) – Kolmogorov-Smirnov Test p-value (asymptotic approximation) A p-value of 0 means “strong evidence against equality.” A p-value of 1 means “no evidence against equality.” Identical distributions show a pvalue of 1. Similar distributions show a pvalue close to 1.

disdrodb.psd.gof_metrics.compute_wasserstein_distance(pk, qk, D, dD, dim, integration='bin')[source][source]#

Compute Wasserstein-1 distance (Earth Mover’s Distance) between two distributions.

Parameters:

pk (xarray.DataArray) – Observed / true probability distribution
qk (xarray.DataArray) – Predicted / model probability distribution
D (xarray.DataArray) – Bin centers
dD (xarray.DataArray) – Bin widths
dim (str) – Name of the bin dimension
integration (str, optional) –
Integration scheme used to compute the Wasserstein integral. Supported options are "bin" and "left_riemann".

"bin" compute Histogram-based Wasserstein distance. Distributions are interpreted as piecewise-constant densities over bins of width dD. The distance is computed by integrating the difference between cumulative distribution functions over each bin. This is the default.

"left_riemann" computes Discrete-support Wasserstein distance. Probability mass is assumed to be concentrated at bin centers D, and the integral is approximated using the spacing between support points, consistent with scipy.stats.wasserstein_distance().

Returns:

Wasserstein-1 distance

Return type:

xarray.DataArray

disdrodb.psd.grid_search module#

Routines for grid search optimization.

disdrodb.psd.grid_search.apply_transformation(obs, pred, transformation)[source][source]#

Apply transformation to observed and predicted values.

Parameters:

obs (numpy.ndarray) – Observed values
pred (numpy.ndarray) – Predicted values
transformation (str) – Transformation type: ‘identity’, ‘log’, or ‘sqrt’.

Returns:

(obs_transformed, pred_transformed)

Return type:

tuple

disdrodb.psd.grid_search.check_censoring(censoring)[source][source]#: Check valid censoring argument.

disdrodb.psd.grid_search.check_loss(loss, valid_metrics={'AE', 'JSD', 'KLDiv', 'KS', 'MAE', 'MSE', 'RMSE', 'SAE', 'SE', 'SSE', 'WD', 'relMAE'})[source][source]#: Check valid loss argument.

disdrodb.psd.grid_search.check_loss_weight(loss_weight)[source][source]#: Check valid loss_weight argument.

disdrodb.psd.grid_search.check_objective(objective)[source][source]#: Check objective validity.

disdrodb.psd.grid_search.check_objectives(objectives)[source][source]#

Validate and normalize objectives for grid search optimization.

Parameters:: objectives (list of dict) – List of objective dictionaries, each containing: - ‘target’ : str, Target variable (N(D), H(x), R, Z, LWC, or M) - ‘transformation’ : str, Transformation type (identity, log, sqrt) - ‘censoring’ : str, Censoring type (none, left, right, both) - ‘loss’ : str, Error metric (SSE, SAE, MAE, MSE, RMSE, etc.) - ‘loss_weight’ : float, optional, Weight for weighted optimization (auto-set to 1.0 for single objective)
Returns:: Validated objectives. Loss weights are not normalized.
Return type:: list of dict

disdrodb.psd.grid_search.check_target(target)[source][source]#: Check valid target argument.

disdrodb.psd.grid_search.check_transformation(transformation)[source][source]#: Check valid transformation argument.

disdrodb.psd.grid_search.check_valid_loss(loss, target)[source][source]#

Check if loss is valid for the given target.

For distribution targets (ND, H(x)), any error metric is valid. For scalar targets (Z, R, LWC), distribution error metrics are not valid.

Parameters:

loss (str) – The error metric to validate.
target (str) – The target variable type.

Returns:

The validated loss.

Return type:

str

Raises:

ValueError – If loss is not valid for the given target.

disdrodb.psd.grid_search.compute_errors(obs, pred, loss, D=None, dD=None)[source][source]#

Compute error between observed and predicted values.

The function is entirely vectorized and can handle multiple predictions at once.

Parameters:

obs (numpy.ndarray) – Observed values. Is scalar value if specified target is an integral variable. Is 1D array of size [n_bins] if target is a distribution.
pred (numpy.ndarray) – Predicted values. Can be 1D [n_samples] or 2D [n_samples, n_bins]. Is 1D when specified target is an integral variable. Is 2D when specified target is a distribution.
loss (str) – Error metric to compute. See supported metrics in ERROR_METRICS.
D (numpy.ndarray, optional) – Diameter bin center in mm [n_bins]. Required for ‘WD’ metric. Default is None.
dD (numpy.ndarray, optional) – Diameter bin width in mm [n_bins]. Required for distribution metrics. Default is None.

Returns:

Computed error(s) [n_samples] for most metrics, or [n_samples, n_bins] for element-wise metrics.

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_jensen_shannon_distance(obs, pred, dD, eps=1e-12)[source][source]#

Compute Jensen-Shannon distance between observed and predicted N(D).

The Jensen-Shannon distance is the square root of the Jensen-Shannon divergence. Values are defined between 0 and np.sqrt(ln(2)) = 0.83256

Vectorized implementation for multiple predictions.

Parameters:

obs (numpy.ndarray) – Observed N(D) values with shape (n_bins,) and units [#/m3/mm-1]
pred (numpy.ndarray) – Predicted N(D) values with shape (n_samples, n_bins) and units [#/m3/mm-1]
dD (numpy.ndarray) – Diameter bin width in mm with shape (n_bins,)

Returns:

Jensen-Shannon distance for each sample [n_samples]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_kl_divergence(obs, pred, dD, eps=1e-12)[source][source]#

Compute Kullback-Leibler divergence between observed and predicted N(D).

Parameters:

obs (numpy.ndarray) – Observed N(D) values with shape (n_bins,) and units [#/m3/mm-1]
pred (numpy.ndarray) – Predicted N(D) values with shape (n_samples, n_bins) and units [#/m3/mm-1]
dD (numpy.ndarray) – Diameter bin width in mm with shape (n_bins,)

Returns:

KL divergence for each sample with shape (n_samples,)

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_kolmogorov_smirnov_distance(obs, pred, dD, eps=1e-12)[source][source]#

Compute Kolmogorov-Smirnov (KS) distance between observed and predicted N(D).

Vectorized implementation for multiple predictions.

Parameters:

obs (numpy.ndarray) – Observed N(D) values with shape (n_bins,) and units [#/m3/mm-1]
pred (numpy.ndarray) – Predicted N(D) values with shape (n_samples, n_bins) and units [#/m3/mm-1]
dD (numpy.ndarray) – Diameter bin width in mm with shape (n_bins,)

Returns:

numpy.ndarray – KS statistic for each sample [n_samples] If 0, the two distributions are identical.
np.ndarray – KS p-value for each sample [n_samples] A p-value of 0 means “strong evidence against equality.” A p-value of 1 means “no evidence against equality.” Identical distributions show a pvalue of 1. Similar distributions show a pvalue close to 1.

disdrodb.psd.grid_search.compute_loss(ND_obs, ND_preds, D, dD, V, target, censoring, transformation, loss, check_arguments=True)[source][source]#

Compute loss.

Computes loss between observed and predicted drop size distributions, with optional censoring, transformation, and target variable specification.

Parameters:

ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins] [m/s]
target (str) – Target variable: ‘Z’, ‘R’, ‘LWC’, moments (‘M0’-‘M6’), ‘N(D)’, or ‘H(x)’.
censoring (str) – Censoring strategy: ‘none’, ‘left’, ‘right’, or ‘both’.
transformation (str) – Transformation: ‘identity’, ‘log’, or ‘sqrt’.
loss (str) – Loss function. If target is "N(D)" or "H(x)", valid options are: - SSE: Sum of Squared Errors - SAE: Sum of Absolute Errors - MAE: Mean Absolute Error - MSE: Mean Squared Error - RMSE: Root Mean Squared Error - relMAE: Relative Mean Absolute Error - KLDiv: Kullback-Leibler Divergence - WD: Wasserstein Distance - JSD: Jensen-Shannon Distance - KS: Kolmogorov-Smirnov Statistic If target is one of "R", "Z", "LWC", or "M", valid options are: - AE: Absolute Error - SE: Squared Error
check_arguments (bool, optional) – If True, validate input arguments. Default is True.

Returns:

Computed errors [n_samples]. Values are NaN where computation failed.

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_lwc(ND, D, dD, rho_w=1000)[source][source]#

Compute liquid water content from drop size distribution.

Parameters:

ND (numpy.ndarray) – Drop size distribution [#/m3/mm-1]. Can be 1D [n_bins] or 2D [n_samples, n_bins].
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
rho_w (float, optional) – Water density [kg/m3]. Default is 1000.

Returns:

Liquid water content [g/m3]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_moment(ND, order, D, dD)[source][source]#

Compute moment of the drop size distribution.

Parameters:

ND (numpy.ndarray) – Drop size distribution [#/m3/mm-1]. Can be 1D [n_bins] or 2D [n_samples, n_bins].
order (int) – Moment order.
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]

Returns:

Moment of the specified order [mm^order·m^-3]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_rain_rate(ND, D, dD, V)[source][source]#

Compute rain rate from drop size distribution.

Parameters:

ND (numpy.ndarray) – Drop size distribution [#/m3/mm-1]. Can be 1D [n_bins] or 2D [n_samples, n_bins].
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins] [m/s]

Returns:

Rain rate [mm/h]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_target_variable(target, ND_obs, ND_preds, D, dD, V)[source][source]#

Compute target variable from drop size distribution.

Parameters:

target (str) – Target variable type. Can be ‘Z’, ‘R’, ‘LWC’, moments (‘M0’-‘M6’), ‘N(D)’, or ‘H(x)’.
ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins] [m/s]

Returns:

(obs, pred) where obs is 1D [n_bins] or scalar, and pred is 2D [n_samples, n_bins] or 1D [n_samples]

Return type:

tuple

disdrodb.psd.grid_search.compute_wasserstein_distance(obs, pred, D, dD, eps=1e-12, integration='bin')[source][source]#

Compute Wasserstein distance (Earth Mover’s Distance) between observed and predicted N(D).

Vectorized implementation for multiple predictions.

Parameters:

obs (numpy.ndarray) – Observed N(D) values with shape (n_bins,) and units [#/m3/mm-1]
pred (numpy.ndarray) – Predicted N(D) values with shape (n_samples, n_bins) and units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin centers in mm with shape (n_bins,)
dD (numpy.ndarray) – Diameter bin width in mm with shape (n_bins,)
integration (str, optional) –
Integration scheme used to compute the Wasserstein integral. Supported options are "bin" and "left_riemann".

"bin" compute Histogram-based Wasserstein distance. N(D) are interpreted as piecewise-constant densities over bins of width dD. The distance is computed by integrating the difference between cumulative distribution functions over each bin. This is the default.

"left_riemann" computes Discrete-support Wasserstein distance. Probability mass is assumed to be concentrated at bin centers D, and the integral is approximated using the spacing between support points, consistent with scipy.stats.wasserstein_distance().

Returns:

Wasserstein distance for each sample [n_samples]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_weighted_loss(ND_obs, ND_preds, D, dD, V, objectives, Nc=None)[source][source]#

Compute weighted loss between observed and predicted particle size distributions.

Parameters:

ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins] [m/s]
objectives (list of dict) –
targetstr, optional
Target quantity to optimize. Valid options:
- "N(D)" : Drop number concentration [m⁻³ mm⁻¹]
- "H(x)" : Normalized drop number concentration [-]
- "R" : Rain rate [mm h⁻¹]
- "Z" : Radar reflectivity [mm⁶ m⁻³]
- "LWC" : Liquid water content [g m⁻³]
- "M" : Moment of order p
transformationstr, optional
Transformation applied to the target quantity before computing the loss. Valid options:
- "identity" : No transformation
- "log" : Logarithmic transformation
- "sqrt" : Square root transformation
censoringstr
Specifies whether the observed particle size distribution (PSD) is treated as censored at the edges of the diameter range due to instrumental sensitivity limits:
- "none" : No censoring is applied. All diameter bins are used.
- "left" : Left-censored PSD. Diameter bins at the lower end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "right" : Right-censored PSD. Diameter bins at the upper end of the spectrum where the observed number concentration is zero are removed prior to cost-function evaluation.
- "both" : Both left- and right-censored PSD. Only the contiguous range of diameter bins with non-zero observed concentrations is retained.
lossint, optional
Loss function. If target is "N(D)" or "H(x)", valid options are:
- SSE: Sum of Squared Errors
- SAE: Sum of Absolute Errors
- MAE: Mean Absolute Error
- MSE: Mean Squared Error
- RMSE: Root Mean Squared Error
- relMAE: Relative Mean Absolute Error
- KLDiv: Kullback-Leibler Divergence
- WD: Wasserstein Distance
- JSD: Jensen-Shannon Distance
- KS: Kolmogorov-Smirnov Statistic
If target is one of "R", "Z", "LWC", or "M", valid options are:
- AE: Absolute Error
- SE: Squared Error
loss_weight: int, optional
Weight of this objective when multiple objectives are used. Must be specified if more than one objective is specified.
Nc (float, optional) – Normalization constant for H(x) target. If provided, N(D) will be divided by Nc.

Returns:

Computed errors [n_samples]. Values are NaN where computation failed.

Return type:

numpy.ndarray

disdrodb.psd.grid_search.compute_z(ND, D, dD)[source][source]#

Compute radar reflectivity from drop size distribution.

Parameters:

ND (numpy.ndarray) – Drop size distribution [#/m3/mm-1]. Can be 1D [n_bins] or 2D [n_samples, n_bins].
D (numpy.ndarray) – Diameter bin centers in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]

Returns:

Radar reflectivity [dBZ]

Return type:

numpy.ndarray

disdrodb.psd.grid_search.left_truncate_bins(ND_obs, ND_preds, D, dD, V)[source][source]#

Truncate left side of bins (smallest diameters) to first non-zero bin.

Parameters:

ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin center in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins]

Returns:

(ND_obs_trunc, ND_preds_trunc, D_trunc, dD_trunc, V_trunc) or None if all zeros

Return type:

tuple or None

disdrodb.psd.grid_search.normalize_errors(errors)[source][source]#

Normalize errors to scale minimum error region to O(1).

Scaling by the median value of the p0-p10 region normalizes error in the minimum region to approximately O(1). Scaling by p95-p5 is not used because when tails span orders of magnitude, it normalizes the spread rather than the minimum region, suppressing the minimum region and amplifying the bad region.

Parameters:: errors (numpy.ndarray) – Error values to normalize [n_samples]
Returns:: Normalized errors (if normalize_error=True) or original errors (if False)
Return type:: numpy.ndarray

disdrodb.psd.grid_search.right_truncate_bins(ND_obs, ND_preds, D, dD, V)[source][source]#

Truncate right side of bins (largest diameters) to last non-zero bin.

Parameters:

ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin center in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins]

Returns:

(ND_obs_trunc, ND_preds_trunc, D_trunc, dD_trunc, V_trunc) or None if all zeros

Return type:

tuple or None

disdrodb.psd.grid_search.truncate_bin_edges(ND_obs, ND_preds, D, dD, V, left_censored=False, right_censored=False)[source][source]#

Truncate bin edges based on censoring strategy.

Parameters:

ND_obs (numpy.ndarray) – Observed drop size distribution of shape (n_bins, ) with units [#/m3/mm-1]
ND_preds (numpy.ndarray) – Predicted drop size distributions of shape (n_samples, n_bins) with units [#/m3/mm-1]
D (numpy.ndarray) – Diameter bin center in mm [n_bins]
dD (numpy.ndarray) – Diameter bin width in mm [n_bins]
V (numpy.ndarray) – Terminal velocity [n_bins]
left_censored (bool, optional) – If True, truncate from the left (remove small diameter bins). Default is False.
right_censored (bool, optional) – If True, truncate from the right (remove large diameter bins). Default is False.

Returns:

(ND_obs_trunc, ND_preds_trunc, D_trunc, dD_trunc, V_trunc) or None if all zeros

Return type:

tuple or None

disdrodb.psd.models module#

Definition of PSD models.

The class implementation is inspired by pytmatrix.psd and pyradsim.psd modules and adapted to allow efficient vectorized computations with xarray.

Source code: - jleinonen/pytmatrix - wolfidan/pyradsim

class disdrodb.psd.models.BinnedPSD(bin_edges, bin_psd, interp_method='step_left')[source][source]#

Bases: PSD

Binned particle size distribution (PSD).

This class represents a binned PSD that computes values through interpolation between discretized bin values. This approach is useful for representing empirically measured or discretized PSDs.

The PSD values are computed via interpolation from discrete bin values using various methods. Values outside the defined bin range are set to zero, and all returned values are non-negative.

Parameters:

bin_edges (array-like) – Sequence of n+1 bin edge values defining the bins [mm]. Must be monotonically increasing.
bin_psd (array-like) – Sequence of n PSD values corresponding to the intervals defined by bin_edges [m^-3 mm^-1].
interp_method (str, optional) –
Interpolation method for computing PSD values between bin centers. Valid methods can be:
- ’step_left’: Use the value from the left bin (piecewise constant, left-continuous)
- ’step_right’: Use the value from the right bin (piecewise constant, right-continuous)
- ’linear’: Linear interpolation between bin centers
- ’pchip’: Piecewise Cubic Hermite Interpolating Polynomial, preserves monotonicity
Default is ‘step_left’.

bin_edges#

Bin edge values.

Type:: numpy.ndarray

bin_psd#

PSD values for each bin.

Type:: numpy.ndarray

interp_method#

Selected interpolation method.

Type:: str

Notes

Values for diameters D outside the range (bin_edges[0], bin_edges[-1]) are set to 0
Interpolation is performed using bin centers computed as the midpoint of each bin
All PSD values are clipped to be non-negative after interpolation
The ‘pchip’ method is recommended when smoothness and monotonicity preservation are important

Examples

>>> import numpy as np
>>> bin_edges = [0.0, 1.0, 2.0, 3.0, 4.0]
>>> bin_psd = [10.0, 20.0, 30.0, 0.0]
>>> D = np.linspace(0, 3.5, 100)
>>>
>>> # Using linear interpolation
>>> psd_linear = BinnedPSD(bin_edges, bin_psd, interp_method="linear")
>>> psd_values = psd_linear(D)
>>>
>>> # Using step interpolation
>>> psd_step = BinnedPSD(bin_edges, bin_psd, interp_method="step_left")
>>> psd_values_step = psd_step(D)

class disdrodb.psd.models.ExponentialPSD(N0=1.0, Lambda=1.0)[source][source]#

Bases: XarrayPSD

Exponential particle size distribution (PSD).

This class implements an exponential PSD model, which is one of the simplest forms used to describe particle size distributions.

The PSD is defined by the formula:

\[N(D) = N_0 \exp(-\Lambda D)\]

Parameters:

N0 (float or xarray.DataArray, optional) – Intercept parameter [m^-3 mm^-1]. Default is 1.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.

N0#

Intercept parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The exponential distribution is a special case of the gamma distribution with shape parameter mu = 0.

static formula(D, N0, Lambda)[source][source]#

Calculate the Exponential PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
N0 (float or array-like) – Intercept parameter [m^-3 mm^-1].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize ExponentialPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘N0’ and ‘Lambda’.
Returns:: An instance of ExponentialPSD initialized with the parameters.
Return type:: ExponentialPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#

Return a string with the parameter summary.

Returns:: Formatted string summarizing the PSD parameters.
Return type:: str

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.GammaPSD(N0=1.0, mu=0.0, Lambda=1.0)[source][source]#

Bases: ExponentialPSD

Gamma particle size distribution (PSD).

This class implements a gamma PSD model, which is widely used to describe raindrop size distributions and other particle size distributions in atmospheric sciences.

The PSD is defined by the formula:

\[N(D) = N_0 D^{\mu} \exp(-\Lambda D)\]

Parameters:

N0 (float or xarray.DataArray, optional) – Intercept parameter (scale parameter) [m^-3 mm^(-1-mu)]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter [-]. Default is 0.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.

N0#

Intercept parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The gamma distribution reduces to the exponential distribution when mu = 0. This formulation is particularly useful for representing natural variations in raindrop size distributions.

References

Ulbrich, C. W., 1983. Natural Variations in the Analytical Form of the Raindrop Size Distribution. J. Appl. Meteor. Climatol., 22, 1764-1775, https://doi.org/10.1175/1520-0450(1983)022<1764:NVITAF>2.0.CO;2

static compute_Dm(mu, Lambda)[source][source]#

Compute mass-weighted mean diameter from PSD parameters.

Parameters:

mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

Mass-weighted mean diameter Dm [mm].

Return type:

float or array-like

static compute_sigma_m(mu, Lambda)[source][source]#

Compute standard deviation of mass-weighted distribution.

Parameters:

mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

Standard deviation sigma_m [mm].

Return type:

float or array-like

static formula(D, N0, Lambda, mu)[source][source]#

Calculate the Gamma PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
N0 (float or array-like) – Intercept parameter [m^-3 mm^(-1-mu)].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].
mu (float or array-like) – Shape parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize GammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘N0’, ‘Lambda’, and ‘mu’.
Returns:: An instance of GammaPSD initialized with the parameters.
Return type:: GammaPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#

Return a string with the parameter summary.

Returns:: Formatted string summarizing the PSD parameters.
Return type:: str

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.GeneralizedGammaPSD(Nt=1.0, Lambda=1.0, mu=0.0, c=1.0)[source][source]#

Bases: XarrayPSD

Generalized gamma particle size distribution (PSD).

This class implements a generalized gamma PSD model, which extends the standard gamma distribution by introducing an additional shape parameter c. This provides greater flexibility in representing diverse particle size distributions.

The PSD is defined by the formula:

\[\begin{split}N(D; N_t, \\Lambda, \\mu, c) = N_t \\frac{c\\Lambda}{\\Gamma(\\mu+1)} (\\Lambda D)^{c(\\mu+1)-1} \\exp[-(\\Lambda D)^c]\end{split}\]

Parameters:

Nt (float or xarray.DataArray, optional) – Total concentration parameter [m^-3]. Default is 1.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter, must satisfy mu > -1 [-]. Default is 0.0.
c (float or xarray.DataArray, optional) – Additional shape parameter, must satisfy c ≠ 0 [-]. Default is 1.0.

Nt#

Total concentration parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

c#

Additional shape parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The generalized gamma distribution reduces to the standard gamma distribution when c = 1. The parameter c provides additional flexibility in controlling the shape of the distribution, particularly useful for representing diverse atmospheric particle populations.

References

Lee, G. W., I. Zawadzki, W. Szyrmer, D. Sempere-Torres, and R. Uijlenhoet, 2004. A General Approach to Double-Moment Normalization of Drop Size Distributions. J. Appl. Meteor. Climatol., 43, 264-281, https://doi.org/10.1175/1520-0450(2004)043<0264:AGATDN>2.0.CO;2

static formula(D, Nt, Lambda, mu, c)[source][source]#

Calculates the Generalized Gamma PSD values.

Parameters:

D (array-like) – Particle diameter
Nt (float or array-like) – Total concentration parameter [m^-3]
Lambda (float or array-like) – Inverse scale parameter [???]
mu (float or array-like) – Shape parameter (μ > -1)
c (float or array-like) – Shape parameter (c ≠ 0)

Returns:

PSD values

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize GeneralizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nt’, ‘Lambda’, ‘mu’, and ‘c’.
Returns:: An instance of GeneralizedGammaPSD initialized with the parameters.
Return type:: GeneralizedGammaPSD

property name[source]#: Return the PSD name.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.LognormalPSD(Nt=1.0, mu=0.0, sigma=1.0)[source][source]#

Bases: XarrayPSD

Lognormal particle size distribution (PSD).

This class implements a lognormal PSD model, which is commonly used to describe particle size distributions in atmospheric sciences.

The PSD is defined by the formula:

\[N(D) = \frac{N_t}{\sqrt{2\pi} \sigma D} \exp\left(-\frac{(\ln(D) - \mu)^2}{2\sigma^2}\right)\]

Parameters:

Nt (float or xarray.DataArray, optional) – Total concentration parameter [m^-3]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Location parameter of the underlying normal distribution [-]. Default is 0.0.
sigma (float or xarray.DataArray, optional) – Scale parameter (standard deviation) of the underlying normal distribution [-]. Default is 1.0.

Nt#

Total concentration parameter.

Type:: float or xarray.DataArray

mu#

Location parameter.

Type:: float or xarray.DataArray

sigma#

Scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The lognormal distribution is characterized by the fact that the logarithm of the variable follows a normal distribution.

static formula(D, Nt, mu, sigma)[source][source]#

Calculate the Lognormal PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
Nt (float or array-like) – Total concentration parameter [m^-3].
mu (float or array-like) – Location parameter [-].
sigma (float or array-like) – Scale parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize LognormalPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nt’, ‘mu’, and ‘sigma’.
Returns:: An instance of LognormalPSD initialized with the parameters.
Return type:: LognormalPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.NormalizedGammaPSD(Nw=1.0, D50=1.0, mu=0.0)[source][source]#

Bases: XarrayPSD

Normalized gamma particle size distribution (PSD).

Callable class implementing a normalized gamma particle size distribution parameterized by a characteristic diameter and shape parameter. The PSD can be evaluated by calling the instance with particle diameters.

Notes

The normalized gamma PSD is defined as:

\[N(D) = N_w \ f(\mu) \left( \frac{D}{D_{50}} \right)^{\mu} \exp\!\left[-(\mu + 3.67)\frac{D}{D_{50}}\right]\]

with

\[f(\mu) = \frac{6}{3.67^4} \frac{(\mu + 3.67)^{\mu + 4}}{\Gamma(\mu + 4)}\]

where:

\(D\) is the particle diameter,
\(D_{50}\) is the median volume diameter,
\(N_w\) is the intercept parameter,
\(\mu\) is the shape parameter,
\(\Gamma(\cdot)\) denotes the gamma function.

Alternative formulation using the mass-weighted mean diameter \(D_m\) (Testud et al., 2001; Bringi et al., 2001; Williams et al., 2014; Dolan et al., 2018):

\[N(D) = N_w \, f_1(\mu) \left( \frac{D}{D_m} \right)^{\mu} \exp\!\left[-(\mu + 4)\frac{D}{D_m}\right]\]

with

\[f_1(\mu) = \frac{6}{4^4} \frac{(\mu + 4)^{\mu + 4}}{\Gamma(\mu + 4)}\]

This formulation corresponds to a normalization with respect to liquid water content.

Another alternative formulation normalized by total number concentration (Tokay et al., 2010; Illingworth et al., 2002):

\[N(D) = N_t \, f_2(\mu) \left( \frac{D}{D_m} \right)^{\mu} \exp\!\left[-(\mu + 4)\frac{D}{D_m}\right]\]

with

\[f_2(\mu) = \frac{(\mu + 4)^{\mu + 1}}{\Gamma(\mu + 1)}\]

Note that \(\Gamma(4) = 6\).

D50#

Median volume diameter.

Type:: float or xarray.DataArray

Nw#

Intercept parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

Parameters:: D (float or array-like) – Particle diameter (same units as \(D_{50}\) or \(D_m\)).
Returns:: Particle size distribution value evaluated at diameter D.
Return type:: float or array-like

References

Willis, P. T., 1984: Functional Fits to Some Observed Drop Size Distributions and Parameterization of Rain. J. Atmos. Sci., 41, 1648-1661, https://doi.org/10.1175/1520-0469(1984)041<1648:FFTSOD>2.0.CO;2

Illingworth, A. J., and T. M. Blackman, 2002: The Need to Represent Raindrop Size Spectra as Normalized Gamma Distributions for the Interpretation of Polarization Radar Observations. J. Appl. Meteor. Climatol., 41, 286-297, https://doi.org/10.1175/1520-0450(2002)041<0286:TNTRRS>2.0.CO;2

Bringi, V. N., G. Huang, V. Chandrasekar, and E. Gorgucci, 2002: A Methodology for Estimating the Parameters of a Gamma Raindrop Size Distribution Model from Polarimetric Radar Data: Application to a Squall-Line Event from the TRMM/Brazil Campaign. J. Atmos. Oceanic Technol., 19, 633-645, https://doi.org/10.1175/1520-0426(2002)019<0633:AMFETP>2.0.CO;2

Bringi, V. N., V. Chandrasekar, J. Hubbert, E. Gorgucci, W. L. Randeu, and M. Schoenhuber, 2003: Raindrop Size Distribution in Different Climatic Regimes from Disdrometer and Dual-Polarized Radar Analysis. J. Atmos. Sci., 60, 354-365, https://doi.org/10.1175/1520-0469(2003)060<0354:RSDIDC>2.0.CO;2

Tokay, A., and P. G. Bashor, 2010: An Experimental Study of Small-Scale Variability of Raindrop Size Distribution. J. Appl. Meteor. Climatol., 49, 2348-2365, https://doi.org/10.1175/2010JAMC2269.1

static formula(D, Nw, D50, mu)[source][source]#

Calculate the Normalized Gamma PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
Nw (float or array-like) – Intercept parameter [m^-3 mm^-1].
D50 (float or array-like) – Median volume diameter [mm].
mu (float or array-like) – Shape parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize NormalizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nw’, ‘D50’, and ‘mu’.
Returns:: An instance of NormalizedGammaPSD initialized with the parameters.
Return type:: NormalizedGammaPSD

property name[source]#: Return the PSD name.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.NormalizedGeneralizedGammaPSD(i=1.0, j=0.0, Nc=1, Dc=1.0, c=1.0, mu=0.0)[source][source]#

Bases: XarrayPSD

Normalized generalized gamma particle size distribution (PSD).

This class implements a normalized generalized gamma PSD model based on the double-moment normalization framework. This formulation uses two moments of the distribution to derive normalized parameters, providing a flexible representation of particle size distributions.

The PSD is defined by the formula:

\[N(D; M_i, M_j, \mu, c) = N_c \, c \, \Gamma_i^{\frac{j + c(\mu + 1)}{i - j}} \Gamma_j^{\frac{-i - c(\mu + 1)}{i - j}} \left(\frac{D}{D_c}\right)^{c(\mu + 1) - 1} \exp\left[ -\left(\frac{\Gamma_i}{\Gamma_j}\right)^{\frac{c}{i - j}} \left(\frac{D}{D_c}\right)^c \right]\]

where the normalization parameters are defined as:

\[N_c = M_i^{\frac{j + 1}{j - i}} M_j^{\frac{i + 1}{i - j}}\]

\[D_c = \left(\frac{M_j}{M_i}\right)^{\frac{1}{j - i}}\]

with \(M_i = \Gamma_i\) and \(M_j = \Gamma_j\) representing the i-th and j-th moments of the distribution.

Parameters:

i (float or int, optional) – Moment index i [-]. Default is 1.0.
j (float or int, optional) – Moment index j [-]. Default is 0.0.
Nc (float or xarray.DataArray, optional) – Normalized intercept parameter [m^-3 mm^-1]. Default is 1.0.
Dc (float or xarray.DataArray, optional) – Characteristic diameter parameter [mm]. Default is 1.0.
c (float or xarray.DataArray, optional) – Shape parameter, must satisfy c ≠ 0 [-]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter, must satisfy mu > -1 [-]. Default is 0.0.

i#

Moment index i.

Type:: float or int

j#

Moment index j.

Type:: float or int

Nc#

Normalized intercept parameter computed from moments.

Type:: float or xarray.DataArray

Dc#

Characteristic diameter parameter computed from moments.

Type:: float or xarray.DataArray

c#

Shape parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The double-moment normalization framework uses two arbitrary moments of the distribution to compute the normalization parameters Nc and Dc. This approach provides a unified framework for comparing different PSD models and relating them to observable quantities.

The moment indices i and j are typically chosen based on the moments that can be most reliably measured or estimated from observations. Common choices include (i=3, j=4) or (i=3, j=6) for radar applications.

References

Lee, G. W., I. Zawadzki, W. Szyrmer, D. Sempere-Torres, and R. Uijlenhoet, 2004: A General Approach to Double-Moment Normalization of Drop Size Distributions. J. Appl. Meteor. Climatol., 43, 264-281, https://doi.org/10.1175/1520-0450(2004)043<0264:AGATDN>2.0.CO;2

static compute_Dc(i, j, Mi, Mj)[source][source]#

Compute D_c from i, j, Mi, Mj.

\[D_c = \left(\frac{M_j}{M_i}\right)^{\frac{1}{j - i}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The characteristic diameter parameter D_c with units mm.

Return type:

float or array-like

static compute_Nc(i, j, Mi, Mj)[source][source]#

Compute N_c from i, j, Mi, Mj.

\[N_c = M_i^{\frac{j + 1}{j - i}} M_j^{\frac{i + 1}{i - j}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The normalized intercept parameter N_c with units m-3 mm-1.

Return type:

float or array-like

static formula(D, i, j, Nc, Dc, c, mu)[source][source]#

Calculates the Normalized Generalized Gamma PSD N(D) values.

N_c and D_c are computed internally from the parameters.

Parameters:

D (array-like) – Particle diameter
i (float) – Moment index i
j (float) – Moment index j
Nc (float) – General characteristic intercept (mm-1 m-3)
Dc (float) – General characteristic diameter (mm)
c (float) – Shape parameter c
mu (float) – Shape parameter μ

Returns:

PSD values

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize NormalizedGeneralizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘i’, ‘j’, ‘Nc’, ‘Dc’, ‘c’, and ‘mu’. The moment indices ‘i’ and ‘j’ can also be provided in the ‘disdrodb_psd_model_kwargs’ attribute if parameters is an xarray.Dataset.
Returns:: An instance of NormalizedGeneralizedGammaPSD initialized with the parameters.
Return type:: NormalizedGeneralizedGammaPSD

property name[source]#: Return the PSD name.

static normalized_formula(x, i, j, c, mu)[source][source]#

Calculates N(D)/Nc from x=D/Dc.

This formula is useful to fit a single normalized PSD shape to data in the double normalization framework.

Parameters:

x (array-like) – Normalized particle diameter: x = D/Dc
i (float) – Moment index i
j (float) – Moment index j
c (float) – Shape parameter c
mu (float) – Shape parameter μ

Returns:

N(D)/Nc values

Return type:

array-like

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.models.PSD[source][source]#

Bases: object

Dummy PSD class placeholder when pytmatrix is not available.

This class serves as a placeholder when the pytmatrix library is not installed, allowing the module to be imported without errors while maintaining the class hierarchy for PSD models.

class disdrodb.psd.models.XarrayPSD[source][source]#

Bases: PSD

PSD class template allowing vectorized computations with xarray.

This class serves as a base template for Particle Size Distribution (PSD) models that support vectorized computations with xarray.DataArray objects. It extends the pytmatrix PSD class to maintain compatibility with scattering simulations.

Notes

This class inherits from pytmatrix PSD to enable scattering simulations. See: ltelab/pytmatrix-lte

The class supports both scalar and xarray.DataArray parameters, enabling efficient vectorized operations across multiple dimensions.

has_scalar_parameters()[source][source]#

Check if the PSD object contains only scalar parameters.

Returns:: True if all parameters are scalars, False otherwise.
Return type:: bool

has_xarray_parameters()[source][source]#

Check if the PSD object contains at least one xarray parameter.

Returns:: True if at least one parameter is an xarray.DataArray, False otherwise.
Return type:: bool

isel(**kwargs)[source][source]#

Subset the parameters by index using xarray.isel.

Parameters:: **kwargs (dict) – Indexing arguments passed to xarray.DataArray.isel().
Returns:: A new PSD instance with subset parameters.
Return type:: XarrayPSD
Raises:: ValueError – If the PSD does not have xarray parameters.

sel(**kwargs)[source][source]#

Subset the parameters by label using xarray.sel.

Parameters:: **kwargs (dict) – Indexing arguments passed to xarray.DataArray.sel().
Returns:: A new PSD instance with subset parameters.
Return type:: XarrayPSD
Raises:: ValueError – If the PSD does not have xarray parameters.

disdrodb.psd.models.available_psd_models()[source][source]#

Return a list of available PSD models.

Returns:: List of available PSD model names.
Return type:: list of str

disdrodb.psd.models.check_diameter_inputs(D)[source][source]#

Check validity of diameter input.

Parameters:

D (int, float, array-like, or xarray.DataArray) – Diameter values to validate [mm].

Returns:

The validated diameter input.

Return type:

int, float, numpy.ndarray, dask.array.Array, or xarray.DataArray

Raises:

ValueError – If the diameter array is not 1-dimensional or is empty.
TypeError – If the diameter type is invalid.

disdrodb.psd.models.check_input_parameters(parameters)[source][source]#

Check validity of input parameters.

Parameters:: parameters (dict) – Dictionary of PSD parameters to validate.
Returns:: The validated parameters dictionary.
Return type:: dict
Raises:: TypeError – If any parameter is not a scalar or xarray.DataArray.

disdrodb.psd.models.check_psd_model(psd_model)[source][source]#

Check validity of a PSD model.

Parameters:: psd_model (str) – Name of the PSD model to validate.
Returns:: The validated PSD model name.
Return type:: str
Raises:: ValueError – If the PSD model is not valid.

disdrodb.psd.models.compute_Dc(i, j, Mi, Mj)[source][source]#

Compute double moment normalization characteristic diameter D_c.

The characteristic diameter is calculated as:

\[D_c = \left(\frac{M_j}{M_i}\right)^{\frac{1}{j - i}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The characteristic diameter parameter D_c with units mm.

Return type:

float or array-like

disdrodb.psd.models.compute_Nc(i, j, Mi, Mj)[source][source]#

Compute double moment normalization intercept parameter N_c.

The normalized intercept parameter is calculated as:

\[N_c = M_i^{\frac{j + 1}{j - i}} M_j^{\frac{i + 1}{i - j}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The normalized intercept parameter N_c with units m-3 mm-1.

Return type:

float or array-like

disdrodb.psd.models.create_psd(psd_model, parameters)[source][source]#

Create a PSD instance from model name and parameters.

Parameters:

psd_model (str) – Name of the PSD model.
parameters (dict or xarray.Dataset) – Dictionary or Dataset containing the PSD parameters.

Returns:

An instance of the specified PSD model initialized with the given parameters.

Return type:

XarrayPSD

disdrodb.psd.models.create_psd_from_dataset(ds_params)[source][source]#

Create a PSD instance from a DISDRODB L2M product.

Parameters:: ds_params (xarray.Dataset) – DISDRODB L2M dataset containing PSD parameters and metadata. Must have ‘disdrodb_psd_model’ attribute.
Returns:: An instance of the PSD model specified in the dataset attributes.
Return type:: XarrayPSD
Raises:: ValueError – If the dataset does not contain ‘disdrodb_psd_model’ attribute.

disdrodb.psd.models.define_interpolator(bin_edges, bin_values, interp_method)[source][source]#

Create an interpolation function for binned data.

Parameters:

bin_edges (array-like) – Sorted array of n+1 bin edge values [mm].
bin_values (array-like) – Array of n bin values corresponding to each bin.
interp_method (str) –
Interpolation method:
- ’step_left’: Piecewise constant, left-continuous
- ’step_right’: Piecewise constant, right-continuous
- ’linear’: Linear interpolation
- ’pchip’: Piecewise Cubic Hermite Interpolating Polynomial

Returns:

A function f(D) that returns the interpolated values for diameter D.

Return type:

callable

disdrodb.psd.models.get_exponential_moment(N0, Lambda, moment)[source][source]#

Compute moments of the exponential distribution.

Parameters:

N0 (float or array-like) – Intercept parameter [m^-3 mm^-1].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].
moment (int or float) – Moment order.

Returns:

The computed moment value.

Return type:

float or array-like

disdrodb.psd.models.get_gamma_moment_v1(N0, mu, Lambda, moment)[source][source]#

Compute moments of the gamma distribution (version 1).

Parameters:

N0 (float or array-like) – Intercept parameter [m^-3 mm^(-1-mu)].
mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].
moment (int or float) – Moment order.

Returns:

The computed moment value.

Return type:

float or array-like

References

disdrodb.psd.models.get_gamma_moment_v2(Nt, mu, Lambda, moment)[source][source]#

Compute moments of the gamma distribution (version 2).

Parameters:

Nt (float or array-like) – Total concentration parameter [m^-3].
mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].
moment (int or float) – Moment order.

Returns:

The computed moment value.

Return type:

float or array-like

References

disdrodb.psd.models.get_lognormal_moment(Nt, sigma, mu, moment)[source][source]#

Compute moments of the lognormal distribution.

Parameters:

Nt (float or array-like) – Total concentration parameter [m^-3].
sigma (float or array-like) – Scale parameter [-].
mu (float or array-like) – Location parameter [-].
moment (int or float) – Moment order.

Returns:

The computed moment value.

Return type:

float or array-like

References

disdrodb.psd.models.get_parameters_from_dataset(ds)[source][source]#

Extract PSD parameters from DISDRODB L2M dataset.

Parameters:: ds (xarray.Dataset) – DISDRODB L2M dataset containing PSD parameters. Must have ‘disdrodb_psd_model’ attribute.
Returns:: Dataset containing only the PSD parameter variables.
Return type:: xarray.Dataset
Raises:: ValueError – If the dataset does not contain ‘disdrodb_psd_model’ attribute.

disdrodb.psd.models.get_psd_model(psd_model)[source][source]#

Retrieve the PSD class.

Parameters:: psd_model (str) – Name of the PSD model.
Returns:: The PSD class corresponding to the model name.
Return type:: type

disdrodb.psd.models.get_psd_model_formula(psd_model)[source][source]#

Retrieve the PSD formula function.

Parameters:: psd_model (str) – Name of the PSD model.
Returns:: The static formula method of the PSD class.
Return type:: callable

disdrodb.psd.models.get_required_parameters(psd_model)[source][source]#

Retrieve the list of parameters required by a PSD model.

Parameters:: psd_model (str) – Name of the PSD model.
Returns:: List of required parameter names for the specified PSD model.
Return type:: list of str

disdrodb.psd.models.is_scalar(value)[source][source]#

Determine if the input value is a scalar.

Parameters:: value (any) – Value to check.
Returns:: True if the value is a scalar, False otherwise.
Return type:: bool

Notes

A value is considered scalar if it is an int, float, or a numpy/xarray array with exactly one element.

Module contents#

Implement PSD model and fitting routines.

class disdrodb.psd.ExponentialPSD(N0=1.0, Lambda=1.0)[source][source]#

Bases: XarrayPSD

Exponential particle size distribution (PSD).

This class implements an exponential PSD model, which is one of the simplest forms used to describe particle size distributions.

The PSD is defined by the formula:

\[N(D) = N_0 \exp(-\Lambda D)\]

Parameters:

N0 (float or xarray.DataArray, optional) – Intercept parameter [m^-3 mm^-1]. Default is 1.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.

N0#

Intercept parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The exponential distribution is a special case of the gamma distribution with shape parameter mu = 0.

static formula(D, N0, Lambda)[source][source]#

Calculate the Exponential PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
N0 (float or array-like) – Intercept parameter [m^-3 mm^-1].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize ExponentialPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘N0’ and ‘Lambda’.
Returns:: An instance of ExponentialPSD initialized with the parameters.
Return type:: ExponentialPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#

Return a string with the parameter summary.

Returns:: Formatted string summarizing the PSD parameters.
Return type:: str

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.GammaPSD(N0=1.0, mu=0.0, Lambda=1.0)[source][source]#

Bases: ExponentialPSD

Gamma particle size distribution (PSD).

This class implements a gamma PSD model, which is widely used to describe raindrop size distributions and other particle size distributions in atmospheric sciences.

The PSD is defined by the formula:

\[N(D) = N_0 D^{\mu} \exp(-\Lambda D)\]

Parameters:

N0 (float or xarray.DataArray, optional) – Intercept parameter (scale parameter) [m^-3 mm^(-1-mu)]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter [-]. Default is 0.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.

N0#

Intercept parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The gamma distribution reduces to the exponential distribution when mu = 0. This formulation is particularly useful for representing natural variations in raindrop size distributions.

References

static compute_Dm(mu, Lambda)[source][source]#

Compute mass-weighted mean diameter from PSD parameters.

Parameters:

mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

Mass-weighted mean diameter Dm [mm].

Return type:

float or array-like

static compute_sigma_m(mu, Lambda)[source][source]#

Compute standard deviation of mass-weighted distribution.

Parameters:

mu (float or array-like) – Shape parameter [-].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].

Returns:

Standard deviation sigma_m [mm].

Return type:

float or array-like

static formula(D, N0, Lambda, mu)[source][source]#

Calculate the Gamma PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
N0 (float or array-like) – Intercept parameter [m^-3 mm^(-1-mu)].
Lambda (float or array-like) – Inverse scale parameter [mm^-1].
mu (float or array-like) – Shape parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize GammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘N0’, ‘Lambda’, and ‘mu’.
Returns:: An instance of GammaPSD initialized with the parameters.
Return type:: GammaPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#

Return a string with the parameter summary.

Returns:: Formatted string summarizing the PSD parameters.
Return type:: str

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.GeneralizedGammaPSD(Nt=1.0, Lambda=1.0, mu=0.0, c=1.0)[source][source]#

Bases: XarrayPSD

Generalized gamma particle size distribution (PSD).

The PSD is defined by the formula:

\[\begin{split}N(D; N_t, \\Lambda, \\mu, c) = N_t \\frac{c\\Lambda}{\\Gamma(\\mu+1)} (\\Lambda D)^{c(\\mu+1)-1} \\exp[-(\\Lambda D)^c]\end{split}\]

Parameters:

Nt (float or xarray.DataArray, optional) – Total concentration parameter [m^-3]. Default is 1.0.
Lambda (float or xarray.DataArray, optional) – Inverse scale parameter (slope parameter) [mm^-1]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter, must satisfy mu > -1 [-]. Default is 0.0.
c (float or xarray.DataArray, optional) – Additional shape parameter, must satisfy c ≠ 0 [-]. Default is 1.0.

Nt#

Total concentration parameter.

Type:: float or xarray.DataArray

Lambda#

Inverse scale parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

c#

Additional shape parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

References

static formula(D, Nt, Lambda, mu, c)[source][source]#

Calculates the Generalized Gamma PSD values.

Parameters:

D (array-like) – Particle diameter
Nt (float or array-like) – Total concentration parameter [m^-3]
Lambda (float or array-like) – Inverse scale parameter [???]
mu (float or array-like) – Shape parameter (μ > -1)
c (float or array-like) – Shape parameter (c ≠ 0)

Returns:

PSD values

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize GeneralizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nt’, ‘Lambda’, ‘mu’, and ‘c’.
Returns:: An instance of GeneralizedGammaPSD initialized with the parameters.
Return type:: GeneralizedGammaPSD

property name[source]#: Return the PSD name.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.LognormalPSD(Nt=1.0, mu=0.0, sigma=1.0)[source][source]#

Bases: XarrayPSD

Lognormal particle size distribution (PSD).

This class implements a lognormal PSD model, which is commonly used to describe particle size distributions in atmospheric sciences.

The PSD is defined by the formula:

\[N(D) = \frac{N_t}{\sqrt{2\pi} \sigma D} \exp\left(-\frac{(\ln(D) - \mu)^2}{2\sigma^2}\right)\]

Parameters:

Nt (float or xarray.DataArray, optional) – Total concentration parameter [m^-3]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Location parameter of the underlying normal distribution [-]. Default is 0.0.
sigma (float or xarray.DataArray, optional) – Scale parameter (standard deviation) of the underlying normal distribution [-]. Default is 1.0.

Nt#

Total concentration parameter.

Type:: float or xarray.DataArray

mu#

Location parameter.

Type:: float or xarray.DataArray

sigma#

Scale parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

The lognormal distribution is characterized by the fact that the logarithm of the variable follows a normal distribution.

static formula(D, Nt, mu, sigma)[source][source]#

Calculate the Lognormal PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
Nt (float or array-like) – Total concentration parameter [m^-3].
mu (float or array-like) – Location parameter [-].
sigma (float or array-like) – Scale parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize LognormalPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nt’, ‘mu’, and ‘sigma’.
Returns:: An instance of LognormalPSD initialized with the parameters.
Return type:: LognormalPSD

property name[source]#: Return name of the PSD.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.NormalizedGammaPSD(Nw=1.0, D50=1.0, mu=0.0)[source][source]#

Bases: XarrayPSD

Normalized gamma particle size distribution (PSD).

Notes

The normalized gamma PSD is defined as:

\[N(D) = N_w \ f(\mu) \left( \frac{D}{D_{50}} \right)^{\mu} \exp\!\left[-(\mu + 3.67)\frac{D}{D_{50}}\right]\]

with

\[f(\mu) = \frac{6}{3.67^4} \frac{(\mu + 3.67)^{\mu + 4}}{\Gamma(\mu + 4)}\]

where:

\(D\) is the particle diameter,
\(D_{50}\) is the median volume diameter,
\(N_w\) is the intercept parameter,
\(\mu\) is the shape parameter,
\(\Gamma(\cdot)\) denotes the gamma function.

Alternative formulation using the mass-weighted mean diameter \(D_m\) (Testud et al., 2001; Bringi et al., 2001; Williams et al., 2014; Dolan et al., 2018):

\[N(D) = N_w \, f_1(\mu) \left( \frac{D}{D_m} \right)^{\mu} \exp\!\left[-(\mu + 4)\frac{D}{D_m}\right]\]

with

\[f_1(\mu) = \frac{6}{4^4} \frac{(\mu + 4)^{\mu + 4}}{\Gamma(\mu + 4)}\]

This formulation corresponds to a normalization with respect to liquid water content.

Another alternative formulation normalized by total number concentration (Tokay et al., 2010; Illingworth et al., 2002):

\[N(D) = N_t \, f_2(\mu) \left( \frac{D}{D_m} \right)^{\mu} \exp\!\left[-(\mu + 4)\frac{D}{D_m}\right]\]

with

\[f_2(\mu) = \frac{(\mu + 4)^{\mu + 1}}{\Gamma(\mu + 1)}\]

Note that \(\Gamma(4) = 6\).

D50#

Median volume diameter.

Type:: float or xarray.DataArray

Nw#

Intercept parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

Parameters:: D (float or array-like) – Particle diameter (same units as \(D_{50}\) or \(D_m\)).
Returns:: Particle size distribution value evaluated at diameter D.
Return type:: float or array-like

References

Tokay, A., and P. G. Bashor, 2010: An Experimental Study of Small-Scale Variability of Raindrop Size Distribution. J. Appl. Meteor. Climatol., 49, 2348-2365, https://doi.org/10.1175/2010JAMC2269.1

static formula(D, Nw, D50, mu)[source][source]#

Calculate the Normalized Gamma PSD values.

Parameters:

D (array-like) – Particle diameter [mm].
Nw (float or array-like) – Intercept parameter [m^-3 mm^-1].
D50 (float or array-like) – Median volume diameter [mm].
mu (float or array-like) – Shape parameter [-].

Returns:

PSD values N(D) [m^-3 mm^-1].

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize NormalizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘Nw’, ‘D50’, and ‘mu’.
Returns:: An instance of NormalizedGammaPSD initialized with the parameters.
Return type:: NormalizedGammaPSD

property name[source]#: Return the PSD name.

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

class disdrodb.psd.NormalizedGeneralizedGammaPSD(i=1.0, j=0.0, Nc=1, Dc=1.0, c=1.0, mu=0.0)[source][source]#

Bases: XarrayPSD

Normalized generalized gamma particle size distribution (PSD).

The PSD is defined by the formula:

where the normalization parameters are defined as:

\[N_c = M_i^{\frac{j + 1}{j - i}} M_j^{\frac{i + 1}{i - j}}\]

\[D_c = \left(\frac{M_j}{M_i}\right)^{\frac{1}{j - i}}\]

with \(M_i = \Gamma_i\) and \(M_j = \Gamma_j\) representing the i-th and j-th moments of the distribution.

Parameters:

i (float or int, optional) – Moment index i [-]. Default is 1.0.
j (float or int, optional) – Moment index j [-]. Default is 0.0.
Nc (float or xarray.DataArray, optional) – Normalized intercept parameter [m^-3 mm^-1]. Default is 1.0.
Dc (float or xarray.DataArray, optional) – Characteristic diameter parameter [mm]. Default is 1.0.
c (float or xarray.DataArray, optional) – Shape parameter, must satisfy c ≠ 0 [-]. Default is 1.0.
mu (float or xarray.DataArray, optional) – Shape parameter, must satisfy mu > -1 [-]. Default is 0.0.

i#

Moment index i.

Type:: float or int

j#

Moment index j.

Type:: float or int

Nc#

Normalized intercept parameter computed from moments.

Type:: float or xarray.DataArray

Dc#

Characteristic diameter parameter computed from moments.

Type:: float or xarray.DataArray

c#

Shape parameter.

Type:: float or xarray.DataArray

mu#

Shape parameter.

Type:: float or xarray.DataArray

parameters#

Dictionary containing all PSD parameters.

Type:: dict

Notes

References

static compute_Dc(i, j, Mi, Mj)[source][source]#

Compute D_c from i, j, Mi, Mj.

\[D_c = \left(\frac{M_j}{M_i}\right)^{\frac{1}{j - i}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The characteristic diameter parameter D_c with units mm.

Return type:

float or array-like

static compute_Nc(i, j, Mi, Mj)[source][source]#

Compute N_c from i, j, Mi, Mj.

\[N_c = M_i^{\frac{j + 1}{j - i}} M_j^{\frac{i + 1}{i - j}}\]

Parameters:

i (float or array-like) – Moment index i
j (float or array-like) – Moment index j
Mi (float or array-like) – Moment parameter Mi (Γ_i)
Mj (float or array-like) – Moment parameter Mj (Γ_j)

Returns:

The normalized intercept parameter N_c with units m-3 mm-1.

Return type:

float or array-like

static formula(D, i, j, Nc, Dc, c, mu)[source][source]#

Calculates the Normalized Generalized Gamma PSD N(D) values.

N_c and D_c are computed internally from the parameters.

Parameters:

D (array-like) – Particle diameter
i (float) – Moment index i
j (float) – Moment index j
Nc (float) – General characteristic intercept (mm-1 m-3)
Dc (float) – General characteristic diameter (mm)
c (float) – Shape parameter c
mu (float) – Shape parameter μ

Returns:

PSD values

Return type:

array-like

static from_parameters(parameters)[source][source]#

Initialize NormalizedGeneralizedGammaPSD from a dictionary or xarray.Dataset.

Parameters:: parameters (dict or xarray.Dataset) – Parameters to initialize the class. Must contain ‘i’, ‘j’, ‘Nc’, ‘Dc’, ‘c’, and ‘mu’. The moment indices ‘i’ and ‘j’ can also be provided in the ‘disdrodb_psd_model_kwargs’ attribute if parameters is an xarray.Dataset.
Returns:: An instance of NormalizedGeneralizedGammaPSD initialized with the parameters.
Return type:: NormalizedGeneralizedGammaPSD

property name[source]#: Return the PSD name.

static normalized_formula(x, i, j, c, mu)[source][source]#

Calculates N(D)/Nc from x=D/Dc.

This formula is useful to fit a single normalized PSD shape to data in the double normalization framework.

Parameters:

x (array-like) – Normalized particle diameter: x = D/Dc
i (float) – Moment index i
j (float) – Moment index j
c (float) – Shape parameter c
mu (float) – Shape parameter μ

Returns:

N(D)/Nc values

Return type:

array-like

parameters_summary()[source][source]#: Return a string with the parameter summary.

static required_parameters()[source][source]#

Return the required parameters of the PSD.

Returns:: List of required parameter names.
Return type:: list of str

disdrodb.psd.available_psd_models()[source][source]#

Return a list of available PSD models.

Returns:: List of available PSD model names.
Return type:: list of str

disdrodb.psd.create_psd(psd_model, parameters)[source][source]#

Create a PSD instance from model name and parameters.

Parameters:

psd_model (str) – Name of the PSD model.
parameters (dict or xarray.Dataset) – Dictionary or Dataset containing the PSD parameters.

Returns:

An instance of the specified PSD model initialized with the given parameters.

Return type:

XarrayPSD

disdrodb.psd.estimate_model_parameters(ds, psd_model, optimization, optimization_settings=None)[source][source]#

Estimate particle size distribution model parameters.

This is the main interface function for fitting PSD models to observed data. It supports three optimization methods: Maximum Likelihood (ML), Method of Moments (MOM), and Grid Search (GS).

Parameters:

ds (xarray.Dataset) –
Input dataset containing PSD observations. Must include:
- drop_number_concentration : Drop number concentration [m⁻³ mm⁻¹]
- diameter_bin_center : Diameter bin centers [mm]
- diameter_bin_width : Diameter bin widths [mm]
Additional variables required for specific optimization methods:
- For ML: diameter_bin_lower, diameter_bin_upper
- For GS with target=’R’: fall_velocity (auto-computed if missing)
- For MOM: Moment variables M0, M1, …, M6 (depending on method)
psd_model (str) –
Name of the PSD model to fit. Valid options:
- "GammaPSD" : Gamma distribution
- "NormalizedGammaPSD" : Normalized gamma distribution
- "LognormalPSD" : Lognormal distribution
- "ExponentialPSD" : Exponential distribution
Use available_optimization(psd_model) to check which optimization methods are available for a given model.
optimization (str) –
Optimization method to use. Valid options:
- "ML" : Maximum Likelihood estimation
- "MOM" : Method of Moments
- "GS" : Grid Search
optimization_settings –
Dictionary of keyword arguments specific to the chosen optimization method.

For optimization="ML":
- init_method : str or list, Method(s) of moments for parameter initialization
- probability_method : str, Method to compute probabilities (default: ‘cdf’)
- likelihood : str, Likelihood function (‘multinomial’ or ‘poisson’, default: ‘multinomial’)
- truncated_likelihood : bool, Use truncated likelihood (default: True)
- optimizer : str, Optimization algorithm (default: ‘Nelder-Mead’)
For optimization="GS":
- fixed_parametersdict, optional
 Allows to specify PSD model parameters to fixed value(s). For example for psd_model=GammaPSD one can use fixed_parameters={“mu”: 3} For psd_model=NormalizedGeneralizedGammaPSD, it’s mandatory to specify i and j moment order with: fixed_parameters={“i”: 3, “j”: 4}
- objectives: dict, optional
 List of optimization objectives. If None (default), use DEFAULT_OBJECTIVES. Each objective dict must contain:
 "target"str
 Target quantity to optimize. Valid options: - "N(D)" : Drop number concentration [m⁻³ mm⁻¹] - "H(x)" : Normalized drop number concentration [-]. Only for Normalized PSD models. - "R" : Rain rate [mm h⁻¹] - "Z" : Radar reflectivity [mm⁶ m⁻³] - "LWC" : Liquid water content [g m⁻³] - "M" : Moment of order p
 
 "transformation"str
 Transformation applied before computing the error. Valid options: - "identity" : No transformation - "log" : Logarithmic transformation - "sqrt" : Square root transformation
 
 "censoring"str
 Censoring applied to observed PSD. Valid options: - "none" : No censoring applied - "left" : Left-censored (remove leading zero bins) - "right" : Right-censored (remove trailing zero bins) - "both" : Both sides censored
 
 "loss"str
 Error metric. For "N(D)" and "H(x)" valid options are "SSE", "SAE", "MAE", "MSE", "RMSE", "relMAE" "KLDiv", "JSD", "WD", "KS". For "R", "Z", "LWC", and "M" valid options are "AE", "SE".
 
 "loss_weight"float, optional
 Weight for this objective in the combined loss (default: 1.0 for single objective). When multiple objectives are provided, weights are normalized to sum to 1.0.

Returns:

ds_params – Dataset containing the estimated PSD model parameters with attributes. Variables depend on the selected psd_model:

GammaPSD : N0, mu, Lambda
NormalizedGammaPSD : Nw, mu, Dm
LognormalPSD : Nt, mu, sigma
ExponentialPSD : N0, Lambda

Each parameter variable includes attributes with parameter name, units, and optimization metadata.

Dataset attributes include:

disdrodb_psd_model : The fitted PSD model name
disdrodb_psd_optimization : The optimization method used
disdrodb_psd_optimization_settings : String representation of kwargs

Return type:

xarray.Dataset

disdrodb.psd package

Contents

disdrodb.psd package#

Submodules#

disdrodb.psd.fitting module#

disdrodb.psd.gof_metrics module#

disdrodb.psd.grid_search module#

disdrodb.psd.models module#

Module contents#