GUIBRUSHR.core.functions.statistics module

Statistics utility functions for GUIBRUSHR atmospheric retrieval.

This module contains functions for statistical analysis extracted from general_functions.py:

  • get_medians: Extract and process parameter statistics from MCMC chains.

  • pre_plot: Prepare posterior chain statistics and labels for plotting.

  • linear_solver: Solve a linear system using SVD.

  • get_keys_by_value: Find the first key in a dict whose value contains a target.

  • compute_transit_durations: Compute transit durations T14, T23, T12.

GUIBRUSHR.core.functions.statistics.get_medians(folder_retrieval_final: str | Path, arr_values, remove_chain: bool, corner_plot_or_simulation: bool, best_fit_method: str, n_samples: int = 500) → BestFitParametersAndResults[source]

Extract and process parameter statistics from MCMC chains.

This function processes MCMC chain data to compute median values and other statistics for fitted parameters. It handles chain rejection based on log-likelihood criteria and performs burn-in removal.

Parameters:

  • folder_retrieval_final (Union[str, Path]) – Path to the final retrieval folder

  • arr_values – Array containing parameter information

  • remove_chain (bool) – Whether to remove chains based on log-likelihood criteria

  • corner_plot_or_simulation (bool) – Whether to process data for corner plots

  • best_fit_method – Method used to extract best fit parameters

  • n_samples – Number of samples to use for random model extraction

Returns:

Object containing processed parameter statistics

Return type:

BestFitParametersAndResults

GUIBRUSHR.core.functions.statistics.pre_plot(folder_retrieval_final: str | ~pathlib.Path, arr_values: ~numpy.ndarray, remove_chain: [<class 'bool'>, <class 'int'>], corner_plot: [<class 'bool'>, <class 'int'>], best_fit_method: str)[source]

Prepare posterior chain statistics and parameter labels for plotting.

Parameters:

  • folder_retrieval_final (Union[str, Path]) – Path to the final retrieval folder

  • arr_values (np.ndarray) – Array containing parameter information

  • remove_chain (bool) – Whether to remove chains based on log-likelihood criteria

  • corner_plot (bool) – Whether to process data for corner plots

  • best_fit_method (str) – Method used to extract best fit parameters

Returns:

  • int: Number of bad chains

  • float: AIC value

  • float: Last maximum likelihood

  • float: Current maximum likelihood

  • np.ndarray: Flattened log-likelihood values # IDL: chi2

  • List[str]: Best-fit parameter names

  • np.ndarray: Post-burn-in chain parameters (arr1)

  • np.ndarray: Parameter medians

  • List[float]: Fixed parameter values

  • List[str]: Fixed parameter names

  • str: Summary string

  • str: Parameter names string

  • List[str]: Parameter labels

  • np.ndarray: Parameter errors

  • int: Burn-in index (burnndx)

  • int: Number of good chains

  • np.ndarray: Full chain including burn-in, shape (nfit, nsteps_total, nchains)

Return type:

Tuple containing

GUIBRUSHR.core.functions.statistics.linear_solver(topca_l: ndarray, res_l: ndarray)[source]

Solve a linear system using Singular Value Decomposition (SVD).

This function solves the linear system Ax = b using SVD decomposition, where A is the design matrix (res_l) and b is the target vector (topca_l). The solution is computed in a numerically stable way using SVD.

Parameters:

  • topca_l (np.ndarray) – Target vector b in the system Ax = b

  • res_l (np.ndarray) – Design matrix A in the system Ax = b

Returns:

The reconstructed array after solving the linear system Error: Whether the linear system was solved successfully

Return type:

Results

GUIBRUSHR.core.functions.statistics.get_keys_by_value(dictionary: Dict[str, Any], target_value: Any) → str | None[source]

Find the first key in a dictionary whose value contains the target value.

This function searches through the dictionary values to find the first key whose value contains the target value. It’s useful for reverse lookups in dictionaries where values are collections.

Parameters:

  • dictionary (Dict[str, Any]) – Dictionary to search through

  • target_value (Any) – Value to search for in the dictionary values

Returns:

The first key whose value contains target_value,

or None if no match is found

Return type:

Optional[str]

GUIBRUSHR.core.functions.statistics.compute_transit_durations(period, a_Rs, k, inc_deg, ecc=0.0, omega_planet=1.5707963267948966)[source]

Compute transit durations T14, T23, T12 (=T34) for circular and eccentric orbits.

Parameters:

  • period (float) – Orbital period in days.

  • a_Rs (float) – Semi-major axis in units of stellar radii (a / R_star).

  • k (float) – Planet-to-star radius ratio (Rp / Rs).

  • inc_deg (float) – Orbital inclination in degrees.

  • ecc (float, optional) – Orbital eccentricity (default 0 for circular).

  • omega_planet (float, optional) – Argument of periastron of the PLANET in radians (default pi/2). The Winn (2010) transit formulae use the STAR’s argument of periastron, so this value is converted internally to the stellar one (omega_star = omega_planet - pi).

Returns:

‘T14’, ‘T23’, ‘T12’ : durations in days ‘T14_hours’, ‘T23_hours’, ‘T12_hours’ : durations in hours ‘b’ : impact parameter ‘ecc_factor’ : eccentricity correction factor (1.0 if circular) ‘grazing’ : True if grazing transit (T23 = 0) ‘limph_T14’, ‘limph_T12’ : phase limits = T / (2*P)

Return type:

dict with keys

References

Winn (2010), “Transits and Occultations”, arXiv:1001.2010, Eq. 14-16. Kipping (2010), MNRAS 407, 301, arXiv:1004.3819.