3.4. The Command Line Interface (CLI) execution mode

The Phosphoros software can be executed with the command line interface (CLI). After starting Phosphoros (see the Download and Installation section), any Phosphoros process is launched with the Phosphoros main command. The syntax is as follows:

> Phosphoros <action> <action parameters>

where action is a keyword which refers to a specific Phosphoros executable, and action parameters refers to the options related to the action (executable).

The Phosphoros command (without parameters or with --help) shows the available actions:

> Phosphoros

A help message for each available action can be displayed with:

> Phosphoros <action> --help

Actions have a long and a short name, e.g. compute_model_grid or CMG.

3.4.1. CLI: Configuration files

The list of options (action parameters) for a comand line (action) can be quite long. The best option is to use a configuration file, i.e. a file that includes:

  1. all the action parameters required to run the Phosphoros executable;

  2. the action parameters that users want to modify with respect to the default values.

A configuration file is provided to Phosphoros with the generic config-file option:

> Phosphoros <action> --config-file=<path>/<filename>

where <path> refers to the path with respect to the directory where the action is launched. For example, the following command will compute the grid of models using the PhosphorosComputeModelGrid.conf configuration file located in the config directory:

> Phosphoros CMG --config-file=$PHOSPHOROS_ROOT/config/PhosphorosComputeModelGrid.conf

We suggest .conf as extension in configuration files, although it is not mandatory (the software will accept any other specified extension).

Tip

Users can copy the system configuration files and modify them, but the most convenient approach is to use the GUI to output configuration files. The GUI can be conveniently used to enter all options in an interactive mode and to save them in configuration files. Configuration files produced with the GUI can also be copied, pasted and edited for small changes.

Note

Any command line option takes precedence over the equivalent option provided through a configuration file.

If not specified by the user, Phosphoros first looks for configuration files into the default directory:

> $PHOSPHOROS_ROOT/config

and it will use configuration files that match the exact expected names (see sections below). When Phosphoros cannot find the appropriate file there, it will pick up the system configuration files located at:

> /path_to_PhosphorosCore_installation_directory/conf/PhzExecutables/

The /path_to_PhosphorosCore_installation_directory path will vary in different system installations. Use the following shell command to find the installation directory:

> find / "conf/PhzExecutables" -name "PhosphorosComputeRedshifts.conf" 2>/dev/null

3.4.2. CLI: Mapping filters to column names

In order to map filter trasmission curve files to catalog column names, Phosphoros reads an ASCII file named filter_mapping.txt, located in the following directory:

> $PHOSPHOROS_ROOT/IntermediateProducts/<Catalog Type>/

This file contains the filename of filter transmission curves, and the corresponding column names of flux and flux error inside the input catalog. It also includes additional information such as the flux-error ratio, the flux/Mag index and the name of filter shift columns (see GUI: Mapping filters to column names and Filter Mapping Format for more details). The file is read by the compute_redshift action (see below).

In the same directory, there is also the error_adjustment_param.txt file that contains the coefficients of Eq. (3.1) used to re-calibrate flux errors.

These files can be easily generated by the GUI or created by the user, providing it is located at the right place of the Phosphoros directory structure.

3.4.3. CLI: Generating the grid of models

The photometry model grid can be generated using the compute_model_grid (or simply CMG) action, which calls the PhosphorosComputeModelGrid C++ executable. The list of command line options can be displayed as follows:

> Phosphoros compute_model_grid  (or CMG)  --help

The easiest way to proceed is to provide action parameters through a configuration file. Phosphoros reads by default the following file:

> $PHOSPHOROS_ROOT/config/PhosphorosComputeModelGrid.conf

A complete and fully documented PhosphorosComputeModelGrid.conf file is available as part of the installed software in the following location below the installation directory (see here):

> /path_to_PhosphorosCore_installation_directory/conf/PhzExecutables/

Configuration files, different from the default one, can be selected through the --config-file option (we remind that the Phosphoros GUI can be used to save the parameter space specifications in a configuration file).

Let’s see an example of configuration file for the CMG action:

phosphoros-root=/home/phosphoros/Phosphoros
thread-no=6
cosmology-hubble-constant=67.74
cosmology-omega-lambda=0.6911
cosmology-omega-m=0.3089

filter-name=DECAM/g
filter-name=DECAM/i
filter-name=DECAM/r
filter-name=DECAM/z
filter-name=EUCLID_DC1/vis
filter-name=vista/H
filter-name=vista/J
filter-name=vista/Y

normalization-filter=DECAM/r
normalization-solar-sed=solar_spectrum
catalog-type=Challenge2

igm-absorption-type=MADAU

sed-group-Elliptical Galaxies=CosmosEll
sed-name-Elliptical Galaxies=CosmosSp/S0_A_0
sed-group-Spiral Galaxies=CosmosSp
sed-exclude-Spiral Galaxies=CosmosSp/S0_A_0
sed-group-Star Burst Galaxies=CosmosSB

reddening-curve-name-Elliptical Galaxies=calzetti
reddening-curve-name-Spiral Galaxies=SMC_prevot
reddening-curve-name-Star Burst Galaxies=SB_calzetti

ebv-value-Elliptical Galaxies=0.000000
ebv-value-Elliptical Galaxies=0.100000
ebv-range-Spiral Galaxies=0.000000 0.050000 0.010000
ebv-range-Spiral Galaxies=0.050000 0.300000 0.050000
ebv-range-Spiral Galaxies=0.300000 1.000000 0.100000
ebv-range-Star Burst Galaxies=0.000000 0.050000 0.010000
ebv-range-Star Burst Galaxies=0.050000 0.300000 0.050000
ebv-range-Star Burst Galaxies=0.300000 1.000000 0.100000

