API Reference#

isoc#

isoc - Download and process MIST/MESA and Padova/PARSEC isochrones

class isoc.Isochrone(database: Literal['padova', 'mist'], data: QTable = None)[source]#

Wrapper that stores isochrone data from either the PARSEC/Padova or MIST/MESA service as an QTable with units.

Parameters:: database (str) – Backend that produced the data: "padova" or "mist".

property columns: list#: List of column names.

property data: QTable#: Isochrone data (excluding photometry) as an QTable.

property database: str#: Backend that produced this data ("padova" or "mist").

static default_values(database: Literal['padova', 'mist']) → dict[source]#

Get the default query parameters.

Returns:: A copy of the default query parameters. The aliases key maps the parameter name expected by the web server to the generalized arg names in from_padova() or from_mist().
Return type:: dict

Query the MIST/MESA service and return an Isochrone.

Any parameters passed as None will use the MIST defaults (see Isochrone.default_values).

Parameters:

age (float, tuple of (low, high, step), list or None) – Age in years or log10(years). A single float queries one isochrone; a tuple of length 3 sets a min, max and step size to query over the corresponding age grid, and a list queries over an age grid.
metallicity (float or None) – [Fe/H] metallicity value.
abundance (float or None) – [alpha/Fe] abundance ratio.
v_div_vcrit (float or None) – Initial rotation velocity v/v_crit.
photometry (str or None) – The name of a photometric system to retrieve synthetic photometry for. If None, MIST output is set to “theory”.
extinction (float or None) – Extinction A_V to apply to photometry. Has no effect if photometry is None.
version (str or None) – MIST version to query.
from_file (str or None) – If provided, load isochrone data from a file instead of querying the MIST service.
**kwargs – Additional keyword arguments forwarded to the MIST query.

Returns:

An Isochrone object containing the queried data.

Return type:

Isochrone

Query the Padova/PARSEC service and return an Isochrone.

Any parameters passed as None will use the Padova/PARSEC defaults (see Isochrone.default_values).

Parameters:

age (tuple of (low, high, step) or float or None) – Age in years or log10(years). A single float queries one isochrone; a tuple of length 3 sets a min, max and step size to query over the corresponding age grid, and a list queries over an age grid.
metallicity (tuple of (low, high, step) or float or None) – Metallicity value. Interpreted as Z or [M/H] depending on metallicity_type.
metallicity_type (str or None) – Whether the metallicity parameter is interpreted as “Z” or “MH” ([M/H]).
photometry (str or None) – The name of a photometric system to retrieve synthetic photometry for.
from_file (str or None) – If provided, load isochrone data from a file instead of querying the Padova service.
**kwargs – Additional keyword arguments forwarded to the Padova query.

Returns:

An Isochrone object containing the queried data.

Return type:

Isochrone

get_photometry_system_title() → str | None[source]#: Look up the human-readable title for the queried photometric system.

property header: str#: Header metadata from the original isochrone file/query.

property initial_mass#: Stellar mass column [M_Sun].

property initial_metallicity#: Initial metallicity column.

property isochrone: _IsochroneIndex#

Index individual isochrones within a multi-isochrone table.

Supports integer and 'field=value' string keys. Each item is a new Isochrone containing only the rows for that individual isochrone.

Examples

>>> iso.isochrone[-1]
>>> iso.isochrone['log_age=9']          # MIST
>>> iso.isochrone['logAge=9']           # Padova
>>> iso.isochrone['[Fe/H]_init=0.015']  # MIST: initial metallicity
>>> iso.isochrone['Zini=0.015']         # Padova: initial metallicity

property log_L#: log10(L [L_Sun]) column.

property log_Teff#: log10(Teff [K]) column.

property log_age#: log10(age / [yr]) column.

property log_g#: log10(g [cm s^-2]) column.

property mass#: Stellar mass column [M_Sun].

property metallicity#: Metallicity column.

