Command line arguments

Below are descriptions of the command line arguments available for MOSFiT.

mosfit

Fit astrophysical transients.

usage: mosfit [-h] [--language [LANGUAGE]] [--events EVENTS [EVENTS ...]]
              [--models [MODELS]]
              [--parameter-paths PARAMETER_PATHS [PARAMETER_PATHS ...]]
              [--walker-paths WALKER_PATHS [WALKER_PATHS ...]]
              [--max-time MAX_TIME]
              [--limiting-magnitude LIMITING_MAGNITUDE [LIMITING_MAGNITUDE ...]]
              [--prefer-fluxes] [--time-list TIME_LIST [TIME_LIST ...]]
              [--extra-dates DATE_LIST [DATE_LIST ...]]
              [--extra-mjds MJD_LIST [MJD_LIST ...]]
              [--extra-jds JD_LIST [JD_LIST ...]]
              [--extra-phases PHASE_LIST [PHASE_LIST ...]]
              [--band-list BAND_LIST [BAND_LIST ...]]
              [--band-systems BAND_SYSTEMS [BAND_SYSTEMS ...]]
              [--band-instruments BAND_INSTRUMENTS [BAND_INSTRUMENTS ...]]
              [--band-bandsets BAND_BANDSETS [BAND_BANDSETS ...]]
              [--band-sampling-points BAND_SAMPLING_POINTS]
              [--exclude-bands EXCLUDE_BANDS [EXCLUDE_BANDS ...]]
              [--exclude-instruments EXCLUDE_INSTRUMENTS [EXCLUDE_INSTRUMENTS ...]]
              [--exclude-systems EXCLUDE_SYSTEMS [EXCLUDE_SYSTEMS ...]]
              [--exclude-sources EXCLUDE_SOURCES [EXCLUDE_SOURCES ...]]
              [--exclude-kinds EXCLUDE_KINDS [EXCLUDE_KINDS ...]]
              [--fix-parameters USER_FIXED_PARAMETERS [USER_FIXED_PARAMETERS ...]]
              [--release-parameters USER_RELEASED_PARAMETERS [USER_RELEASED_PARAMETERS ...]]
              [--iterations [ITERATIONS]] [--generative]
              [--smooth-times [SMOOTH_TIMES]]
              [--extrapolate-time [EXTRAPOLATE_TIME [EXTRAPOLATE_TIME ...]]]
              [--limit-fitting-mjds LIMIT_FITTING_MJDS LIMIT_FITTING_MJDS]
              [--output-path OUTPUT_PATH] [--suffix SUFFIX]
              [--num-walkers NUM_WALKERS] [--num-temps NUM_TEMPS]
              [--no-fracking] [--no-write] [--quiet] [--cuda]
              [--no-copy-at-launch] [--force-copy-at-launch] [--offline]
              [--prefer-cache] [--frack-step FRACK_STEP] [--burn BURN]
              [--post-burn POST_BURN]
              [--slice-sampler-steps SLICE_SAMPLER_STEPS] [--upload]
              [--run-until-converged [RUN_UNTIL_CONVERGED]]
              [--run-until-uncorrelated [RUN_UNTIL_UNCORRELATED]]
              [--maximum-walltime MAXIMUM_WALLTIME]
              [--maximum-memory MAXIMUM_MEMORY] [--seed SEED]
              [--draw-above-likelihood [DRAW_ABOVE_LIKELIHOOD]] [--gibbs]
              [--save-full-chain] [--print-trees]
              [--set-upload-token [SET_UPLOAD_TOKEN]]
              [--ignore-upload-quality] [--test]
              [--variance-for-each VARIANCE_FOR_EACH [VARIANCE_FOR_EACH ...]]
              [--speak [SPEAK]] [--version]
              [--extra-outputs [EXTRA_OUTPUTS [EXTRA_OUTPUTS ...]]]
              [--catalogs CATALOGS [CATALOGS ...]] [--no-guessing]
              [--open-in-browser] [--exit-on-prompt]
              [--download-recommended-data] [--local-data-only]
              [--method {ensembler,ultranest,dynesty}]
              [--cache-path CACHE_PATH]

-h, --help

