Command-Line Interface

Note

The EOS command-line interface is completely optional and does not provide any functionality beyond the interactive Python interface.

Although using EOS within an interactive Jupyter notebook on your personal computer or laptop is useful to prototype an analysis, this approach sometimes suffers from limited computing power. To circumvent this problem, you can alternatively

  • use EOS in Jupyter interactively on a remote workstation computer via an SSH tunnel (see the FAQ);

  • use EOS on remote workstations or compute clusters via the command-line interface.

Working in the command-line interface requires that all analyses are defined within an analysis file. For an example of an analysis file see the corresponding section in the user guide. For the description of the file format see the corresponding section in the reference. The following provide a documentation of the command-line interface, which is available through a single script called eos-analysis.

The eos-analysis script provides several subcommands that

  • inspect the analysis file;

  • sample from a posterior density with a variety of methods, including Metroplis-Hastings, Population Monte Carlos, and nested sampling;

  • perform auxiliary tasks on intermediate results.

The output of these commands are stored on disk as directories filled with YAML files (for descriptions and small numerical datasets) and Numpy datafiles (for samples). The datafiles can be access with the classes documented as part of the eos.data module.

usage: eos-analysis [-h]
                    {list-priors,list-likelihoods,list-posteriors,list-predictions,sample-mcmc,sample-pmc,sample-nested,plot-samples,find-mode,mixture-product,find-clusters,predict-observables,corner-plot,validate,report,run,init}
                    ...

Sub-commands

list-priors

Lists the named prior PDFs defined within the scope of this analysis file.

eos-analysis list-priors [-h] [-v] [-f ANALYSIS_FILE]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

list-likelihoods

Lists the named likelihoods defined within the scope of this analysis file.

eos-analysis list-likelihoods [-h] [-v] [-f ANALYSIS_FILE] [-d]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-d, --display-details

Whether to display further details for each likelihood.

list-posteriors

Lists the named posterior PDFs defined within the scope of this analysis file.

eos-analysis list-posteriors [-h] [-v] [-f ANALYSIS_FILE]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

list-predictions

Lists the named prediction sets defined within the scope of this analysis file.

eos-analysis list-predictions [-h] [-v] [-f ANALYSIS_FILE]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

sample-mcmc

Samples from a named posterior PDF using Markov Chain Monte Carlo (MCMC) methods.

The output file will be stored in EOS_BASE_DIRECTORY/POSTERIOR/mcmc-IDX.

eos-analysis sample-mcmc [-h] [-v] [-f ANALYSIS_FILE] [-N N] [-S STRIDE]
                         [-p PRERUNS] [-n PRE_N] [-s START_POINT]
                         [-c COV_SCALE] [-b BASE_DIRECTORY]
                         POSTERIOR CHAIN-IDX

Positional Arguments

POSTERIOR

The name of the posterior PDF from which to draw the samples.

CHAIN-IDX

The index assigned to the Markov chain. This value is used to seed the RNG for a reproducible analysis.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-N, --number-of-samples

The number of samples to be stored in the output file.

-S, --stride

The ratio of samples drawn over samples stored. For every S samples, S - 1 will be discarded.

-p, --number-of-preruns

The number of prerun steps, which are used to adapt the MCMC proposal to the posterior.

-n, --number-of-prerun-samples

The number of samples to be used for an adaptation in each prerun steps. These samples will be discarded.

-s, --start-point

Optional starting point for the chain; a comma separated list of floats

-c, --cov-scale

Scale factor for the initial guess of the covariance matrix.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

sample-pmc

Samples from a named posterior using the Population Monte Carlo (PMC) methods.

The results of the find-cluster command are expected in EOS_BASE_DIRECTORY/POSTERIOR/clusters. The output will be stored in EOS_BASE_DIRECTORY/POSTERIOR/pmc. In addition, an ImportanceSamples object is exported to EOS_BASE_DIRECTORY/POSTERIOR/samples.

eos-analysis sample-pmc [-h] [-v] [-f ANALYSIS_FILE] [-n STEP_N] [-s STEPS]
                        [-t PERPLEXITY_THRESHOLD] [-w WEIGHT_THRESHOLD]
                        [-N FINAL_N] [--pmc_iterations PMC_ITERATIONS]
                        [--pmc-rel-tol PMC_REL_TOL]
                        [--pmc-abs-tol PMC_ABS_TOL] [-l PMC_LOOKBACK]
                        [-p INITIAL_PROPOSAL] [-S SIGMA_TEST_STAT]
                        [-b BASE_DIRECTORY]
                        POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF from which to draw the samples.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-n, --number-of-adaptation-samples