property metallicity_type#: Whether the metallicity column is "Z", "MH" ([M/H]), or "FeH" ([Fe/H]).

property n_isochrones: int#: Number of isochrones in the data.

static parameter_descriptions(database: Literal['padova', 'mist']) → dict[source]#: Get descriptions for each query parameter.

property photometry: Photometry#: Photometric magnitude columns as a Photometry object.

classmethod query_ezpadova(age_yr: tuple[float, float, float] | None = None, Z: tuple[float, float, float] | None = None, logage: tuple[float, float, float] | None = None, MH: tuple[float, float, float] | None = None, default_ranges: bool = False, **kwargs) → Isochrone[source]#: Query the Padova/PARSEC service and return an Isochrone.

property query_parameters: dict#

The resolved query parameters used to retrieve this isochrone.

Returns:: A copy of the query parameters sent to the webform.
Return type:: dict

class isoc.Photometry(isochrone: Isochrone)[source]#

Container for photometric magnitude columns.

Photometry data is stored in QTable instances, one for each photometric system queried.

Each band is accessible as a named attribute.

Parameters:: isochrone (Isochrone) – The parent Isochrone instance, used to access metadata.

add_photometry(system_names: str | list[str]) → None[source]#

Query one or more additional photometric systems and add them.

Re-uses the query parameters from the parent Isochrone, changing only the photometric system.

Parameters:: system_names (str or list[str]) – One or more photometric system identifiers (short key or long description).

property available_systems: dict#

All photometric systems available for querying.

For Padova, systems are parsed from ezpadova’s parsec.json (the photsys_file dictionary). For MIST, systems are parsed from isoc’s mist_config.json (the output dictionary).

Returns:: {system_value: description, ...}
Return type:: dict

property columns: dict[str, list]#

Column names per system.

Returns:: {system_full_name: [col1, col2, ...], ...}
Return type:: dict

property data: _PhotometryTables#

Per-system photometry tables.

Returns:: {system_full_name: QTable, ...} — also exposes .columns.
Return type:: _PhotometryTables

get_color(band1: str, band2: str) → Quantity[source]#

Compute a color index by subtracting two magnitude columns.

The resulting color column is added to the table that contains band1.

Parameters:

band1 (str) – Names of the two magnitude columns.
band2 (str) – Names of the two magnitude columns.

Returns:

color – The band1 − band2 color array.

Return type:

Quantity

property header: str#: Header metadata for each photometric system.

property systems: dict[str, str]#

Photometric systems currently loaded.

Returns:: {short_key: full_name, ...}
Return type:: dict

isoc.plot_color_magnitude(iso: Isochrone, band1: str, band2: str, mag: str | None = None, fig: Figure | None = None, ax: Axes | None = None, invert_y: bool = True, **kwargs) → tuple[Figure, Axes][source]#

Plot a color–magnitude diagram.

Uses Photometry.get_color() to compute the color band1 − band2 and plots it against a magnitude.

Parameters:

iso (Isochrone) – Isochrone with photometry.
band1 (str) – Band names passed to Photometry.get_color().
band2 (str) – Band names passed to Photometry.get_color().
mag (str, optional) – Band name for the y-axis magnitude. Defaults to band1.
fig (matplotlib Figure, optional) – Existing figure to draw on. A new axes is added to it when ax is None. Ignored if ax is provided.
ax (matplotlib Axes, optional) – Existing axes to draw on. Takes priority over fig. A new figure is created if both are None.
invert_y (bool) – If True the y-axis is inverted (brighter up).
**kwargs – Forwarded to matplotlib.pyplot.plot().

Returns:

fig, ax

Return type:

Figure, Axes

isoc.plot_isochrone(iso: Isochrone | Sequence[Isochrone], iso_labels: Sequence[str] | None = None, x: str = 'log_Teff', y: str = 'log_L', fig: Figure | None = None, ax: Axes | None = None, invert_x: bool = True, cmap: str = 'viridis', **kwargs) → tuple[Figure, Axes][source]#