show this help message and exit

--language <language>

Language for output text.

--events <events>, -e <events>

List of event names (or file names) to be fit, delimited by spaces. If an event name contains a space, enclose the event’s name in double quote marks, e.g. “SDSS-II SN 5944”. Files with .json extensions are presumed to be in Open Catalog format, whereas files with any other extension will be read as a list of event names.

--models <models>, -m <models>

List of models to use to fit against the listed events. The model can either be a name of a model included with MOSFiT, or a path to a custom model JSON file generated by the user.

--parameter-paths <parameter_paths>, -P <parameter_paths>

Paths to parameter files corresponding to each model file; length of this list should be equal to the length of the list of models

--walker-paths <walker_paths>, -w <walker_paths>

List of paths to Open Catalog format files with walkers from which to draw initial walker positions. Output data from MOSFiT can be loaded with this command. If some variables are not contained within the input file(s), they will instead be drawn randomly from the specified model priors.

--max-time <max_time>

Set the maximum time for model light curves to be plotted until.

--limiting-magnitude <limiting_magnitude>, -l <limiting_magnitude>

Assumed limiting magnitude of a simulated survey. When enabled, model light curves will be randomly drawn and assigned error bars. If passed one argument, that number will be used as the limiting magnitude (default: 20). If provided a second argument, that number will be used for observation-to-observation variance in the limit.

--prefer-fluxes

If magnitudes and fluxes exist for the same observation(s), prefer the flux representation over the magnitude representation.

--time-list <time_list>, --extra-times <time_list>

List of additional times to generate light curves at. Times can either be specified as dates in YYYY-MM-DD format, MJDs, JDs, or a time relative to the observed maximum (indiciated by prepending a +/- to each time). More specific flags that presume one of these date formats (rather than attempting to guess) are –extra-dates, –extra-mjds, –extra-jds, and –extra-phases.

--extra-dates <date_list>

List of additional times to generate light curves at. Times can either be specified as dates in YYYY-MM-DD format, MJDs, JDs, or a time relative to the observed maximum (indiciated by prepending a +/- to each time). More specific flags that presume one of these date formats (rather than attempting to guess) are –extra-dates, –extra-mjds, –extra-jds, and –extra-phases.

--extra-mjds <mjd_list>

List of additional times to generate light curves at. Times can either be specified as dates in YYYY-MM-DD format, MJDs, JDs, or a time relative to the observed maximum (indiciated by prepending a +/- to each time). More specific flags that presume one of these date formats (rather than attempting to guess) are –extra-dates, –extra-mjds, –extra-jds, and –extra-phases.

--extra-jds <jd_list>

List of additional times to generate light curves at. Times can either be specified as dates in YYYY-MM-DD format, MJDs, JDs, or a time relative to the observed maximum (indiciated by prepending a +/- to each time). More specific flags that presume one of these date formats (rather than attempting to guess) are –extra-dates, –extra-mjds, –extra-jds, and –extra-phases.

--extra-phases <phase_list>

List of additional times to generate light curves at. Times can either be specified as dates in YYYY-MM-DD format, MJDs, JDs, or a time relative to the observed maximum (indiciated by prepending a +/- to each time). More specific flags that presume one of these date formats (rather than attempting to guess) are –extra-dates, –extra-mjds, –extra-jds, and –extra-phases.

--band-list <band_list>, --extra-bands <band_list>

List of additional bands to plot when plotting model light curves that are not being matched to actual transient data.

--band-systems <band_systems>, --extra-systems <band_systems>

List of photometric systems corresponding to the bands listed in –band-list.

--band-instruments <band_instruments>, --extra-instruments <band_instruments>

List of instruments corresponding to the bands listed in –band-list.

--band-bandsets <band_bandsets>, --extra-bandsets <band_bandsets>

List of bandsets corresponding to the bands listed in –band-list.

--band-sampling-points <band_sampling_points>

Number of wavelengths to sample in each band when modeling photometry.

--exclude-bands <exclude_bands>

List of bands to exclude in fitting.

--exclude-instruments <exclude_instruments>

List of instruments to exclude in fitting corresponding to the bands listed in –exclude-bands.

--exclude-systems <exclude_systems>

