Models & utilities

Container classes, parameter dictionaries, functions related to file loading and/or saving as well as various data manipulation methods (i.e. correcting artefacts, binning data, etc.).

Introduction

Imports

Any dependencies

Usage

Used during…

Examples

Models

pysyd.models.background(frequency, guesses, mode='regular', ab=False, noise=None)

The main model for the stellar background fitting

Parameters
frequencynumpy.ndarray

the frequency of the power spectrum

guesseslist

the parameters of the Harvey model

mode{‘regular’, ‘second’, ‘fourth’}

the mode of which Harvey model parametrization to use. Default mode is regular. The ‘regular’ mode is when both the second and fourth order terms are added in the denominator whereas, ‘second’ only adds the second order term and ‘fourth’ only adds the fourth order term.

totalbool

If True, returns the summed model over multiple components. This is deprecated.

abbool, optional

If True, changes to the traditional a, b parametrization as opposed to the SYD

noiseNone, optional

If not None, it will fix the white noise to this value and not model it, reducing the dimension of the problem/model

Returns
modelnp.ndarray

the stellar background model

TODO

option to fix the white noise (i.e. noise option) option to change the parametrization (i.e. ab option) option to add power law

pysyd.models.gaussian(frequency, offset, amplitude, center, width)

Gaussian model

Observed solar-like oscillations have a Gaussian-like profile and therefore, detections are modeled as a Gaussian distribution.

Parameters
frequencynumpy.ndarray

the frequency array

offsetfloat

the vertical offset

amplitudefloat

amplitude of the Gaussian

centerfloat

center of the Gaussian

widthfloat

the width of the Gaussian

Returns
resultnp.ndarray

the Gaussian distribution

pysyd.models.harvey_fit(frequency, tau, sigma, exponent, mode='regular', ab=False)

Testing

pysyd.models.harvey_fourth(frequency, tau, sigma, mode='regular', ab=False)

Testing

pysyd.models.harvey_none(frequency, white_noise, ab=False)

No Harvey model

Stellar background model that does not contain any Harvey-like components i.e. this is the simplest model of all - consisting of a single white-noise component. This was added with the hopes that it would be preferred in the model selection for non-detections.

Warning

check if this is working for null detections

Parameters
frequencynumpy.ndarray

the frequency array

white_noisefloat

the white noise component

Returns
modelnumpy.ndarray

the no-Harvey (white noise) model

pysyd.models.harvey_one(frequency, tau_1, sigma_1, white_noise, ab=False)

One Harvey model

Stellar background model consisting of a single Harvey-like component

Parameters
frequencynumpy.ndarray

the frequency array

tau_1float

timescale of the first harvey component

sigma_1float

amplitude of the first harvey component

white_noisefloat

the white noise component

Returns
modelnumpy.ndarray

the one-Harvey model

pysyd.models.harvey_regular(frequency, tau, sigma, mode='regular', ab=False)

Testing

pysyd.models.harvey_second(frequency, tau, sigma, mode='regular', ab=False)

Testing

pysyd.models.harvey_three(frequency, tau_1, sigma_1, tau_2, sigma_2, tau_3, sigma_3, white_noise, ab=False)

Three Harvey model

Stellar background model consisting of three Harvey-like components

Parameters
frequencynumpy.ndarray

the frequency array

tau_1float

timescale of the first harvey component

sigma_1float

amplitude of the first harvey component

tau_2float

timescale of the second harvey component

sigma_2float

amplitude of the second harvey component

tau_3float

timescale of the third harvey component

sigma_3float

amplitude of the third harvey component

white_noisefloat

the white noise component

Returns
modelnumpy.ndarray

the three-Harvey model

pysyd.models.harvey_two(frequency, tau_1, sigma_1, tau_2, sigma_2, white_noise, ab=False)

Two Harvey model

Stellar background model consisting of two Harvey-like components

Parameters
frequencynumpy.ndarray

the frequency array

tau_1float

timescale of the first harvey component

sigma_1float

amplitude of the first harvey component

tau_2float

timescale of the second harvey component

sigma_2float

amplitude of the second harvey component

white_noisefloat

the white noise component

Returns
modelnumpy.ndarray

the two-Harvey model

pysyd.models.power(frequency, coefficient, exponent)

Power law

Power law distribution used to model traditional “red” noise contributions i.e. the rise in power at low frequencies typically corresponding to long-term stellar variability

Parameters
frequencynumpy.ndarray

the frequency array

coefficientfloat

the power law coefficient

exponentfloat

the power law exponent

Returns
resultnp.ndarray

the power law distribution

pysyd.models.white(frequency, white_noise)

Testing

class pysyd.utils.Constants

Container class for constants and known values – which is primarily solar asteroseismic values for our purposes.

UNITS ARE IN THE SUPERIOR CGS COME AT ME

exception pysyd.utils.InputError(error, width=60)

Class for pySYD user input errors (i.e., halts execution).

exception pysyd.utils.InputWarning(warning, width=60)

Class for pySYD user input warnings.