Plot one or more isochrones on an HR diagram.

Parameters:

iso (Isochrone or sequence of Isochrone) – Isochrone object(s) to plot.
iso_labels (sequence of str, optional) – Legend labels, one per isochrone. If None no legend is added. Ignored when iso is a single Isochrone.
x (str) – Property or column names for the horizontal and vertical axes. Recognised shortcuts: "log_Teff", "log_L", "log_g", "mass", or any column name in iso.data.
y (str) – Property or column names for the horizontal and vertical axes. Recognised shortcuts: "log_Teff", "log_L", "log_g", "mass", or any column name in iso.data.
fig (matplotlib Figure, optional) – Existing figure to draw on. A new axes is added to it when ax is None. Ignored if ax is provided.
ax (matplotlib Axes, optional) – Existing axes to draw on. Takes priority over fig. A new figure is created if both are None.
invert_x (bool) – If True the x-axis is inverted (conventional for T_eff).
cmap (str) – Matplotlib colormap name used to color curves when plotting multiple isochrones and no explicit color is given in kwargs. Ignored for a single isochrone.
**kwargs – Forwarded to matplotlib.pyplot.plot().

Returns:

fig, ax

Return type:

Figure, Axes

isoc.isochrone#

Query and process Padova/PARSEC or MIST/MESA isochrone databases to get isochrones and associated photometry as astropy QTable objects with physical units.

class isoc.isochrone.Isochrone(database: Literal['padova', 'mist'], data: QTable = None)[source]#

Wrapper that stores isochrone data from either the PARSEC/Padova or MIST/MESA service as an QTable with units.

Parameters:: database (str) – Backend that produced the data: "padova" or "mist".

property columns: list#: List of column names.

property data: QTable#: Isochrone data (excluding photometry) as an QTable.

property database: str#: Backend that produced this data ("padova" or "mist").

static default_values(database: Literal['padova', 'mist']) → dict[source]#

Get the default query parameters.

Returns:: A copy of the default query parameters. The aliases key maps the parameter name expected by the web server to the generalized arg names in from_padova() or from_mist().
Return type:: dict

Query the MIST/MESA service and return an Isochrone.

Any parameters passed as None will use the MIST defaults (see Isochrone.default_values).

Parameters:

age (float, tuple of (low, high, step), list or None) – Age in years or log10(years). A single float queries one isochrone; a tuple of length 3 sets a min, max and step size to query over the corresponding age grid, and a list queries over an age grid.
metallicity (float or None) – [Fe/H] metallicity value.
abundance (float or None) – [alpha/Fe] abundance ratio.
v_div_vcrit (float or None) – Initial rotation velocity v/v_crit.
photometry (str or None) – The name of a photometric system to retrieve synthetic photometry for. If None, MIST output is set to “theory”.
extinction (float or None) – Extinction A_V to apply to photometry. Has no effect if photometry is None.
version (str or None) – MIST version to query.
from_file (str or None) – If provided, load isochrone data from a file instead of querying the MIST service.
**kwargs – Additional keyword arguments forwarded to the MIST query.

Returns:

An Isochrone object containing the queried data.

Return type:

Isochrone

Query the Padova/PARSEC service and return an Isochrone.

Any parameters passed as None will use the Padova/PARSEC defaults (see Isochrone.default_values).

Parameters:

age (tuple of (low, high, step) or float or None) – Age in years or log10(years). A single float queries one isochrone; a tuple of length 3 sets a min, max and step size to query over the corresponding age grid, and a list queries over an age grid.
metallicity (tuple of (low, high, step) or float or None) – Metallicity value. Interpreted as Z or [M/H] depending on metallicity_type.
metallicity_type (str or None) – Whether the metallicity parameter is interpreted as “Z” or “MH” ([M/H]).
photometry (str or None) – The name of a photometric system to retrieve synthetic photometry for.
from_file (str or None) – If provided, load isochrone data from a file instead of querying the Padova service.
**kwargs – Additional keyword arguments forwarded to the Padova query.

