Data Module (`brutus.data`)¶

brutus.data downloads, verifies, and loads the external model grids, MIST evolutionary tracks, isochrones, neural network weights, 3D dust maps, and photometric calibration offsets used by brutus.

Data Dependencies:

Installation lists every external data file with its download size and corresponding fetch_* function.

Storage and Lookup Order:

No file downloads automatically on import or class instantiation. Each fetch_* function downloads its file via pooch into the brutus cache directory (~/.cache/astro-brutus/ by default, or $ASTRO_BRUTUS_DATA_DIR when set), verifies its SHA-256 checksum, and creates a symbolic link (or copy) in target_dir (the current working directory by default). Loaders that resolve a default filename (find_nn_file, EEPTracks, and Isochrone) check the brutus cache directory first and data/DATAFILES in the repository second, raising FileNotFoundError with the required fetch_* command when the file is absent.

Typical Usage:

First-time setup (download data files):

from brutus.data import fetch_grids, fetch_isos, fetch_dustmaps

# Download the default MIST v9 model grid (all 49 supported filters)
fetch_grids()

# Download MIST v1.2 isochrones
fetch_isos()

# Download the Bayestar19 3D dust map
fetch_dustmaps(dustmap="bayestar19")

Loading data for fitting:

from brutus.data import load_models
from brutus.core import StarGrid

# Load pre-computed grid (third return is the ancillary-label mask)
models, labels, label_mask = load_models('grid_mist_v9.h5')
grid = StarGrid(models, labels)

# Grid is now ready for use with BruteForce fitter

Custom data locations:

# Load grid from custom path
models, labels, label_mask = load_models('/path/to/my_custom_grid.h5')

Data File Formats:

Grids: HDF5 with datasets for models, labels, reddening coefficients
Isochrones: HDF5 with structured arrays
Dust Maps: HDF5 files on a HEALPix pixelization (pixel lookups via healpy)
Neural Networks: HDF5 files with layer weights

See Also:

Installation - Setting up data files
Model grids - Creating custom grids
Quickstart - Basic data loading examples

Data Downloading¶

brutus.data.fetch_grids(grid='mist_v9', *, target_dir='.')[source]¶

Download pre-computed stellar model grids to the target directory.

Parameters:

