grannules.utils package#

Submodules#

grannules.utils.datatransform module#

Provides DataTransformer, an abstract base class for defining custom data transformers for data pre-processing, as well as DefaultXTransformer and DefaultyTransformer, the transformers used by grannules.NNPredictor.get_default_predictor() and grannules.predict()

class grannules.utils.datatransform.DataTransformer(center: Array, scale: Array)[source]#

Bases: object

Custom data transformers for use in creating custom NNPredictors should inherit this class and override fit_transform(), transform(), and inverse_transform(). Provides default __init__() and fit() methods that may optionally be overridden as well.

fit(X) → None[source]#

Calls fit_transform() without returning.

Parameters:

X – Passed through to fit_transform()

abstractmethod fit_transform(X)[source]#
abstractmethod inverse_transform(X)[source]#
abstractmethod transform(X)[source]#
class grannules.utils.datatransform.DefaultXTransformer(center: Array, scale: Array)[source]#

Bases: DataTransformer

fit_transform(X: DataFrame) → Array[source]#
inverse_transform(X: Array) → Array[source]#
transform(X: DataFrame) → Array[source]#
class grannules.utils.datatransform.DefaultyTransformer(center: Array, scale: Array)[source]#

Bases: DataTransformer

fit_transform(y: DataFrame) → Array[source]#
inverse_transform(y: Array) → Array[source]#
transform(y: DataFrame) → Array[source]#

grannules.utils.model module#

Implements factories for the neural network architectures (flax.nn.module objects) used in the main module of this package.

grannules.utils.model.model_from_params(hyperparams, n_outputs)[source]#

Creates a neural network model (flax.nn.Module) using the hyperparameters in hyperparams.

Parameters:

  • hyperparams (dict[str, int | float | str]) –

    A dictionary with the following entries:

    • ’num_layers’, int, the number of layers the model should have.

    • ’dropout_rate’, float, the fraction of neurons to disable at random on any training run.

    • ’use_dropout_rate’, bool, whether to use a dropout rate at all.

    • ’layer_[n]_size’, int, the amount of neurons in the nth layer. There should be one of these arguments for every n in [0, num_layers).

    • ’layer_[n]_type’, str ‘relu’, ‘sigmoid’, or ‘tanh’ the operation performed by neurons in this layer. There should be one of these entries for every n in [0, num_layers), like for ‘layer_[n]_size’.

  • n_outputs (int) – The number of outputs this neural network should have.

Returns:

Instance of created model (a subclass of flax.nn.Module).

Return type:

flax.nn.Module

grannules.utils.model.model_from_trial(trial, n_outputs)[source]#

Does the same thing as model_from_params(), but calls the suggest_ methods on trial to gather the hyperparameters. suggest_categorical() for the bool and str arguments, and suggest_int() and suggest_float() for the int and float arguments respectively.

grannules.utils.psd module#

Implements helper methods to generate synthetic power spectrum envelopes without white noise or activity similar to de Assis Peralta et al. 2018 Equation (9).

\[\mathrm{PSD}(\nu) = \eta^2(\nu) \left[ \frac{P}{1 + \left(2 \pi \tau \nu \right)^\alpha} + H \exp \left( \frac{-(\nu - \nu_\mathrm{max})^2} {0.66 \nu_\mathrm{max}^{0.88} /4 \ln 2} \right) \right]\]

The whole equation is implemented in PSD(), and individual components are implemented as follows:

  • The damping factor, \(\eta^2(\nu)\) is implemented in damping()

  • The granulation background, the first term in the brackets, is implemented in granulation()

  • The signal excess envelope, the second term in the brackets, is implemented in excess().

This submodule also implements simple scaling relations for \(\nu_\mathrm{max}\), the frequency at maximum power, and \(\Delta \nu\), the large frequency separation in nu_max() and delta_nu() respectively.

grannules.utils.psd.PSD(nu, nu_max, H, P, tau, alpha, reshape=True)[source]#
Parameters:

reshape (bool) – Reshapes nu into a “row” array of shape (1, len(nu)) and the other input parameters into “column” arrays of shape (len(arg), 1) such that the output is a 2D array where the ijth element corresponds to power of the ith star at the jth frequency. Defaults to True.

grannules.utils.psd.damping(nu)[source]#
grannules.utils.psd.delta_nu(M, R, delta_nu_solar=135.1)[source]#
grannules.utils.psd.excess(nu, nu_max, H)[source]#
grannules.utils.psd.granulation(nu, P, tau, alpha)[source]#
grannules.utils.psd.nu_max(M, R, Teff, nu_max_solar=3090, Teff_solar=5777)[source]#

grannules.utils.scalingrelations module#

Provides the SRPredictor class, which allows the user to predict \(H,\,P,\,\) and \(\tau\) using the \(\nu_\mathrm{max}\) scaling relations in de Assis Peralta et al. 2018, complemented with my own fit for \(\alpha\) using the data from the same study.