Returns:

An Isochrone object containing the queried data.

Return type:

Isochrone

get_photometry_system_title() → str | None[source]#: Look up the human-readable title for the queried photometric system.

property header: str#: Header metadata from the original isochrone file/query.

property initial_mass#: Stellar mass column [M_Sun].

property initial_metallicity#: Initial metallicity column.

property isochrone: _IsochroneIndex#

Index individual isochrones within a multi-isochrone table.

Supports integer and 'field=value' string keys. Each item is a new Isochrone containing only the rows for that individual isochrone.

Examples

>>> iso.isochrone[-1]
>>> iso.isochrone['log_age=9']          # MIST
>>> iso.isochrone['logAge=9']           # Padova
>>> iso.isochrone['[Fe/H]_init=0.015']  # MIST: initial metallicity
>>> iso.isochrone['Zini=0.015']         # Padova: initial metallicity

property log_L#: log10(L [L_Sun]) column.

property log_Teff#: log10(Teff [K]) column.

property log_age#: log10(age / [yr]) column.

property log_g#: log10(g [cm s^-2]) column.

property mass#: Stellar mass column [M_Sun].

property metallicity#: Metallicity column.

property metallicity_type#: Whether the metallicity column is "Z", "MH" ([M/H]), or "FeH" ([Fe/H]).

property n_isochrones: int#: Number of isochrones in the data.

static parameter_descriptions(database: Literal['padova', 'mist']) → dict[source]#: Get descriptions for each query parameter.

property photometry: Photometry#: Photometric magnitude columns as a Photometry object.

classmethod query_ezpadova(age_yr: tuple[float, float, float] | None = None, Z: tuple[float, float, float] | None = None, logage: tuple[float, float, float] | None = None, MH: tuple[float, float, float] | None = None, default_ranges: bool = False, **kwargs) → Isochrone[source]#: Query the Padova/PARSEC service and return an Isochrone.

property query_parameters: dict#

The resolved query parameters used to retrieve this isochrone.

Returns:: A copy of the query parameters sent to the webform.
Return type:: dict

class isoc.isochrone.Photometry(isochrone: Isochrone)[source]#

Container for photometric magnitude columns.

Photometry data is stored in QTable instances, one for each photometric system queried.

Each band is accessible as a named attribute.

Parameters:: isochrone (Isochrone) – The parent Isochrone instance, used to access metadata.

add_photometry(system_names: str | list[str]) → None[source]#

Query one or more additional photometric systems and add them.

Re-uses the query parameters from the parent Isochrone, changing only the photometric system.

Parameters:: system_names (str or list[str]) – One or more photometric system identifiers (short key or long description).

property available_systems: dict#

All photometric systems available for querying.

For Padova, systems are parsed from ezpadova’s parsec.json (the photsys_file dictionary). For MIST, systems are parsed from isoc’s mist_config.json (the output dictionary).

Returns:: {system_value: description, ...}
Return type:: dict

property columns: dict[str, list]#

Column names per system.

Returns:: {system_full_name: [col1, col2, ...], ...}
Return type:: dict

property data: _PhotometryTables#

Per-system photometry tables.

Returns:: {system_full_name: QTable, ...} — also exposes .columns.
Return type:: _PhotometryTables

get_color(band1: str, band2: str) → Quantity[source]#

Compute a color index by subtracting two magnitude columns.

The resulting color column is added to the table that contains band1.

Parameters:

band1 (str) – Names of the two magnitude columns.
band2 (str) – Names of the two magnitude columns.

Returns:

color – The band1 − band2 color array.

Return type:

Quantity

property header: str#: Header metadata for each photometric system.

property systems: dict[str, str]#

Photometric systems currently loaded.

Returns:: {short_key: full_name, ...}
Return type:: dict

isoc.plot#

Convenience plotting functions for isochrone data. All functions return (fig, ax) tuples.