z-range-Elliptical Galaxies=0.000000 6.000000 0.050000
z-range-Spiral Galaxies=0.000000 6.000000 0.050000
z-range-Star Burst Galaxies=0.000000 6.000000 0.050000

In the first part of the list we find generic specifications such as: the Phosphoros root directory; the number of threads to use; the name of filter files; the values of cosmological parameters. They are optional and, if not specified, default values are used. The following parameters are instead mandatory and must be specified by users: the name of the catalog type (catalog-type); the name of the filter file (normalization-filter) and of the solar SED file (normalization-solar-sed) used for template normalization (see SED normalization).

The prescription for the IGM absorption correction is selected through the igm-absorption-type option. If the option is not present (or =OFF), no correction is applied.

The parameter space specification starts with the SED template specification. The syntax sed-group-Elliptical Galaxies=CosmoEll means that the Elliptical Galaxies group contains all SED templates found in the CosmoEll directory. With the prefix sed-name-, a single SED (here CosmosSp/S0_A_0) is also added to that group.

A particular SED can be excluded from a group with the prefix sed-exclude-, as shown in the above example.

Reddening curve specifications follow the same syntax as SED templates, with the prefix reddening-curve-.

Note

The same SED template or reddening curve can be contained in multiple groups, provided that there are no grid cells with the same model parameters.

Note

By default, the model grid output is a binary file. However, it can be written in ASCII by setting the option output-model-grid-format=TEXT (see Intermediate Products). The name of the output can be choosen by output-model-grid=<name>.

As shown in the example, the \(E_{(B-V)}\) and redshift specifications for each SED group are entered using the following prefixes:

ebv-value-*
ebv-range-*
z-value-*
z-range-*

The *value-* prefix must be followed by a single value, but it can be repeat multiple times with different values (in the example, \(E_{(B-V)}\) values for the Elliptical Galaxies group are 0 and 0.1). The *range-* prefix must be completed with the start, stop, step triplet. Multiple ranges of values are allowed providing they do not overlap.

3.4.4. CLI: Computing Redshifts

Photometric redshifts are computed by the compute_redshift (or CR) action, which calls the PhosphorosComputeRedshift C++ executable. Again, the list of command line options can be displayed through the --help option.

Action parameters can be passed with a configuration file through the --config-file action parameter. If not specified, Phosphoros reads by default the configuration file

> $PHOSPHOROS_ROOT/config/PhosphorosComputeRedshift.conf

A complete and fully documented PhosphorosComputeRedshift.conf is available as part of the installed software in the following location below the installation directory (see here):

/path_to_PhosphorosCore_installation_directory/conf/PhzExecutables/PhosphorosComputeRedshift.conf

A configuration file for the PhosphorosComputeRedshift executable can be generated by the Phosphoros GUI using the Save Config. File button in the Compute Redshift panel (see the GUI: Computing Redshifts section).

Here below, an example of configuration file:

phosphoros-root=/home/phosphoros/Phosphoros
thread-no=6

normalization-filter=DECAM/r
normalization-solar-sed=solar_spectrum

cosmology-hubble-constant=67.74
cosmology-omega-lambda=0.6911
cosmology-omega-m=0.3089

catalog-type=Challenge2
input-catalog-file=Challenge2TrainingSmallCatalog.fits
source-id-column-name=OBJECT_ID
missing-photometry-flag=-99
enable-upper-limit=YES
upper-limit-use-threshod-flag=-99
model-grid-file=Grid_Chalenge2_Parameter_Space_1_MADAU.dat

phz-output-dir=/home/phosphoros/Phosphoros/Results/Challenge2/Challenge2TrainingSmallCatalog
output-catalog-format=FITS
copy-columns=<list of input catalog columns>
create-output-best-likelihood-model=NO
create-output-best-model=YES

Along with generic specifications (such as the Phosphoros root directory, cosmological parameters, etc.), the configuration file requires information on the input/output catalogs:

  1. Input: the name of the catalog type and of input catalog (with specifications for the source ID column, for missing data and upper limits), and the name of the model grid file. In addition, input catalog options give the possibility:

    • to process only a chunk of the input catalog by excluding the first n sources (input-skip-head=<n>) and by stopping after n sources (input-process-max=<n>);

    • to fix the redshift of sources by providing the column of the input catalog containing the redshift (fixed-redshift-column=<column name>);

    • to exclude filters (exclude-filter=<list of filters>).

  2. Ouput: the directory where the output catalog will be located, plus some specifications about what outputs are computed and stored, and their format. The name of the output catalog is by default phz_cat, with the extension according to the selected format.

    In the above example, only the parameters of the best posterior model are stored in the output file. If users want to save the posterior 1D PDF of redshift, for example, it is enough to add the option create-output-pdf=Z (EBV, REDDENING-CURVE or SED for the other parameters). Finally, in order to store the multi-dimensional posterior distribution, the full-PDF-samplig option must be present in the configuration file: full-PDF-samplig=YES for the sampling of the distribution, NO for the full grid (see GUI: Compute Redshift and File Format: Outputs).

The configuration file for the compute_redshift action can be much more complex than the one shown here when advanced functionalities of Phosphoros are applied (such as priors, Galactic absorption correction, etc.). Action parameters for these funtionalities will be described in the Advanced Features chapter.