Introduction
As we have alluded to throughout the documentation, pySYD was intended to be used through
its command-line interface (CLI) – which means that the software is specifically optimized
for this usage and therefore most options probably have the best defaults already
set. Here, “best” just means that the defaults work best for most stars.
However, that does not necessarily mean that your star(s) or setting(s) are expected to conform or adhere to these settings. In fact, we recommend playing around with some of the settings to see how it affects the results, which might help build your intuition for seismic analyses.
Note
Please keep in mind that, while we have extensively tested a majority of our options, we are
continuously adding new ones which ultimately might break something. If this happens, we
encourage you to submit an issue here
and thank you in advance for helping make pySYD even better!
CLI help
To give you a glimpse into the insanely large amount of available options, open up a terminal
window and enter the help command for the main pipeline execution (run aka pysyd.pipeline.run),
since this mode inherits all command-line parsers.
$ pysyd run --help
usage: pySYD run [-h] [--in str] [--infdir str] [--out str] [-s] [-o] [-v]
[--cli] [--notebook] [--star [str [str ...]]] [--file str]
[--info str] [--gap int] [-x] [--of int] [-k]
[--dnu [float [float ...]]] [--le [float [float ...]]]
[--ue [float [float ...]]] [-n] [-e] [-j] [--def str]
[--sw float] [--bin float] [--bm str] [--step float]
[--trials int] [-a] [--lx [float [float ...]]]
[--ux [float [float ...]]] [-b] [--basis str] [--bf float]
[--iw float] [--rms int] [--laws int] [-w] [--metric str]
[--lb [float [float ...]]] [--ub [float [float ...]]] [-g]
[--numax [float [float ...]]] [--lp [float [float ...]]]
[--up [float [float ...]]] [--ew float] [--sm float]
[--sp float] [-f] [--thresh float] [--peak int] [--mc int]
[-m] [--all] [-d] [--cm str] [--cv float] [-y] [-i]
[--nox int] [--noy str] [--npb int] [--se float]
optional arguments:
-h, --help show this help message and exit
This was actually just a teaser!
If you ran it from your end, you probably noticed an output that was a factor of ~5-10 longer! It may seem like an overwhelming amount but do not fret, this is for good reason – and that’s to make your asteroseismic experience as customized as possible.
Currently pySYD has four parsers: the parent_parser for high-level functionality, the
data_parser for anything related to data loading and manipulation, the main_parser for
everything related to the core analyses, and the plot_parser for (yes, you guessed it!)
plotting. In fact, the main parser is so large that comprises four subgroups, each related to
the corresponding steps in the main pipeline execution. BTW see here
for more information on which parsers a given pipeline mode inherits.
Sections
Note: as you are navigating this page, keep in mind that we also have a special glossary for all our command-line options. This includes everything from the variable type, default value and relevant units to how it’s stored within the software itself. There are glossary links at the bottom of every section for each of the parameters discussed within that subsection.
High-level functionality
aka the parent_parser
All pySYD modes inherent the parent_parser and therefore, mostly pertains to paths and
how you choose to run the software (i.e. save files and if so, whether or not to overwrite
old files with the same extension, etc.)
--in str, --input str, --inpdir str
Input directory
--infdir str Path to relevant pySYD information
--out str, --outdir str, --output str
Output directory
-s, --save Do not save output figures and results.
-o, --overwrite Overwrite existing files with the same name/path
-v, --verbose turn on verbose output
--cli Running from command line (this should not be touched)
--notebook Running from a jupyter notebook (this should not be
touched)
Glossary terms (alphabetical order): –cli, –file, –in, –info, –information, –inpdir, –input, –list, –notebook, -o, –out, –overwrite, -s, –save, –outdir, –output, –todo, -v, –verbose
Data analyses
aka the data_parser
The following features are primarily related to the input data and when applicable, what tools to apply to the data. All data manipulation relevant to this step happens prior to any pipeline analyses. Currently this is mostly frequency-domain tools but we are working on implementing time-domain tools as well!
--star [str [str ...]], --stars [str [str ...]]
list of stars to process
--file str, --list str, --todo str
list of stars to process
--info str, --information str
list of stellar parameters and options
--gap int, --gaps int
What constitutes a time series 'gap' (i.e. n x the
cadence)
-x, --stitch, --stitching
Correct for large gaps in time series data by
'stitching' the light curve
--of int, --over int, --oversample int
The oversampling factor (OF) of the input power
spectrum
-k, --kc, --kepcorr Turn on the Kepler short-cadence artefact correction
routine
--dnu [float [float ...]]
spacing to fold PS for mitigating mixed modes
--le [float [float ...]], --lowere [float [float ...]]
lower frequency limit of folded PS to whiten mixed
modes
--ue [float [float ...]], --uppere [float [float ...]]
upper frequency limit of folded PS to whiten mixed
modes
-n, --notch another technique to mitigate effects from mixed modes
(not fully functional, creates weirds effects for
higher SNR cases??)
Glossary terms (alphabetical order): –dnu -k, –le, –lowere, –kc, –kepcorr, –of, –over, –oversample, –star, –stars, –stitch, –stitching, –ue, –uppere, -x
Core asteroseismic analyses
aka the main_parser
The main parser holds a majority of the parameters that are relevant to core functions of the software. Since it is so large, it is broken down into four different “groups” which are related to their application.
Search & estimate
The following options are relevant for the first, optional module that is designed to search for power excess due to solar-like oscillations and estimate rough starting points for its main properties.
-e, --est, --estimate
Turn off the optional module that estimates numax
-j, --adjust Adjusts default parameters based on region of
oscillations
--def str, --defaults str
Adjust defaults for low vs. high numax values (e.g.,
smoothing filters)
--sw float, --smoothwidth float
Box filter width (in muHz) for smoothing the PS
--bin float, --binning float
Binning interval for PS (in muHz)
--bm str, --mode str, --bmode str
Binning mode
--step float, --steps float
--trials int, --ntrials int
-a, --ask Ask which trial to use
--lx [float [float ...]], --lowerx [float [float ...]]
Lower frequency limit of PS
--ux [float [float ...]], --upperx [float [float ...]]
Upper frequency limit of PS
Glossary terms (alphabetical order): -a, –ask, –bin, –binning, –bm, –bmode, -e, –est, –estimate, –lowerx, –lx, –mode, –ntrials, –step, –steps, –sw, –smoothwidth, –trials, –upperx, –ux
Background fit
Below is a complete list of parameters relevant to the background-fitting routine:
-b, --bg, --background
Turn off the routine that determines the stellar
background contribution
--basis str Which basis to use for background fit (i.e. 'a_b',
'pgran_tau', 'tau_sigma'), *** NOT operational yet ***
--bf float, --box float, --boxfilter float
Box filter width [in muHz] for plotting the PS
--iw float, --indwidth float
Width of binning for PS [in muHz]
--rms int, --nrms int
Number of points to estimate the amplitude of red-
noise component(s)
--laws int, --nlaws int
Force number of red-noise component(s)
-w, --wn, --fixwn Fix the white noise level
--metric str Which model metric to use, choices=['bic','aic']
--lb [float [float ...]], --lowerb [float [float ...]]
Lower frequency limit of PS
--ub [float [float ...]], --upperb [float [float ...]]
Upper frequency limit of PS
Glossary terms (alphabetical order): -b, –background, –basis, –bf, –bg, –box, –boxfilter, –fixwn, –iw, –indwidth, –laws, –lb, –lowerb, –metric, –nrms, –rms, –nlaws, –ub, –upperb, -w, –wn
Global parameters
All of the following are related to deriving global asteroseismic parameters, numax (\(\rm \nu_{max}\)) and dnu (\(\Delta\nu\)).
-g, --globe, --global
Disable the main global-fitting routine
--numax [float [float ...]]
initial estimate for numax to bypass the forst module
--lp [float [float ...]], --lowerp [float [float ...]]
lower frequency limit for the envelope of oscillations
--up [float [float ...]], --upperp [float [float ...]]
upper frequency limit for the envelope of oscillations
--ew float, --exwidth float
fractional value of width to use for power excess,
where width is computed using a solar scaling
relation.
--sm float, --smpar float
smoothing parameter used to estimate the smoothed
numax (typically before 1-4 through experience --
**development purposes only**)
--sp float, --smoothps float
box filter width [in muHz] of PS for ACF
-f, --fft Use :mod:`numpy.correlate` instead of fast fourier
transforms to compute the ACF
--thresh float, --threshold float
fractional value of FWHM to use for ACF
--peak int, --peaks int, --npeaks int
number of peaks to fit in the ACF
Glossary terms (alphabetical order): –ew, –exwidth, -g, –global, –globe, –lp, –lowerp, –npeaks, –numax, –peak, –peaks, –sm, –smpar, –up, –upperp –dnu, –sp, –smoothps, –thresh
Sampling & uncertainties
All CLI options relevant for the Monte-Carlo sampling in order to estimate uncertainties:
--mc int, --iter int, --mciter int
number of Monte-Carlo iterations to run for estimating
uncertainties (typically 200 is sufficient)
-m, --samples save samples from the Monte-Carlo sampling
Glossary terms (alphabetical order): –iter, -m, –mc, –mciter, –samples
Plotting
aka the plot_parser
Anything related to the plotting of results for any of the modules is in this parser. Its currently a little heavy on the echelle diagram end because this part of the plot is harder to hack, so we tried to make it as easily customizable as possible.
--all, --showall plot background comparison figure
-d, --show, --display
show output figures
--cm str, --color str
Change colormap of ED, which is `binary` by default
--cv float, --value float
Clip value multiplier to use for echelle diagram (ED).
Default is 3x the median, where clip_value == `3`.
-y, --hey plugin for Daniel Hey's echelle package **not
currently implemented**
-i, --ie, --interpech
turn on the interpolation of the output ED
--nox int, --nacross int
number of bins to use on the x-axis of the ED
(currently being tested)
--noy str, --ndown str, --norders str
NEW!! Number of orders to plot pm how many orders to
shift (if ED is not centered)
--npb int NEW!! npb == "number per bin", which is option instead
of nox that uses the frequency resolution and spacing
to compute an appropriate bin size for the ED
--se float, --smoothech float
Smooth ED using a box filter [in muHz]
Glossary terms (alphabetical order): –ce, –cm, –color, –cv, -d, –display, –hey, -i, –ie, –interpech, –nox, –nacross, –ndown, –norders, –noy, –npb, –se, –show, –smoothech, –value, -y
On the next page, we will show applications for some of these options in command-line examples.
We also have our advanced usage page, which is specifically designed to show these in action by providing before and after references. You can also find descriptions of certain commands available in the notebook tutorials.