class grannules.utils.scalingrelations.SRPredictor(relations: dict[str, tuple[float, float]] = {}, relations_with_phase: tuple[dict[str, tuple[float, float]]] = ({}, {}, {}), use_phase=True)[source]#

Bases: object

Uses \(\nu_\mathrm{max}\) scaling relations to predict red giant granulation parameters.

Defaults to using the relations for \(H,\, P,\,\) and \(\tau\) found in de Assis Peralta et al. 2018 Table B5, and a provided fit for \(\alpha\).

Parameters:

  • relations (dict[str, tuple[float, float]]) – If use_phase is False, overrides the “all” fits in the default relations with entries in this dict. Use keys “H”, “P”, “tau” and “alpha” to replace the respective scaling relations. The values should be tuples of float of length 2, where the first item is the coefficient of \(\nu_\mathrm{max}\), and the second is the exponent. Defaults to an empty dictionary (no overrides).

  • relations_with_phase (tuple[dict[str, tuple[float, float]]]) –

    This parameter is a tuple of length 3, where each element is a dict just like relations. Each dict corresponds to the scaling relations for the following stellar evolution phases:

    • 0: Unclassified/All

    • 1: Red Giant Branch

    • 2: Red Clump/Helium Burning

    If use_phase is True, each dict will override the default scaling relation of its respective phase, as with the relations parameter.

  • use_phase (bool) – Whether to use different scaling relations based on the phase of the input star.

predict(nu_max, phases=0) → DataFrame[source]#
grannules.utils.scalingrelations.compare_psd(M: float | None = None, R: float | None = None, Teff: float | None = None, FeH: float | None = None, phase: float | None = None, KepMag: float | None = None, KIC=None, *, x: Series | None = None)[source]#

Compare the power spectral density (PSD) of a red giant derived from the default NNPredictor model and the scaling relations. Has functionality to optionally fetch observed PSD using lightkurve.

Important

This method requires holoviews to be installed.

To fetch Kepler lightcurves (i.e. running with KIC is not None), lightkurve is also required.

Parameters:

  • M (float, optional) – Stellar mass in solar units. Default is None.

  • R (float, optional) – Stellar radius in solar units. Default is None.

  • Teff (float, optional) – Effective temperature of the star in Kelvin. Default is None.

  • FeH (float, optional) – Metallicity of the star ([Fe/H]). Default is None.

  • phase (float, optional) – Evolutionary phase of the star. Default is None.

  • KepMag (float, optional) – Kepler magnitude of the star. Default is None.

  • KIC (int, optional) – Kepler Input Catalog (KIC) identifier for the star. Default is None.

  • x (pd.Series, optional) – A pandas Series containing the stellar parameters (M, R, Teff, FeH, phase, KepMag). If provided, individual parameters should not be passed. Default is None.

Returns:

A Holoviews Overlay object containing the PSD plots for the star, including:

  • The true PSD (if KIC is provided).

  • The binned PSD (if KIC is provided).

  • PSD predicted using scaling relations.

  • PSD predicted using a neural network.

  • A vertical line indicating the predicted nu_max value.

Return type:

holoviews.Overlay

Raises:

ValueError – If neither a pandas Series (x) nor individual stellar parameters are provided.

Note

  • The function uses Lightkurve to search, download, and process the light curve data for the given KIC.

  • The PSD is computed and compared against predictions from scaling relations and a neural network.

  • The function caches the PSD for a given KIC to avoid redundant computations.

grannules.utils.scalingrelations.compare_psd_bokeh(M: float | None = None, R: float | None = None, Teff: float | None = None, FeH: float | None = None, phase: float | None = None, KepMag: float | None = None, KIC=None, *, x: Series | None = None, cache={})[source]#

Compare the power spectral density (PSD) of a red giant derived from the default NNPredictor model and the scaling relations, returning a Bokeh figure.

Parameters:

  • M (float, optional) – Stellar mass in solar units. Default is None.

  • R (float, optional) – Stellar radius in solar units. Default is None.

  • Teff (float, optional) – Effective temperature of the star in Kelvin. Default is None.

  • FeH (float, optional) – Metallicity of the star ([Fe/H]). Default is None.

  • phase (float, optional) – Evolutionary phase of the star. Default is None.

  • KepMag (float, optional) – Kepler magnitude of the star. Default is None.

  • KIC (int, optional) – Kepler Input Catalog (KIC) identifier for the star. Default is None.

  • x (pd.Series, optional) – A pandas Series containing the stellar parameters (M, R, Teff, FeH, phase, KepMag). If provided, individual parameters should not be passed. Default is None.

Returns:

A Bokeh figure containing the PSD plots for the star, including: * PSD predicted using scaling relations. * PSD predicted using a neural network. * The true PSD (if KIC is provided). * A vertical line indicating the predicted nu_max value.

Return type:

bokeh.plotting.figure

Module contents#