List of systems to exclude in fitting corresponding to the bands listed in –exclude-bands.

--exclude-sources <exclude_sources>

List of references to exclude data from when fitting. These are specified using the source ID number that is shown on the Open Astronomy Catalog page for each transient.

--exclude-kinds <exclude_kinds>

List of kinds of observations to exclude when fitting. These are specified using keywords such as radio or x-ray.

--fix-parameters <user_fixed_parameters>, -F <user_fixed_parameters>

Pairs of parameter names and values to fix for the current fit. Example: -F kappa 1.0 vejecta 1.0e4 would fix the kappa and vejecta parameters to those values. If the second value is recognized to be an existing key, the whole list will be assumed to just be a list of keys and the default values specified in the model JSON files will be used. If the name is a parameter class (e.g. covariance), all variables of that class will be fixed.

--release-parameters <user_released_parameters>, -r <user_released_parameters>

Parameter names and values to released for the current fit. Example: -r codeltatime would release the codeltatime parameter, allowing the parameter to vary as specified in the model JSON files. If the name is a parameter class (e.g. covariance), all variables of that class will be released.

--iterations <iterations>, -i <iterations>

Number of iterations to run emcee for, including burn-in and post-burn iterations. Setting this option to 0 (or providing no argument) will only draw walker positions and immediately exit.

--generative, -G

Run in generative mode, which draws random parameter combinations from either the priors or a provided input walker file from a prior MOSFiT run. Equivalent to setting -i 0.

--smooth-times <smooth_times>, --plot-points <smooth_times>, -S <smooth_times>

Add this many more fictitious observations between the first and last observed times. Setting this value to 0 (or providing no argument) will guarantee that all observed bands/instrument/system combinations have a point at all observed epochs, but no other times. A negative value will only yield model predictions at the observations but at no other times (faster but sparser light curves).

--extrapolate-time <extrapolate_time>, -E <extrapolate_time>

Extend model light curves this many days before/after first/last observation. Can be a list of two elements, in which case the first element is the amount of time before the first observation to extrapolate, and the second element is the amount of time before the last observation to extrapolate. Value is set to 0.0 days if option not set, 100.0 days by default if no arguments are given.

--limit-fitting-mjds <limit_fitting_mjds>, -L <limit_fitting_mjds>

Only include observations with MJDs within the specified range, e.g. -L 54123 54234 will exclude observations outside this range. If specified without an argument, any upper limit observations before the last upper limit before the first detection in a given band will not be included in the fitting.

--output-path <output_path>, -o <output_path>

Set the base path for all MOSFiT outputs.

--suffix <suffix>, -s <suffix>

Append custom string to output file name to prevent overwrite.

--num-walkers <num_walkers>, -N <num_walkers>

Number of walkers to use in emcee. When fitting, this must be set to at least twice the total number of free parameters within the model, not setting this parameter will set it to this minimum.

--num-temps <num_temps>, -T <num_temps>

Number of temperatures to use in the parallel-tempered emcee sampler. -T 1 is equivalent to the standard EnsembleSampler.

--no-fracking

Setting this flag will skip the fracking step of the optimization process.

--no-write

Do not write any results to disk.

--quiet