class pysyd.utils.Parameters(args=None)

Container class for pySYD parameters

Calls super method to inherit all relevant constants and then stores the default values for all pysyd modules

Methods

add_cli(args)

Add CLI

Save any non-default parameters provided via command line but skips over any keys in the override columns since those are star specific and have a given length – it will come back to this

Parameters
argsargparse.Namespace

the command line arguments

add_targets(stars=None)

Add targets

This was mostly added for non-command-line users, since this makes API usage easier.

check_cli(args, max_laws=3, override=['numax', 'dnu', 'lower_ex', 'upper_ex', 'lower_bg', 'upper_bg', 'lower_ps', 'upper_ps', 'lower_ech', 'upper_ech'])

Check CLI

Make sure that any command-line inputs are the proper lengths, types, etc.

Parameters
argsargparse.Namespace

the command line arguments

max_lawsint

maximum number of Harvey laws to be fit

Asserts

  • the length of each array provided (in override) is equal

  • the oversampling factor is an integer (if applicable)

  • the number of Harvey laws to “force” is an integer (if applicable)

get_background(background=True, basis='tau_sigma', box_filter=1.0, ind_width=20.0, n_rms=20, n_laws=None, fix_wn=False, metric='bic', lower_bg=None, upper_bg=None, functions=None)

Background parameters

Gets parameters used during the automated background-fitting analysis

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_data(info='info/star_info.csv', todo='info/todo.txt', stars=None, mode='run', gap=20, stitch=False, oversampling_factor=None, kep_corr=False, notching=False, dnu=None, lower_ech=None, upper_ech=None)

Get data parser

Load parameters available in the data parser, which is mostly related to initial data loading and manipulation

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_defaults()

Load defaults

Gets default pySYD parameters by calling functions which are analogous to available command-line parsers and arguments

Attributes
paramsDict[str[Dict[,]]]

container class for pySYD parameters

Calls
get_estimate(estimate=True, smooth_width=20.0, binning=0.005, bin_mode='mean', step=0.25, n_trials=3, ask=False, lower_ex=None, upper_ex=None)

Search and estimate parameters

Get parameters relevant for the optional first module that looks for and identifies power excess due to solar-like oscillations and then estimates its properties

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_global(globe=True, numax=None, lower_ps=None, upper_ps=None, ex_width=1.0, sm_par=None, smooth_ps=2.5, fft=True, threshold=1.0, n_peaks=5)

Global fitting parameters

Get default parameters that are relevant for deriving global asteroseismic parameters \(\rm \nu_{max}\) and \(\Delta\nu\)

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_main()

Get main parser

Load parameters available in the main parser i.e. core software functionality

Attributes
paramsDict[str,Dict[,]]

the updated parameters

Calls
get_parent(inpdir='data', infdir='info', outdir='results', save=True, test=False, verbose=False, overwrite=False, warnings=False, cli=True, notebook=False)

Get parent parser

Load parameters available in the parent parser i.e. higher-level software functionality

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_plot(show_all=False, show=False, cmap='binary', hey=False, clip_value=3.0, interp_ech=False, nox=None, noy='0+0', npb=10, ridges=False, smooth_ech=None)

Get plot parser

Save all parameters related to any of the output figures

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_sampling(mc_iter=1, seed=None, samples=False, n_threads=0)

Sampling parameters

Get parameters relevant for the sampling steps i.e. estimating uncertainties

Attributes
paramsDict[str,Dict[,]]

the updated parameters

exception pysyd.utils.ProcessingError(error, width=60)

Class for pySYD processing errors (i.e., halts execution).

exception pysyd.utils.ProcessingWarning(warning, width=60)

Class for pySYD user input warnings.

pysyd.utils.delta_nu(numax)

\(\Delta\nu\)

Estimates the large frequency separation using the numax scaling relation (add citation?)

Parameters
numaxfloat

the frequency corresponding to maximum power or numax (\(\rm \nu_{max}\))

Returns
dnufloat

the approximated frequency spacing or dnu (\(\Delta\nu\))

pysyd.utils.get_dict(type='params')

Get dictionary

Quick+convenient utility function to read in longer dictionaries that are used throughout the software

Parameters
type{‘columns’,’params’,’plots’,’tests’,’functions’}, default=’params’

which dictionary to load in – which MUST match their relevant filenames

Returns
resultDict[str,Dict[,]]

the relevant (type) dictionary

Important

'functions' cannot be saved and loaded in like the other dictionarie because it points to modules loaded in from another file

pysyd.utils.get_infdir(args, dl_dict, note, source='https://raw.githubusercontent.com/ashleychontos/pySYD/master/dev/')

Create info directory

Parameters
argsargparse.NameSpace

command-line arguments

notestr

verbose output

dl_dictDict[str,str]

dictionary to keep track of files that need to be downloaded

sourcestr

path to pysyd source directory on github

Returns
dl_dictDict[str,str]

dictionary of files to download for setup

notestr

updated verbose output

