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’.