GUIBRUSHR.core.functions.io_utils module

I/O utility functions for GUIBRUSHR atmospheric retrieval.

This module contains functions for file I/O and data access extracted from general_functions.py:

  • make_pyratbay_config: Create a pyratbay configuration file.

  • create_fits: Create and save a FITS file.

  • create_path_night: Construct observation data file path.

  • get_csv_value: Retrieve value from a DataFrame.

  • get_condensed_line_list: Retrieve condensed molecule info from pRT.

  • get_line_lists: Retrieve line lists from molecular opacity data.

  • read_fits: Read FITS file with optional slicing.

  • get_depth_filename: Return depth FITS filename by mode.

  • read_depth_fits: Read depth FITS with legacy fallback.

  • get_stellar_model: Load stellar spectrum from pickle.

  • generate_star_model_hr: Generate stellar model with convolution.

  • download_star_spectrum: Download PHOENIX stellar spectrum.

GUIBRUSHR.core.functions.io_utils.make_pyratbay_config(output_folder: str, target: Any, pressure: Any, species: Any, wavelength: Any, resolution: Any, params) → str[source]

Create a pyratbay configuration file based on guibrush configuration.

Parameters:

  • output_folder (str) – Folder where to store the outputs.

  • target – Target object containing stellar and planetary parameters.

  • pressure – Pressure configuration object.

  • species – Species configuration object.

  • wavelength – Wavelength configuration object.

  • resolution – Resolution configuration object.

  • params – List of input parameters.

Returns:

Path to the created configuration file.

Return type:

str

GUIBRUSHR.core.functions.io_utils.create_fits(data: ndarray, pathf: str | Path) → None[source]

Create and save a FITS file from the provided data.

This function creates a primary HDU (Header/Data Unit) using the input data, encapsulates it in an HDUList, and writes the FITS file to the specified path. If a file with the same name exists, it will be overwritten.

Parameters:

  • data (np.ndarray) – The data array to be stored in the FITS file.

  • pathf (Union[str, Path]) – The destination file path for the FITS file.

GUIBRUSHR.core.functions.io_utils.create_path_night(pathfolder: str | Path, target: str, rad_mode: str, instrument: str) → str[source]

Construct and return the file path for a specific night’s observation data.

The path is built by concatenating the following components:

  • pathfolder: The base directory containing observation data.

  • target: The target object or observation name.

  • A constant subdirectory defined by ConstantVariables.HR_INSTRUMENTS, representing high-resolution instruments.

  • rad_mode: The radiative mode, which specifies the type of observation.

    This can be either ‘emission’ or ‘transmission’.

  • instrument: The instrument identifier.

Parameters:

  • pathfolder (Union[str, Path]) – The base directory path.

  • target (str) – The target object or observation name.

  • rad_mode (str) – The radiative mode; valid options are ‘emission’ or ‘transmission’.

  • instrument (str) – The instrument identifier.

Returns:

The fully constructed file path as a string.

Return type:

str

GUIBRUSHR.core.functions.io_utils.get_csv_value(df, search_value: Any, search_column: str = 'Variable', target_column: str = 'Value') → Any | None[source]

Retrieve a value from a general-info container by key.

This helper accepts three input shapes (the legacy DataFrame mode is preserved so the 100+ existing call sites keep working without edits):

  1. pd.DataFrame with a 2-column Variable/Value legacy shape. The search_column/target_column arguments override the defaults.

  2. dict (typed general-info, as returned by GUIBRUSHR.core.io.retrieval_io.read_general_info()). Equivalent to data.get(search_value). search_column/target_column are ignored.

  3. str or pathlib.Path pointing to a retrieval folder. The function calls read_general_info() internally and looks up the key. search_column/target_column are ignored.

Parameters:

  • df – Container to query. DataFrame, dict, str, or Path.

  • search_value (Any) – The key (or value in search_column) to look up.

  • search_column (str, optional) – Only used in DataFrame mode. Defaults to “Variable”.

  • target_column (str, optional) – Only used in DataFrame mode. Defaults to “Value”.

Returns:

The matching value (typed when input is dict/folder; raw cell when input is DataFrame), or None if no match is found.

Return type:

Optional[Any]

GUIBRUSHR.core.functions.io_utils.get_condensed_line_list()[source]

Retrieve condensed molecule information from petitRADTRANS opacity data.