The number of samples to be used in each adaptation step. These samples will be discarded.

-s, --number-of-adaptation-steps

The number of adaptation steps, which are used to adapt the PMC proposal to the posterior.

-t, --perplexity-threshold

The threshold for the perplexity in the last step after which further adaptation steps are to be skipped.

-w, --weight-threshold

Mixture components with a weight smaller than this threshold are pruned.

-N, --number-of-final-samples

The number of samples to be stored in the output file.

--pmc_iterations

The maximum number of update of the PMC, changing this value may make the update unstable

--pmc-rel-tol

Relative tolerance of the PMC update.

--pmc-abs-tol

Absolute tolerance of the PMC update.

-l, --pmc-lookback

The number of previous steps whose samples are used to update the PMC. 1 (default) means that only last step is used ; 0 means that all available steps are used.

-p, --initial-proposal
Specify where the initial proposal should be taken from; ‘clusters’ (default): use the proposal obtained using find-clusters;

‘product’: use the proposal obtained from mixture_product; ‘pmc’: continue sampling from the previous sample-pmc results.

-S, --sigma-test-stat

If provided, the inverse CDF of -2*log(PDF) will be evaluated, using the provided values as the respective significance.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

sample-nested

Samples from a likelihood associated with a named posterior using dynamic nested sampling.

The output will be stored in EOS_BASE_DIRECTORY/POSTERIOR/nested. In addition, an ImportanceSamples object is exported to EOS_BASE_DIRECTORY/POSTERIOR/samples.

eos-analysis sample-nested [-h] [-v] [-f ANALYSIS_FILE] [-B BOUND] [-n NLIVE]
                           [-d DLOGZ] [-m MAXITER] [-s SEED]
                           [-b BASE_DIRECTORY] [-M SAMPLE]
                           POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF from which to draw the samples.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-B, --target-bound

The method used to approximately bound the prior using the current set of live points. Conditions the sampling methods used to propose new live points. For valid values, see the dynesty documentation.

-n, --number-of-live-points

The number of live points.

-d, --evidence-tolerance

The relative tolerance for the remaining evidence.

-m, --max-number-iterations

The maximum number of iterations. Iterations may stop earlier if the termination condition is reached.

-s, --use-random-seed

The seed used to initialize the Mersenne Twister pseudo-random number generator.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

-M, --sampling-method

The method used for sampling within the likelihood constraints. For valid values, see dynesty documentation.

plot-samples

Plots all samples obtained for a named posterior.

The results of either the sample-mcmc or the sample-pmc command are expected in EOS_BASE_DIRECTORY/POSTERIOR/mcmc-* or EOS_BASE_DIRECTORY/POSTERIOR/pmc, respectively. The plots will be stored as PDF files within the respective sample inputs.

eos-analysis plot-samples [-h] [-v] [-f ANALYSIS_FILE] [-B BINS]
                          [-b BASE_DIRECTORY]
                          POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF from which to draw the samples.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-B, --bins

The number of bins per histogram.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

find-mode

Finds the mode of the named posterior.

The optimization process can be initialised either by a provided parameter point or previously obtained importance samples (recommended), a random point, or from a pre-existing Markov chain with provided index (deprecated). The optimization can be iterated to increase the accuracy of the result. The output will be stored in EOS_BASE_DIRECTORY/posterior/mode-LABEL.

eos-analysis find-mode [-h] [-v] [-f ANALYSIS_FILE] [-o OPTIMIZATIONS]
                       [-c CHAIN] [-S] [-p START_POINT] [-s SEED] [-L LABEL]
                       [-b BASE_DIRECTORY]
                       POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF that will be maximized.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-o, --optimizations

The number of calls to the optimization algorithm.

-c, --from-mcmc

The chain index of an MCMC data file from which the maximization is started, this is now deprecated.

-S, --from-samples

If specified, the optimization will start from the importance samples stored in posterior/samples.

-p, --from-point

The point from which the minimization is started; a comma separated list of floats.

-s, --use-random-seed

The seed used to generate the random starting point of the minimization.

-L, --label

The label used for the generated data file.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