isoc.plot.plot_color_magnitude(iso: Isochrone, band1: str, band2: str, mag: str | None = None, fig: Figure | None = None, ax: Axes | None = None, invert_y: bool = True, **kwargs) → tuple[Figure, Axes][source]#

Plot a color–magnitude diagram.

Uses Photometry.get_color() to compute the color band1 − band2 and plots it against a magnitude.

Parameters:

iso (Isochrone) – Isochrone with photometry.
band1 (str) – Band names passed to Photometry.get_color().
band2 (str) – Band names passed to Photometry.get_color().
mag (str, optional) – Band name for the y-axis magnitude. Defaults to band1.
fig (matplotlib Figure, optional) – Existing figure to draw on. A new axes is added to it when ax is None. Ignored if ax is provided.
ax (matplotlib Axes, optional) – Existing axes to draw on. Takes priority over fig. A new figure is created if both are None.
invert_y (bool) – If True the y-axis is inverted (brighter up).
**kwargs – Forwarded to matplotlib.pyplot.plot().

Returns:

fig, ax

Return type:

Figure, Axes

isoc.plot.plot_isochrone(iso: Isochrone | Sequence[Isochrone], iso_labels: Sequence[str] | None = None, x: str = 'log_Teff', y: str = 'log_L', fig: Figure | None = None, ax: Axes | None = None, invert_x: bool = True, cmap: str = 'viridis', **kwargs) → tuple[Figure, Axes][source]#

Plot one or more isochrones on an HR diagram.

Parameters:

iso (Isochrone or sequence of Isochrone) – Isochrone object(s) to plot.
iso_labels (sequence of str, optional) – Legend labels, one per isochrone. If None no legend is added. Ignored when iso is a single Isochrone.
x (str) – Property or column names for the horizontal and vertical axes. Recognised shortcuts: "log_Teff", "log_L", "log_g", "mass", or any column name in iso.data.
y (str) – Property or column names for the horizontal and vertical axes. Recognised shortcuts: "log_Teff", "log_L", "log_g", "mass", or any column name in iso.data.
fig (matplotlib Figure, optional) – Existing figure to draw on. A new axes is added to it when ax is None. Ignored if ax is provided.
ax (matplotlib Axes, optional) – Existing axes to draw on. Takes priority over fig. A new figure is created if both are None.
invert_x (bool) – If True the x-axis is inverted (conventional for T_eff).
cmap (str) – Matplotlib colormap name used to color curves when plotting multiple isochrones and no explicit color is given in kwargs. Ignored for a single isochrone.
**kwargs – Forwarded to matplotlib.pyplot.plot().

Returns:

fig, ax

Return type:

Figure, Axes

isoc.mist#

isoc.mist.get_isochrones(age: tuple[float, float, float] | list | float | None = None, FeH: float = None, alphaFe: Literal[-0.2, 0.0, 0.2, 0.4, 0.6] = None, v_div_vcrit: Literal[0.0, 0.4] = None, output: str | None = None, extinction_Av: float = None, version: Literal['MIST1', 'MIST2'] = None, from_file: str | None = None, photometry_only: bool = False, **kwargs) → DataFrame[source]#

Retrieve MIST isochrones.

Parameters:

age (float, tuple of (low, high, step), list or None) – Age in years or log10(years). A single float queries one isochrone; a tuple of length 3 sets a min, max and step size to query over the corresponding age grid, and a list queries over an age grid.
FeH (float) – [Fe/H] metallicity value.
alphaFe (float) – [alpha/Fe] abundance ratio.
v_div_vcrit (float) – Initial rotation velocity v/v_crit.
output (str or None) – The name of a photometric system to retrieve synthetic photometry for. If None, MIST output is set to “theory”.
extinction_Av (float) – Extinction A_V to apply to photometry. Has no effect if photometry is None.
version ("MIST1" or "MIST2", optional) – MIST version to query.
from_file (str or None) – If provided, load isochrone data from a file instead of querying the MIST service.
photometry_only (bool, optional) – If True, only photometry columns are returned.
**kwargs – Additional keyword arguments forwarded to the MIST query.