This function scans the condensed molecule opacity files in the petitRADTRANS installation and extracts information about available condensed species including their chemical formulas, names, masses, and visualization names.

Returns:

A tuple containing:

  • np.ndarray: Array of condensed molecule chemical formulas

  • np.ndarray: Array of condensed molecule file names

  • np.ndarray: Array of calculated molecular masses (in u)

  • np.ndarray: Array of visualization names for display

Return type:

tuple

Note

If no condensed molecules are found, returns arrays with [“None”] and mass [-999] as placeholders.

GUIBRUSHR.core.functions.io_utils.get_line_lists()[source]

Retrieve line lists, isotopes, opacity_line_list identifiers, and compute isotopic masses from molecular opacity data used by petitRADTRANS.

This function performs the following steps:

  1. Reads the periodic table data from a CSV file to obtain numbers of protons and neutrons for each element.

  2. Scans the ‘line_by_line’ directory (within the opacities folder) for molecule directories.

  3. For each molecule, lists its available isotopes (each isotope is represented by a directory).

  4. Parses each isotope’s name (which encodes its elemental composition) to determine the elemental symbols and their corresponding mass numbers, compute the total mass of the isotope using predefined atomic masses (proton: 1.007276 u, neutron: 1.008665 u, electron: 0.000548579909 u), and adjust the electron count based on the number of ‘+’ symbols.

  5. For each isotope, retrieves the available opacity_line_list file names (by removing the “.xsec.petitRADTRANS.h5” suffix).

Returns:

A tuple containing:

  • np.ndarray: Sorted array of molecule names.

  • dict: Dictionary mapping each molecule to an array of its isotope names.

  • dict: Dictionary mapping each isotope to an array of HR opacity_line_list identifiers.

  • dict: Dictionary mapping each isotope to an array of LR opacity_line_list identifiers.

  • dict: Dictionary mapping each isotope to its computed total mass (in atomic mass units).

Return type:

tuple

GUIBRUSHR.core.functions.io_utils.read_fits(path_fits: str | Path, transpose: bool = False, intransit: ndarray | None = None) → ndarray[source]

Read data from a FITS file and optionally apply slicing and transposition.

Parameters:

  • path_fits (Union[str, Path]) – Path to the FITS file

  • transpose (bool, optional) – Whether to transpose the data array. Defaults to False.

  • intransit (Optional[np.ndarray], optional) – Indices to slice the data along the second axis. If provided, data is sliced as data[:, intransit, :]. Defaults to None.

Returns:

The processed data array from the FITS file

Return type:

np.ndarray

GUIBRUSHR.core.functions.io_utils.get_depth_filename(rad_mode: str) → str[source]

Return the depth FITS filename based on the radiative transfer mode.

GUIBRUSHR.core.functions.io_utils.read_depth_fits(folder: str | Path, rad_mode: str, **kwargs) → ndarray[source]

Read the depth FITS file with fallback to legacy transit_depth.fits.

GUIBRUSHR.core.functions.io_utils.get_stellar_model(path_pkl, min_wl_cm, max_wl_cm)[source]

Load a stellar spectrum from a pickle file and optionally trim to a wavelength range (cm).

GUIBRUSHR.core.functions.io_utils.generate_star_model_hr(path_pkl, pixel_dv, min_wl=None, max_wl=None)[source]

Generate a stellar spectrum model from a pickled file.

This function loads a stellar spectrum from a pickle file, convolves it with the instrumental resolution, and creates a spline interpolation model.

Parameters:

  • path_pkl (str or Path) – Path to the pickle file containing stellar spectrum data

  • pixel_dv (float) – Pixel velocity width for resolution calculation

  • min_wl (float) – Minimum wavelength for interpolation model in cm

  • max_wl (float) – Maximum wavelength for interpolation model in cm

Returns:

Spline representation of the stellar spectrum model

Return type:

tuple

GUIBRUSHR.core.functions.io_utils.download_star_spectrum(figure_tk, target_obj, folder_stellar_spc)[source]

Download and save a PHOENIX stellar spectrum if not already present.

Parameters:

  • figure_tk – Parent Tkinter widget for the stellar parameter dialog.

  • target_obj – Target object with stellar_effective_temperature attribute.

  • folder_stellar_spc (str) – Directory for storing the stellar spectrum file.

Returns:

Path to the stellar spectrum pickle file, or None if cancelled.

Return type:

str or None