mixture-product

Compute the cartesian product of the densities listed in posteriors. Note that this product is not commutative.

The input densities are read from EOS_BASE_DIRECTORY/POSTERIOR_i/pmc, where POSTERIOR_i is listed in posteriors. The output density will be stored in EOS_BASE_DIRECTORY/POSTERIOR/product.

eos-analysis mixture-product [-h] [-v] [-f ANALYSIS_FILE] [-b BASE_DIRECTORY]
                             POSTERIOR POSTERIORS

Positional Arguments

POSTERIOR

The name of the posterior PDF for which the product is computed

POSTERIORS

The list of name of the posteriors PDF that will be concatenated.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

find-clusters

Finds clusters among posterior MCMC samples, grouped by Gelman-Rubin R value, and creates a Gaussian mixture density.

Finding clusters and creating a Gaussian mixture density is a necessary intermediate step before using the sample-pmc subcommand. The input files are expected in EOS_BASE_DIRECTORY/POSTERIOR/mcmc-*. All MCMC input files present will be used in the clustering. The output files will be stored in EOS_BASE_DIRECTORY/POSTERIOR/clusters.

eos-analysis find-clusters [-h] [-v] [-f ANALYSIS_FILE] [-t THRESHOLD]
                           [-c K_G] [-b BASE_DIRECTORY]
                           POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF from which MCMC samples have previously been drawn.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-t, --threshold

The R value threshold. If two sample subsets have an R value larger than this threshold, they will be treated as two distinct clusters. (default: 2.0)

-c, --clusters-per-group

The number of mixture components per cluster. (default: 1)

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

predict-observables

Predicts a set of observables based on previously obtained importance samples.

The input files are expected in EOS_BASE_DIRECTORY/POSTERIOR/samples. The output files will be stored in EOS_BASE_DIRECTORY/POSTERIOR/pred-PREDICTION.

eos-analysis predict-observables [-h] [-v] [-f ANALYSIS_FILE] [-B BEGIN]
                                 [-E END] [-b BASE_DIRECTORY]
                                 POSTERIOR PREDICTION

Positional Arguments

POSTERIOR

The name of the posterior PDF from which to draw the samples.

PREDICTION

The name of the set of observables to predict.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-B, --begin-index

The index of the first sample to use for the predictions.

-E, --end-index

The index beyond the last sample to use for the predictions.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

corner-plot

Generate a corner plot of the 1-D and 2-D marginalized posteriors.

The input files are expected in EOS_BASE_DIRECTORY/POSTERIOR/samples. The output files will be stored in EOS_BASE_DIRECTORY/POSTERIOR/plots.

eos-analysis corner-plot [-h] [-v] [-f ANALYSIS_FILE] [-B BEGIN] [-E END]
                         [-b BASE_DIRECTORY]
                         POSTERIOR

Positional Arguments

POSTERIOR

The name of the posterior PDF from which the samples were drawn.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-B, --begin-parameter

The index of the first parameter to plot.

-E, --end-parameter

The index beyond the last parameter to plot.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

validate

Validates the analysis file by checking that all posteriors and all prediction sets can be created.

eos-analysis validate [-h] [-v] [-f ANALYSIS_FILE]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

report

Generates a report of the analysis based on the analysis file and the recorded results.

eos-analysis report [-h] [-v] [-f ANALYSIS_FILE] [-b BASE_DIRECTORY]
                    [-o OUTPUT_FILE]
                    TEMPLATE

Positional Arguments

TEMPLATE

The file name of the template that is used to generate the report.

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

-o, --output-file

The file name of the output report. If not provided, the report will be printed to the console.

run

Runs a list of subcommands based on the pre-recorded steps defined within an analysis.

eos-analysis run [-h] [-v] [-f ANALYSIS_FILE] [-b BASE_DIRECTORY] [-d]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.

-b, --base-directory

The base directory for the storage of data files. Can also be set via the EOS_BASE_DIRECTORY environment variable.

-d, --dry-run

Perform a dry run only. Outputs the list of subcommands that would be run instead of running them.

init

Initializes a new analysis directory based on the EOS analysis template.

eos-analysis init [-h] [-v] [-f ANALYSIS_FILE]

Named Arguments

-v, --verbose

Increases the verbosity of the script

-f, --analysis-file

The analysis file. Defaults to ‘analysis.yaml’.