pysyd.utils.get_inpdir(args, dl_dict, note, save=False, examples=['1435467', '2309595', '11618103'], exts=['LC', 'PS'], source='https://raw.githubusercontent.com/ashleychontos/pySYD/master/dev/')

Create data (i.e. input) directory

Parameters
argsargparse.NameSpace

command-line arguments

notestr

verbose output

dl_dictDict[str,str]

dictionary to keep track of files that need to be downloaded

sourcestr

path to pysyd source directory on github

examplesList[str]

KIC IDs for 3 example stars

extsList[str]

data types to download for each star

Returns
dl_dictDict[str,str]

dictionary of files to download for setup

notestr

updated verbose output

pysyd.utils.get_outdir(args, note)

Create results directory

Parameters
argsargparse.Namespace

command-line arguments

notestr

verbose output

Returns
notestr

updated verbose output

pysyd.utils.get_output(fun=False)

Print logo output

Used within test mode when current installation is successfully tested.

Parameters
funbool, False

if calling module for ‘fun’, only prints logo but doesn’t test software

pysyd.utils.setup_dirs(args, note='', dl_dict={})

Setup pySYD directories

Primarily most of pipeline.setup functionality to keep the pipeline script from getting too long. Still calls/downloads things in the same way: 1) info directory, 2) input + data directory and 3) results directory.

Parameters
argsargparse.NameSpace

command-line arguments

notestr

verbose output

dl_dictDict[str,str]

dictionary to keep track of files that need to be downloaded

Returns
dl_dictDict[str,str]

dictionary of files to download for setup

notestr

updated verbose output

Calls

Utilities

class pysyd.utils.Parameters(args=None)

Container class for pySYD parameters

Calls super method to inherit all relevant constants and then stores the default values for all pysyd modules

Methods

add_cli(args)

Add CLI

Save any non-default parameters provided via command line but skips over any keys in the override columns since those are star specific and have a given length – it will come back to this

Parameters
argsargparse.Namespace

the command line arguments

add_targets(stars=None)

Add targets

This was mostly added for non-command-line users, since this makes API usage easier.

check_cli(args, max_laws=3, override=['numax', 'dnu', 'lower_ex', 'upper_ex', 'lower_bg', 'upper_bg', 'lower_ps', 'upper_ps', 'lower_ech', 'upper_ech'])

Check CLI

Make sure that any command-line inputs are the proper lengths, types, etc.

Parameters
argsargparse.Namespace

the command line arguments

max_lawsint

maximum number of Harvey laws to be fit

Asserts

  • the length of each array provided (in override) is equal

  • the oversampling factor is an integer (if applicable)

  • the number of Harvey laws to “force” is an integer (if applicable)

get_background(background=True, basis='tau_sigma', box_filter=1.0, ind_width=20.0, n_rms=20, n_laws=None, fix_wn=False, metric='bic', lower_bg=None, upper_bg=None, functions=None)

Background parameters

Gets parameters used during the automated background-fitting analysis

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_data(info='info/star_info.csv', todo='info/todo.txt', stars=None, mode='run', gap=20, stitch=False, oversampling_factor=None, kep_corr=False, notching=False, dnu=None, lower_ech=None, upper_ech=None)

Get data parser

Load parameters available in the data parser, which is mostly related to initial data loading and manipulation

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_defaults()

Load defaults

Gets default pySYD parameters by calling functions which are analogous to available command-line parsers and arguments

Attributes
paramsDict[str[Dict[,]]]

container class for pySYD parameters

Calls
get_estimate(estimate=True, smooth_width=20.0, binning=0.005, bin_mode='mean', step=0.25, n_trials=3, ask=False, lower_ex=None, upper_ex=None)

Search and estimate parameters

Get parameters relevant for the optional first module that looks for and identifies power excess due to solar-like oscillations and then estimates its properties

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_global(globe=True, numax=None, lower_ps=None, upper_ps=None, ex_width=1.0, sm_par=None, smooth_ps=2.5, fft=True, threshold=1.0, n_peaks=5)

Global fitting parameters

Get default parameters that are relevant for deriving global asteroseismic parameters \(\rm \nu_{max}\) and \(\Delta\nu\)

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_main()

Get main parser

Load parameters available in the main parser i.e. core software functionality

Attributes
paramsDict[str,Dict[,]]

the updated parameters

Calls
get_parent(inpdir='data', infdir='info', outdir='results', save=True, test=False, verbose=False, overwrite=False, warnings=False, cli=True, notebook=False)

Get parent parser

Load parameters available in the parent parser i.e. higher-level software functionality

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_plot(show_all=False, show=False, cmap='binary', hey=False, clip_value=3.0, interp_ech=False, nox=None, noy='0+0', npb=10, ridges=False, smooth_ech=None)

Get plot parser

Save all parameters related to any of the output figures

Attributes
paramsDict[str,Dict[,]]

the updated parameters

get_sampling(mc_iter=1, seed=None, samples=False, n_threads=0)

Sampling parameters

Get parameters relevant for the sampling steps i.e. estimating uncertainties

Attributes
paramsDict[str,Dict[,]]

the updated parameters