Returns:

Parsed isochrone data.

Return type:

pd.DataFrame

isoc.mist.parse_result(data: str | bytes | dict, photometry_only: bool = False) → DataFrame | tuple[DataFrame, DataFrame, list][source]#

Parse MIST isochrone data.

data may be:

dict – mapping of {filename: text_content} extracted from a zip archive. When both a .iso and a .iso.<system> file are present, the photometry file is parsed and the photometry columns (those not in the theory-only .iso header) are identified.
bytes – raw content returned by the MIST server (possibly gzip- or zip-compressed).
str that is a file path – a local file containing isochrone data.
str of file content – the decoded text of an isochrone file.

Parameters:

data (dict, str, or bytes) – Raw server content, extracted zip dict, a file path, or decoded text.
photometry_only (bool, optional) – If True and data is a zip dict containing both theory and photometry files, returns only a pd.DataFrame of photometry columns. Otherwise returns a 3-tuple (theory_df, phot_only_df, phot_columns).

Returns:

When data is a zip dict and photometry_only=False: (theory_df, phot_only_df, phot_columns) where theory_df contains all non-photometry columns, phot_only_df contains only the photometry columns, and phot_columns is the list of photometry column names.
When data is a zip dict and photometry_only=True: a single pd.DataFrame of photometry columns.
Otherwise: a single pd.DataFrame with the file header stored in df.attrs["comment"].

Return type:

pd.DataFrame or tuple

isoc.mist.query(q: str) → bytes | dict[source]#

Query the MIST webpage with the given parameters.

Sends a POST request to the MIST webpage specified in the configuration and retrieves the resulting data. The data is processed and returned as bytes. If the server response is incorrect or if there is an issue with the data retrieval, a RuntimeError is raised.

Parameters:

q – URL-encoded query string.

Returns:

The retrieved data from the MIST webpage.: When the download is a zip archive containing multiple files, a dict mapping filenames to their byte content is returned. Otherwise raw bytes of the single file.

Return type:

bytes or dict

Raises:

RuntimeError – If the server response is incorrect or if there is an issue with data retrieval.

isoc.mist_config#

Get the MIST server paramter configuration.

Scrapes the MIST isochrone interpolation webform at https://mist.science/interp_isos.html to keep option lists and default values current.

Note

Several form fields on the MIST website are injected by JavaScript after the page loads and therefore cannot be scraped from the static HTML source. These fields are maintained as static definitions in _JS_INJECTED_* constants below. They should be updated manually whenever the MIST website changes these options.

isoc.mist_config.reload_config()[source]#: Load (or create) the local JSON configuration cache.

isoc.mist_config.update_config()[source]#: Scrape the MIST website, refresh the configuration, and save it.

isoc.file_io#

isoc.file_io.extract_zip(data: bytes) → dict[source]#

Extract all files from a zip archive stored in data.

Parameters:: data (bytes) – Raw bytes of a zip archive.
Returns:: Mapping of {filename: content_string} for every file in the archive. Text files are decoded as UTF-8; binary files are returned as raw bytes.
Return type:: dict

isoc.file_io.load_isochrone(filepath: str) → str | bytes | dict[source]#

Load raw isochrone data from a local file.

If the file type is:

zip archive – extracted with extract_zip(), returns a dict mapping {filename: content}.
gzip/bz2 archive – decompressed, returns raw bytes.
plain text – read as UTF-8, returns a str.

Parameters:: filepath (str) – Path to the local isochrone file.
Returns:: The file contents in whichever form matches the archive type.
Return type:: str, bytes, or dict
Raises:: FileNotFoundError – If filepath does not point to an existing file.

API Reference#

isoc#

isoc.isochrone#

isoc.plot#

isoc.mist#

isoc.mist_config#

isoc.file_io#

isoc.units#