Print minimal output upon execution. Don’t display our amazing logo :-(

--cuda

Enable CUDA for MOSFiT routines. Requires the scikit-cuda package (and its dependencies) to be installed.

--no-copy-at-launch

Setting this flag will prevent MOSFiT from copying the user file hierarchy (models/modules/jupyter) to the current working directory before fitting.

--force-copy-at-launch

Setting this flag will force MOSFiT to overwrite the user file hierarchy (models/modules/jupyter) to the current working directory. User will be prompted before being allowed to run with this flag.

--offline

MOSFiT will only use cached data and will not attempt to use any online resources.

--prefer-cache

MOSFiT will prefer to use cached data and will only use online resources if they are not available locally.

--frack-step <frack_step>, -f <frack_step>

Set the number of MCMC steps between fracking runs.

--burn <burn>, -b <burn>

Burn in the chains for this many iterations. During burn-in, global optimization (“fracking”), replacement, and a Gibbs variant of emcee are used to speed convergence. However, as none of these methods preserve detailed balance, the posteriors obtained during the burn-in phase are very approximate. No convergence information will be displayed during burn-in.

--post-burn <post_burn>, -p <post_burn>

Run emcee this many more iterations after the burn-in phase. The burn-in phase will thus be run for (i - p) iterations, where i is the total number of iterations set with -i and p is the value of this parameter.

--slice-sampler-steps <slice_sampler_steps>, -SSS <slice_sampler_steps>

Number of slice sampling steps for ultranest. If not positive, use rejection sampling methods.

--upload, -u

Upload results of MOSFiT to appropriate Open Catalog. If MOSFiT is only supplied with -u and no other arguments, it will upload the results of the latest run.

--run-until-converged <run_until_converged>, -R <run_until_converged>

Run each model until it has converged. This parameter has different meanings depending on the sampler used: For the ensembler, this parameter corresponds to the PSRF [Default: 1.1]. For the dynesty, this parameter controls both the initial dlogz in the static phase of the sampling and the KL-divergence criterion in the dynamic phase of the sampling [Default: 0.02]. This will run beyond the specified number of iterations, and is recommended when the –upload/-u flag is set.

--run-until-uncorrelated <run_until_uncorrelated>, -U <run_until_uncorrelated>

Run each model until the autocorrelation time is measured accurately and chain has burned in for the specified number of autocorrelation times [Default: 10.0]. This will run beyond the specified number of iterations, and is recommended when the –upload/-u flag is set.

--maximum-walltime <maximum_walltime>, -W <maximum_walltime>

Total execution time (in seconds) constrained to be no greater than this value.

--maximum-memory <maximum_memory>, -M <maximum_memory>

Maximum memory MOSFiT is allowed to use, in megabytes. The memory use is roughly estimated, so it is best to set this number at least 1 GB below your system’s actual memory limit per CPU.

--seed <seed>

Set a random seed (must be an integer) to use for this run. Affects random draws in samplers, only guaranteed to yield identical output for serial (i.e. single processor) runs.

--draw-above-likelihood <draw_above_likelihood>, -d <draw_above_likelihood>

When randomly drawing walkers initially, do not accept a draw unless a likelihood value is greater than this value. By default, any score greater than the likelihood floor will be retained.

--gibbs, -g

Using a Gibbs-sampling variant of emcee. This is not proven to preserve detailed balance, however it has much faster convergence than the vanilla emcee stretch-move. Use with caution.

--save-full-chain, -c

Save the full chain for each model fit.

--print-trees

Print the full dependency trees of each model.

--set-upload-token <set_upload_token>

Set the upload token. If given an argument, expects a 64-character token. If given no argument, MOSFiT will prompt the user to provide a token.

--ignore-upload-quality

Ignore all quality checks when uploading fits.

--test

Alters the printing of output messages such that a new line is generated with each message. Users are unlikely to need this parameter; it is included as Travis requires new lines to be produed to detected program output.

--variance-for-each <variance_for_each>

Create a separate Variance for each type of observation specified. Currently band is the only valid option, with a trailing numeric value indicating the maximum fractional difference in wavelength for two bands to be grouped.

--speak <speak>

Speak.

--version

Print MOSFiT version info.

--extra-outputs <extra_outputs>, -x <extra_outputs>

Extra keys to save alongside the default model outputs.

--catalogs <catalogs>, -C <catalogs>

Restrict data acquisition to the listed catalogs.

--no-guessing

< Message “parser_no_guessing” not found [] >

--open-in-browser, -O

Open the events listed with -e in the user’s web browser one at a time.

--exit-on-prompt

Exit immediately if any user prompts are encountered (useful for batch jobs).

--download-recommended-data

Downloads any recommended data from the Open Catalogs if not provided by the user (without prompting).

--local-data-only

Will not attempt to acquire any data from the Open Catalogs (even from cache), using only data provided locally by the user.

--method {ensembler,ultranest,dynesty}, -D {ensembler,ultranest,dynesty}

Method for computing posteriors. Current options are ensembler, ultranest and dynesty.

--cache-path <cache_path>

Alternative path to store cached data, rather than default of installation directory.