torchref.base.metrics package

Metrics and loss functions for crystallographic refinement.

This submodule provides functions for: - R-factor calculations - Negative log-likelihood loss functions - Statistical metrics

torchref.base.metrics.get_rfactor_torch(F_obs, F_calc)

Calculate R-factor between observed and calculated structure factors (PyTorch version).

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factor amplitudes.

Returns:

R-factor value.

Return type:

torch.Tensor

torchref.base.metrics.get_rfactor(F_obs, F_calc)

Calculate the R-factor between observed and calculated structure factors (NumPy version).

The R-factor is a measure of agreement between observed and calculated structure factor amplitudes, defined as sum(|F_obs - F_calc|) / sum(F_obs).

Parameters:

• F_obs (numpy.ndarray) – Observed structure factor amplitudes.

• F_calc (numpy.ndarray) – Calculated structure factor amplitudes.

Returns:

R-factor value between 0 and 1.

Return type:

float

torchref.base.metrics.rfactor(F_obs, F_calc)

Calculate R-factor between observed and calculated structure factors.

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes of shape (N,).

• F_calc (torch.Tensor) – Calculated structure factor amplitudes of shape (N,).

Returns:

R-factor value.

Return type:

float

torchref.base.metrics.get_rfactors(F_obs, F_calc, rfree)

Get R-factors for working and test sets.

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes of shape (N,).

• F_calc (torch.Tensor) – Calculated structure factor amplitudes of shape (N,).

• rfree (torch.Tensor) – Boolean mask indicating R-free reflections of shape (N,). 1 is Working set, 0 is Test set.

Returns:

(r_work, r_test) where r_work is the R-factor for the working set and r_test is the R-factor for the test set.

Return type:

tuple

torchref.base.metrics.bin_wise_rfactors(F_obs, F_calc, rfree, bins)

Calculate bin-wise R-factors between observed and calculated structure factors.

Parameters:

• F_obs (torch.Tensor) – Observed structure factors.

• F_calc (torch.Tensor) – Calculated structure factors.

• rfree (torch.Tensor) – R-free mask.

• bins (torch.Tensor) – Bin indices for each reflection.

Returns:

• r_work_bins (torch.Tensor) – R-factors for working set (per bin).

• r_test_bins (torch.Tensor) – R-factors for test set (per bin).

Return type:

tuple

torchref.base.metrics.calc_outliers(F_obs, F_calc, z)

Identify outlier reflections based on deviation from expected values (PyTorch version).

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factor amplitudes.

• z (float) – Number of standard deviations for outlier threshold.

Returns:

Boolean mask where True indicates outlier reflections.

Return type:

torch.Tensor

torchref.base.metrics.calc_outliers_numpy(F_obs, F_calc, z)

Identify outlier reflections based on structure factor differences (NumPy version).

Detects reflections where the normalized difference between observed and calculated structure factors exceeds z standard deviations.

Parameters:

• F_obs (numpy.ndarray) – Observed structure factor amplitudes.

• F_calc (numpy.ndarray) – Calculated structure factor amplitudes.

• z (float) – Number of standard deviations for outlier threshold.

Returns:

Boolean array where True indicates an outlier reflection.

Return type:

numpy.ndarray

torchref.base.metrics.nll_xray(F_obs, F_calc, sigma_F_obs)

Compute X-ray negative log-likelihood assuming Gaussian distribution.

Parameters:

