session¶
Setup PBjam sessions and perform mode ID and peakbagging
This module contains the input layer for setting up PBjam sessions for peakbagging solar-like oscillators. This is the easiest way to handle targets in PBjam.
It’s possible to manually initiate star class instances and do all the fitting that way, but it’s simpler to just use the session class, which handles everything, including formatting of the inputs.
A PBjam session is started by initializing the session class instance with a target ID, $ u_{max}$, a large separation, effective temperature and Gaia bp_rp color. The class instance is the called to run through all the peakbagging steps automatically. See the Session class documentation for an example.
Lists of the above can be provided for multiple targets, but it’s often simpler to just provide PBjam with a dictionary or Pandas dataframe. See mytgts.csv for a template.
Custom timeseries or periodograms can be provided as either file pathnames, `numpy’ arrays, or lightkurve.LightCurve/lightkurve.periodogram objects. If nothing is provided PBjam will download the data automatically using `LightKurve’.
Specific quarters, campgains or sectors can be requested with the relevant keyword (i.e., ‘quarter’ for KIC, etc.). If none of these are provided, PBjam will download all available data, using the long cadence versions by default.
Once initialized, the session class contains a list of star class instances for each requested target, with associated spectra for each.
The next step is to perform a mode ID on the spectra. At the moment PBjam only supports use of the asymptotic relation mode ID method. Additional methods can be added in future.
Finally the peakbagging method takes the output from the modeID and performs a proper HMC peakbagging run to get the unparameterized mode frequencies.
Plotting the results of each stage is also possible.
Note
For automatic download the long cadence data set is used by default, so set the cadence to `short’ for main-sequence targets.
-
class
pbjam.session.session(ID=None, numax=None, dnu=None, teff=None, bp_rp=None, timeseries=None, spectrum=None, dictlike=None, use_cached=False, exptime=None, campaign=None, sector=None, month=None, quarter=None, mission=None, path=None, download_dir=None, cadence=None)[source]¶ Main class used to initiate peakbagging.
Use this class to initialize a star class instance for one or more targets.
Once initialized, calling the session class instance will execute a complete peakbagging run.
Data can be provided in multiple different ways, the simplest of which is just to let PBjam query the MAST server. Otherwise arrays of timeseries/power spectra, lightkurve.LightCurve/lightkurve.periodogram, or just path names as strings, is also possible.
The physical parameters, such numax, dnu, teff, bp_rp, must each be provided at least as a list of length 2 for each star. This should contain the parameter value and it’s error estimate.
For multiple targets all the above can be provided as lists, but the easiest way is to simply provide a dataframe from a csv file.
By default, PBjam will download all the available data, favoring long cadence. Cadence and specific observing seasons (quarter, month, campagin, sector) can be specified for more detailed control. The data is downloaded using the Lightkurve API, and cleaned on the timeseries level by removing NaNs, and outliers, and flattening the lightcurve (again using LightKurve’s API). Note that the flattening process may impact the appearance of the granulation background.
Note
1. If you have a large directory of cached lightcurves or power spectra, it is best to supply the filenames to the files.
2. Teff and bp_rp provide much of the same information, so providing both is not strictly necessary. However, for best results you should try to provide both. If bp_rp is omitted though, PBjam will attempt to find this value in online catalogs.
- PBjam will not combine time series from different missions.
Examples
Peakbagging run for a single target:
>>> jam_sess = pbjam.session(ID = '4448777', numax = [220.0, 3.0], dnu = [16.97, 0.01], teff = [4750, 100], bp_rp = [1.34, 0.01], exptime = 1800) >>> jam_sess()
Peakbagging run for multiple targets: >>> jam_sess = pbjam.session(dictlike = mydataframe) >>> jam_sess()
Parameters: - ID (string, optional) – Target identifier, most commonly used identifiers can be used if you want PBjam to download the data (KIC, TIC, HD, Bayer etc.). If you provide data yourself the name can be any string.
- numax (list, optional) – List of the form [numax, numax_error], list of lists for multiple targets
- dnu (list, optional) – List of the form [dnu, dnu_error], list of lists for multiple targets
- teff (list, optional) – List of the form [teff, teff_error], list of lists for multiple targets
- bp_rp (list, optional) – List of the form [bp_rp, bp_rp_error], list of lists for multiple targets
- timeseries (object, optional) – Timeseries input. Leave as None for PBjam to download it automatically. Otherwise, arrays of shape (2,N), lightkurve.LightCurve objects, or strings for pathnames are accepted.
- spectrum (object, optional) – Spectrum input. Leave as None for PBjam to use Timeseries to compute it for you. Otherwise, arrays of shape (2,N), lightkurve.periodogram objects, or strings for pathnames are accepted.
- dictlike (pandas.DataFrame or dictionary, optional) – DataFrame, dictionary, record array with a list of targets, and their properties. If string, PBjam will assume it’s a pathname to a csv file. Specify timeseries and spectrum columns with file pathnames to use manually reduced data.
- store_chains (bool, optional) – Flag for storing all the full set of samples from the MCMC run. Warning, if running multiple targets, make sure you have enough memory.
- use_cached (bool, optional) – Flag for using cached data. If fitting the same targets multiple times, use to this to not download the data every time.
- cadence (string, deprecated) – This was used to specify the observation cadence for downloading via LightKurve. This was changed to exptime in Lightkurve v. 2
- exptime (string, optional) – Exposure time of the observations in seconds. Argument for lightkurve to download correct data type. Can be 1800 or Kepler ‘long’ cadence. 1800 is default setting, so if you’re looking at main sequence stars, make sure to manually set 60.
- campaign (int, optional) – Argument for lightkurve when requesting K2 data.
- sector (int, optional) – Argument for lightkurve when requesting TESS data.
- month (int, optional) – Argument for lightkurve when requesting Kepler short cadence data.
- quarter (int, optional) – Argument for lightkurve when requesting Kepler data.
- mission (str, optional) – Which mission to use data from. Default is all, so if your target has been observed by, e.g., both Kepler and TESS, LightKurve will throw and error.
- make_plots (bool, optional) – Whether or not to automatically generate diagnostic plots for the different stages of the peakbagging process.
- path (str, optional) – Path to store the plots and results for the various stages of the peakbagging process.
- download_dir (str, optional) – Directory to cache lightkurve downloads. Lightkurve will place the fits files in the default lightkurve cache path in your home directory.