Standalone settings

You have now completed the Quickstart example. But what options are available to run SMURFS? Below you can find a full list of settings available through the terminal. If you are interested in some examples, you can take a look at those as well. Mandatory parameters are noted as such, the optional ones give you the default as well. Call smurfs -h to show a help message, explaining all parameters.

Positional arguments are required for every run of SMURFS. Named parameters can be used as explained below

usage: smurfs [-h] [-fr FREQUENCYRANGE] [-ssa] [-sc] [-ef EXTENDFREQUENCIES]
              [-fd FREQUENCYDETECTION] [-imf {all,end,none}]
              [-fm {scipy,lmfit}] [-ft {PDCSAP,SAP,PSF}] [-pca] [-psf] [-so]
              [-sp SAVEPATH] [-i] [-m {Kepler,TESS,K2}] [-cl SIGMACLIP]
              [-it ITERS] [-ac] [--version]
              target snr windowSize

Positional Arguments

target

This parameter represents the target analyzed by SMURFS. This parameter is rather vague, to give you the maximum amount of flexibility. Either you can provide any name of a star (resolvable through Simbad) that has been observed by TESS/Kepler/K2. You can also provide a filename through this parameter.

If you choose to do the the first, the code prioritizes TESS over all other missions (if you don’t provide the mission parameter), and SC over LC observations. It then checks MAST if there are SC observations from TESS for this star. If there are, it uses lightkurve.search_lightcurvefile to download those. If there are none, it checks if there are LC observations from TESS and uses Eleanor to extract the light curves from the FFIs. If there are None, it searches all other missions for light kurves of this object.If you choose another mission, it will call lightkurve.search_lightcurvefile for this specific mission.

If you choose to provide a file through this parameter, make sure that you follow these conventions:

  • The file must be an ASCII file

  • The first column must contain the time stamps

  • The second column must contain the flux

  • If a third column exists, SMURFS will assume that these are the uncertainties in the flux.

SMURFS will take the file as is and won’t apply any corrections to it, if you don’t use the apply_corrections flag. It then assumes that the flux values are in magnitude and varying around 0, that the time stamps are in days and that the data set is properly reduced.

snr

This parameter represents the lower bound signal to noise ratio any frequency must have. SMURFS computes the SNR by taking the amplitude of an individual frequency (as defined by the amplitude in the frequency spectrum). Next, it applies half of the window size to either side of the frequency, starting by the next adjacent minima, and takes the mean of this window as the noise surrounding the frequency. The ratio of these two values is the resulting SNR for an individual frequency. By default, SMURFS stops its run when the first frequency less than this value has been found

windowSize

The window size used to get the SNR for a given frequency. SMURFS defines the window as half of the given value on each side of the peak in the periodogram, starting from the first minima next to the peak.

Named Arguments

-fr, --frequencyRange

Setting this parameter, allows you to restrict the analysis of a time series to a given range in the frequency spectrum. This might be useful, if yo have a lot of high amplitude noise in another part of the spectrum, than the one you might be interested in. Provide the parameter in the form 0,100.

Default: “None,None”

-ssa, --skipSimilarFrequencies

Ignores regions where SMURFS finds multiple frequencies within a small range. This can happen due to insufficient fits or signals that are hard to fit.

Default: False

-sc, --skipCutoff

By default, SMURFS stops the extraction of frequencies if it finds 10 frequencies in a rowthat have a standard deviation of <0.05, as it assumes it can’t work itself out of this region. You can override this behaviour by setting this flag. Be aware, that this might lead to unknown behaviour. Usually, instead of setting this flag, it is better to set the -ssa flag

Default: False

-ef, --extendFrequencies

Extends the analysis by n frequencies. By default, SMURFS stops when it finds the first insignificant frequency. Setting this parameter requires SMURFS to find n insignificant frequencies in a row.

Default: 0

-fd, --frequencyDetection

If this value is set, a found frequency is compared to the original periodogramm. If the ratio between the amplitude of the found frequency and the maximum in the range of the found frequency on the original periodogram is lower than the set value, it will ignore this frequency range going forward.

-imf, --improveFitMode

Possible choices: all, end, none

This parameter defines the way SMURFS uses a Period04 like improvement of frequencies. You can set the following modes:

  • all: Tries to refit all found frequencies after every frequeny that is found. This is the usual behaviour of Period04 and the default setting.

  • end: Improves the frequencies after SMURFS would stop its run

  • none: Disables the improve frequencies setting. This can be useful if you find a lot of frequencies and the run would take an unnecessary amount of time

Default: “all”

-fm, --fitMethod

Possible choices: scipy, lmfit

SMURFS implements two different fitting libraries: Either it uses scipy (scipy.optimize.curve_fit) or lmfit (lmfit Model fit). Choosing one over the other might lead to different results, so if you have find an unexpected result, try to switch the fitting mode.

Default: “lmfit”

-ft, --fluxType

Possible choices: PDCSAP, SAP, PSF

The TESS mission gives its end users different data products to choose, if you download them directly from MAST. You can pass the type of data product you like using this parameter. For the SC data, where the light curve is preprocessed by SPOC, you can choosetwo different products:

  • SAP flux: SAP is the simple aperture photometry flux (resulting light curve is the flux after summing the calibrated pixels within the TESS optimal aperture)

  • PDCSAP flux: PDCSAP is the Pre-search Data conditioned Simple aperture photometry, which is corrected using co-trending basis vectors.

By default we use the PDCSAP flux, but you can also choose another one if you like.

If your target is only observed in LC mode, SMURFS also provides these two modes (these have a slightly different meaning, their result is however equivalent to the SC SAP and PDSCAP fluxes, see the Eleanor documentation). However, in LC mode you have also the PSF flux type, which models a point spread function for a given star. The validation page generated when SMURFS extracts a target from a FFI always shows the SAP and the chosen flux to compare. You might want to try different settings, depending on your use case

Default: “PDCSAP”

-pca, --do_pca

Activates the PCA analysis (aperture × TPF + background subtraction + cotrending basis vectors). This doesn’t change the data you are trying to analyze, but shows the PDSCAP flux in the validation page. Only applicable when using LC data.

Default: False

-psf, --do_psf

Activates the PSF analysis. This adds point spread function modelling to the extraction of light curves from FFIs. This doesn’t change the data you are trying to analyze, but shows the PSF flux in the validation page. Only applicable when using LC data.

Default: False

-so, --storeObject

If this flag is set, the SMURFS object is stored in the results. You can later use this object to load the _result into a python file using ‘Smurfs.from_path’. Allows you to easily access all convenience functions from SMURFS.

Default: False

-sp, --savePath

Allows you to set the save path of the analysis. By default it will save it in the same folder, where the module was called.

Default: “.”

-i, --interactive

Using this flag will automatically start an iPython shell. This allows for direct interaction with the result using the ‘star’ object. You can then access all convenience functions directly (like plotting, the FrequencyFinder object, etc).

Default: False

-m, --mission

Possible choices: Kepler, TESS, K2

Three different missions are available: Kepler,TESS,K2. You can choose the mission by setting this value. By default, only TESS missions are considered

Default: “TESS”

-cl, --sigmaClip

Sets the sigma for the sigma clipping. Default is 4.

Default: 4

-it, --iters

Sets the iterations for the sigma clipping. Default is 1.

Default: 1

-ac, --apply_corrections

If this flag is set, correction (sigma clipping, conversion to magnitude) are applied to files. Make sure that your flux is in electron counts if you use this flag.

Default: False

--version

Shows version of SMURFS