grid (str, optional) –
The desired grid file. Available options:
- ’mist_v9’ (default) : MIST v1.2 with empirical corrections (v9)
- ’mist_v8’ : MIST v1.2 with empirical corrections (v8)
- ’bayestar_v5’ : Bayestar models (v5)
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded stellar model grid file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_grids
>>> grid_path = fetch_grids(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded model grid to: {grid_path}")

>>> # Download older version
>>> old_grid = fetch_grids('mist_v8', target_dir='./data/DATAFILES/')

brutus.data.fetch_isos(iso='MIST_1.2_vvcrit0.0', *, target_dir='.')[source]¶

Download isochrone files to target directory.

Parameters:

iso (str, optional) –
The desired isochrone file. Available options:
- ’MIST_1.2_vvcrit0.0’ (default) : Non-rotating MIST v1.2 isochrones
- ’MIST_1.2_vvcrit0.4’ : Rotating MIST v1.2 isochrones
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded isochrone file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_isos
>>> iso_path = fetch_isos(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded isochrones to: {iso_path}")

>>> # Download rotating models
>>> rotating_path = fetch_isos('MIST_1.2_vvcrit0.4', target_dir='./data/DATAFILES/')

brutus.data.fetch_tracks(track='MIST_1.2_vvcrit0.0', *, target_dir='.')[source]¶

Download EEP (Equivalent Evolutionary Point) track files to target directory.

Parameters:

track (str, optional) –
The desired track file. Available options:
- ’MIST_1.2_vvcrit0.0’ (default) : Non-rotating MIST v1.2 tracks
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded evolutionary track file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_tracks
>>> track_path = fetch_tracks(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded tracks to: {track_path}")

brutus.data.fetch_dustmaps(dustmap='bayestar19', *, target_dir='.')[source]¶

Download 3D dust extinction map files to target directory.

Parameters:

dustmap (str, optional) –
The desired dust map file. Available options:
- ’bayestar19’ (default) : Bayestar dust map from Green et al. (2019)
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded dust map file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_dustmaps
>>> dust_path = fetch_dustmaps(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded dust map to: {dust_path}")

brutus.data.fetch_offsets(grid='mist_v9', *, target_dir='.')[source]¶

Download empirical photometric offset files to the target directory.

Parameters:

grid (str, optional) –
The associated model grid for the offsets. Available options:
- ’mist_v9’ (default) : Offsets for MIST v1.2 with corrections (v9)
- ’mist_v8’ : Offsets for MIST v1.2 with corrections (v8)
- ’bayestar_v5’ : Offsets for Bayestar models (v5)
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded photometric offset file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_offsets
>>> offset_path = fetch_offsets(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded offsets to: {offset_path}")

brutus.data.fetch_nns(model='c3k', *, target_dir='.')[source]¶

Download pre-trained neural network model files (used for fast spectral energy distribution prediction) to target directory.

Parameters:

model (str, optional) –
The desired neural network model file. Available options:
- ’c3k’ (default) : Network trained on C3K spectral models
target_dir (str, optional) – Keyword-only. The directory that gets a link to the downloaded file, or a copy where the file system has no links. The file itself is stored in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set). Default is “.”.

Returns:

file_path – Path to the downloaded neural network file.

Return type:

pathlib.Path

Raises:

ValueError – If the option is not one of those listed.

Examples

>>> from brutus.data import fetch_nns
>>> nn_path = fetch_nns(target_dir='./data/DATAFILES/')
>>> print(f"Downloaded neural network to: {nn_path}")

Data Loading¶

brutus.data.load_models(filepath, filters=None, labels=None, include_ms=True, include_postms=True, include_binaries=False, verbose=True)[source]¶

Load pre-computed stellar model grids and reddening coefficients.

Parameters:

filepath (str) – The filepath of the stellar model file (typically .h5 format).
filters (iterable of str with length Nfilt, optional) – List of filters that will be loaded. If not provided, will default to all available filters. See the internally-defined FILTERS variable for more details on filter names. Any filters that are not available will be skipped over (a UserWarning listing the skipped names and the surviving column order is emitted).
labels (iterable of str with length Nlabel, optional) – List of labels associated with the set of imported stellar models. Labels that are not in the file are skipped, with a UserWarning that lists them; the default set skips its absent labels silently. The default set is [‘mini’, ‘feh’, ‘eep’, ‘smf’, ‘afe’, ‘loga’, ‘logl’, ‘logt’, ‘logg’, ‘Mr’, ‘agewt’].
include_ms (bool, optional) – Whether to include objects on the Main Sequence (eep <= 454). The cut reads the file’s ‘eep’ column whatever labels holds. Default is True.
include_postms (bool, optional) – Whether to include objects evolved off the Main Sequence (eep > 454). The cut reads the file’s ‘eep’ column whatever labels holds. Default is True.
include_binaries (bool, optional) – Whether to include unresolved binaries. If False, only models with secondary mass fraction smf == 0 are kept, read from the file’s ‘smf’ column whatever labels holds. A file without an ‘smf’ column is taken to hold no binaries. Default is False.
verbose (bool, optional) – Whether to print progress messages. Default is True.

Returns:

models (~numpy.ndarray of shape (Nmodel, Nfilt, Ncoef)) – Array of models comprised of coefficients in each band used to describe the photometry as a function of reddening, parameterized in terms of A_V. Each model contains coefficients for: - Unreddened magnitude - Reddening vector for R_V = 0 - Change in reddening vector as function of R_V
labels (structured ~numpy.ndarray with dimensions (Nmodel, Nlabel)) – A structured array with the labels corresponding to each model. Contains stellar parameters like initial mass, metallicity, age, etc.
label_mask (structured ~numpy.ndarray with dimensions (1, Nlabel)) – A structured array that masks ancillary labels associated with predictions (rather than those used to compute the model grid).

Raises:

ValueError – If include_ms and include_postms are both False, if include_ms or include_postms is False and the file has no 'eep' column, or if none of the requested filters exist in filepath.

Notes

Models with non-finite photometric coefficients (invalid grid points written by older GridGenerator versions) are dropped so the returned grid is always safe to fit with BruteForce.

The label_mask return value is a boolean structured array that is True for the labels used to generate the grid and False for those predicted from them. For example, luminosity is predicted from mass, age and metallicity, so the mask is False for luminosity. StarGrid and BruteForce do not read the mask; they identify the grid inputs by name.

Examples

Basic usage with default settings:

>>> from brutus.data import load_models, fetch_grids
>>> fetch_grids()  # Download data (first time only)
>>> models, labels, label_mask = load_models('grid_mist_v9.h5')
>>> print(f"Loaded {len(labels)} stellar models")
>>> print(f"Available labels: {labels.dtype.names}")

Loading specific filters only:

>>> models, labels, mask = load_models(
...     'grid_mist_v9.h5',
...     filters=['PS_g', 'PS_r', 'PS_i', 'PS_z', 'PS_y']
... )

Loading only main sequence stars:

>>> models, labels, mask = load_models(
...     'grid_mist_v9.h5',
...     include_ms=True,
...     include_postms=False
... )

Using with StarGrid for fitting:

>>> from brutus.core import StarGrid
>>> from brutus.analysis import BruteForce
>>> models, labels, mask = load_models('grid_mist_v9.h5')
>>> grid = StarGrid(models, labels)
>>> fitter = BruteForce(grid)

brutus.data.load_offsets(filepath, filters=None, verbose=True)[source]¶

Load multiplicative photometric flux offsets for a set of filters.

Parameters:

filepath (str) – The filepath of the photometric offsets file (typically .txt format).
filters (iterable of str with length Nfilt, optional) – List of filters that will be loaded. If not provided, will default to all available filters. See the internally-defined FILTERS variable for more details on filter names. A filter that is not in the file gets an offset of 1.0, with a UserWarning when the name is not in FILTERS either.
verbose (bool, optional) – Whether to print a summary of the offsets. Default is True.

Returns:

offsets – Array of constants that will be multiplied to the data to account for offsets (i.e. multiplicative flux offsets). Values are typically close to 1.0, with deviations indicating systematic differences.

Return type:

~numpy.ndarray of shape (Nfilt)

Notes

The offset file should contain two columns: filter names and offset values.

Examples

>>> from brutus.data import load_offsets
>>> offsets = load_offsets('./data/DATAFILES/offsets_mist_v9.txt')
>>> print(f"Loaded offsets for {len(offsets)} filters")

>>> # Load specific filters
>>> gri_offsets = load_offsets('./data/DATAFILES/offsets_mist_v9.txt',
...                            filters=['PS_g', 'PS_r', 'PS_i'])

>>> # Check which filters have significant offsets
>>> significant = np.abs(offsets - 1.0) > 0.01
>>> print(f"Filters with >1% offsets: {np.sum(significant)}")

brutus.data.find_nn_file(possible_names=('nn_c3k.h5', 'nnMIST_BC.h5'))[source]¶

Find the neural network model file in the brutus data directories.

Searches for the neural network HDF5 file used for bolometric correction predictions in the brutus download directory (the Pooch cache, or $ASTRO_BRUTUS_DATA_DIR when set), then in data/DATAFILES in the repository.

Parameters:

possible_names (tuple of str, optional) – Filenames to search for, tried in order. Default is ("nn_c3k.h5", "nnMIST_BC.h5"). The first file found is returned.

Returns:

path – Absolute path to the neural network file.

Return type:

pathlib.Path

Raises:

FileNotFoundError – If none of the candidate files can be found in any searched location.
TypeError – If possible_names is a single string.

Data Module (brutus.data)¶

Data Downloading¶

Data Loading¶

Data Module (`brutus.data`)¶