• F_obs (torch.Tensor or MaskedTensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factors (complex).

• sigma_F_obs (torch.Tensor or MaskedTensor) – Standard deviations of observed amplitudes.

Returns:

Mean negative log-likelihood.

Return type:

torch.Tensor

torchref.base.metrics.nll_xray_sum(F_obs, F_calc, sigma_F_obs)

Compute summed X-ray negative log-likelihood assuming Gaussian distribution.

Parameters:

• F_obs (torch.Tensor or MaskedTensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factors (complex).

• sigma_F_obs (torch.Tensor or MaskedTensor) – Standard deviations of observed amplitudes.

Returns:

Sum of negative log-likelihood values.

Return type:

torch.Tensor

torchref.base.metrics.nll_xray_lognormal(F_obs, F_calc, sigma_F_obs, eps=1e-10)

Compute X-ray negative log-likelihood assuming lognormal distribution.

This is a more realistic model for structure factor amplitudes, which must be positive. For a lognormal distribution LogNormal(mu, sigma^2), the NLL is: NLL = 0.5*(log(x) - mu)^2/sigma^2 + log(x) + log(sigma) + 0.5*log(2*pi)

Where mu and sigma are derived from F_obs and sigma_F_obs using: - sigma = sqrt(log(1 + (sigma_F/F)^2)) - mu = log(F) - sigma^2/2

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factors (complex).

• sigma_F_obs (torch.Tensor) – Standard deviations of observed amplitudes.

• eps (float, optional) – Small value to avoid numerical issues. Default is 1e-10.

Returns:

Mean negative log-likelihood.

Return type:

torch.Tensor

torchref.base.metrics.log_loss(F_obs, F_calc, sigma_F_obs)

Compute log-space loss between observed and calculated structure factors.

Parameters:

• F_obs (torch.Tensor) – Observed structure factor amplitudes.

• F_calc (torch.Tensor) – Calculated structure factors (complex).

• sigma_F_obs (torch.Tensor) – Standard deviations of observed amplitudes (unused).

Returns:

Mean absolute difference in log space.

Return type:

torch.Tensor

torchref.base.metrics.estimate_sigma_I(I)

Estimate standard deviation of intensities.

Separates positive and negative values for robust estimation.

Parameters:

I (torch.Tensor) – Intensity values.

Returns:

Estimated standard deviations.

Return type:

torch.Tensor

torchref.base.metrics.estimate_sigma_F(F)

Estimate standard deviation of structure factor amplitudes.

Parameters:

F (torch.Tensor) – Structure factor amplitudes.

Returns:

Estimated standard deviations.

Return type:

torch.Tensor

torchref.base.metrics.gaussian_to_lognormal_sigma(F, sigma_F, eps=1e-10)

Approximate the sigma parameter of a lognormal distribution from Gaussian statistics.

If we assume F comes from a lognormal distribution X ~ LogNormal(mu, sigma^2), then: - Mean: E[X] = F - Std: sqrt(Var[X]) = sigma_F

For lognormal distribution: - E[X] = exp(mu + sigma^2/2) - Var(X) = exp(2*mu + sigma^2)(exp(sigma^2) - 1)

We can derive: - CV^2 = Var[X]/E[X]^2 = exp(sigma^2) - 1 - sigma = sqrt(log(1 + CV^2))

where CV = sigma_F/F is the coefficient of variation.

Parameters:

• F (torch.Tensor) – Structure factor amplitudes (mean of the distribution).

• sigma_F (torch.Tensor) – Standard deviations.

• eps (float, optional) – Small value to avoid division by zero. Default is 1e-10.

Returns:

Sigma parameter for lognormal distribution.

Return type:

torch.Tensor

torchref.base.metrics.gaussian_to_lognormal_mu(F, sigma_lognormal, eps=1e-10)

Calculate the mu parameter of a lognormal distribution given F and sigma.

For lognormal distribution X ~ LogNormal(mu, sigma^2): - E[X] = exp(mu + sigma^2/2)

Solving for mu: - mu = log(E[X]) - sigma^2/2

Parameters:

• F (torch.Tensor) – Structure factor amplitudes (mean of the distribution).

• sigma_lognormal (torch.Tensor) – Sigma parameter from lognormal distribution.

• eps (float, optional) – Small value to avoid log of zero. Default is 1e-10.

Returns:

Mu parameter for lognormal distribution.

Return type:

torch.Tensor

Submodules

• torchref.base.metrics.loss module
  • nll_xray()
  • nll_xray_sum()
  • nll_xray_lognormal()
  • log_loss()
  • estimate_sigma_I()
  • estimate_sigma_F()
  • gaussian_to_lognormal_sigma()
  • gaussian_to_lognormal_mu()
• torchref.base.metrics.rfactor module
  • get_rfactor_torch()
  • get_rfactor()
  • rfactor()
  • get_rfactors()
  • bin_wise_rfactors()
  • calc_outliers()
  • calc_outliers_numpy()