Command Line Interface

Command Line Interface#

soprano#

A CLI tool to streamline common soprano tasks. It has various subcommands, each of which has its own set of options and help.

soprano [OPTIONS] COMMAND [ARGS]...

Options

-v, --verbosity <LVL>#

Either CRITICAL, ERROR, WARNING, INFO or DEBUG

Author: J. Kane Shenton (kane.shenton@stfc.ac.uk)

Last updated: June 21, 2023

dipolar#

Extract and summarise dipolar couplings from structure files.

Usage: soprano dipolar seedname.{magres|cif|POSCAR|etc}

soprano dipolar [OPTIONS] FILES...

Options

-c, --config <config>#

Read option defaults from the specified INI fileIf not set, first checks environment variable: SOPRANO_CONFIG and then ~/.soprano/config.ini

Default:

'/home/runner/.soprano/config.ini'

-v, --verbosity#

Increase verbosity. Use -v for info, -vv for debug. Defaults to only showing warnings and errors.

--view#

If present, view the structure(s) with the ASE GUI.Note that the ASE GUI can color the sites according to their tags. This can be used to see what sites were tagged as equivalent.

--symprec <symprec>#

Symmetry precision for symmetry reduction. Defaults to 1e-4.

--precision <precision>#

Precision of the output (number of decimal places). Defaults to 3.

-i, --isotopes <ISOTOPES>#

Isotopes specification (e.g. -i 13C for carbon 13 -i 2H,15N for deuterium and 15N). When nothing is specified it defaults to the most common NMR active isotope.

-g, --average-group <average_group>#

Group pattern for averaging. Currently only works for XHn groups such as CH3, CH2, NH2 etc. You can specify several, comma separated as in -g CH3,CH2,NH2. If not specified, no averaging is performed.

-i, --select_i <selection_i>#

Selection string of subset of sites include. e.g. -s C for only and all carbon atoms, -s C.1-3,H.1.2 for carbons 1,2,3 and hydrogens 1 and 2, -s C1,H1a,H1b for any sites with the labels C1, H1a and H1b.

-j, --select_j <selection_j>#

Selection string of subset of sites include. e.g. -s C for only and all carbon atoms, -s C.1-3,H.1.2 for carbons 1,2,3 and hydrogens 1 and 2, -s C1,H1a,H1b for any sites with the labels C1, H1a and H1b.

--rss#

Calculate the dipolar constant Root Sum Square for each atom in a system (includes periodicity).(As opposed to the dipolar couplings between pairs of atoms).Default is False.

--cutoff <rss_cutoff>#

Cutoff for Dipolar constant Root Sum Square for each atom in a system (includes periodicity). Units are Angstroms. Default is 5.0 Angstroms.

--isonuclear#

Include only dipolar interactions between atoms of the same type.Default is False.

-f, --output-format <output_format>#

Output file format. If not specified, the format is guessed from output filename extension.If specified, it overrides the output filename extension.The txt, tsv and dat formats all produce tab separated files.The md format produces a markdown table and requires an optional dependency on the tabulate package.

Options:

csv | json | html | md | tex | txt | tsv | dat | xls | xlsx

-o, --output <output>#

Output file name. If not specified, output is printed to stdout.If the output file name has a recognised extension (see --output-format for allowed values), the format is guessed from that.The format can be overridden with the --output-format option.

-m, --merge#

If present, merge all files into a single output file.

--sortby <sortby>#

Sort by column. Defaults to sorting by site number. It can be any column in the output. For example --sortby EFG_Vzz

--sort-order <sort_order>#

Sort order. Defaults to ascending.

Options:

ascending | descending

--include <include>#

Include only certain columns. The columns are specified as a comma-separated list. For example --include MS_shielding,EFG_Vzz. Defaults to all columns.

--exclude <exclude>#

Exclude certain columns. The columns are specified as a comma-separated list. For example --exclude MS_alpha,MS_beta,MS_gamma. Defaults to None.

--query <query>#

Filter results based on query. The filter is specified as a pandas query. Note that you must enclose the query in quotes! Refer to the column names without the units. For example --query 'MS_shielding > 100'. You can combine queries with and and or etc. e.g. --query 'MS_shielding > 100 and MS_shielding < 180'. Defaults to no filter.

Arguments

FILES#

Required argument(s)

nmr#

Extract and analyse NMR data from magres file(s).

Usage: soprano nmr seedname.magres

Processes .magres file(s) containing NMR-related properties and prints a summary. It defaults to printing all NMR properties present in the file for all the atoms.

See the below arguments for how to extract specific information.

soprano nmr [OPTIONS] FILES...

Options

-c, --config <config>#

Read option defaults from the specified INI fileIf not set, first checks environment variable: SOPRANO_CONFIG and then ~/.soprano/config.ini

Default:

'/home/runner/.soprano/config.ini'

-v, --verbosity#

Increase verbosity. Use -v for info, -vv for debug. Defaults to only showing warnings and errors.

--view#

If present, view the structure(s) with the ASE GUI.Note that the ASE GUI can color the sites according to their tags. This can be used to see what sites were tagged as equivalent.

--symprec <symprec>#

Symmetry precision for symmetry reduction. Defaults to 1e-4.

--precision <precision>#

Precision of the output (number of decimal places). Defaults to 3.

-p, --properties <properties>#

Properties for which to extract and summarise e.g. -p ms. They can be combined by using the flag multiple times: -p ms -p efg. Defaults to both ms and efg.

Options:

efg | ms

-i, --isotopes <ISOTOPES>#

Isotopes specification (e.g. -i 13C for carbon 13 -i 2H,15N for deuterium and 15N). When nothing is specified it defaults to the most common NMR active isotope.

-g, --average-group <average_group>#

Group pattern for averaging. Currently only works for XHn groups such as CH3, CH2, NH2 etc. You can specify several, comma separated as in -g CH3,CH2,NH2. If not specified, no averaging is performed.

--reduce, --no-reduce#

Reduce the output by symmetry-equivalent sites. If there are CIF-style labels present, then these override the symmetry-grouping in case of a clash (though there should never be a clash…). Note that this doesn’t take into account magnetic symmetry! Defaults to True, so use --no-reduce to turn off symmetry reduction.

--euler <euler_convention>#

Convention for Euler angles. Defaults to zyz.

Options:

zyz | zxz

--references <references>#

Reference shielding for each element (in ppm). The format is --references C:170,H:123.

--gradients <gradients>#

Reference shielding gradients for each element. Defaults to -1 for all elements. Set it like this: --gradients H:-1,C:-0.97.

-s, --subset <subset>#

Selection string of subset of sites include. e.g. -s C for only and all carbon atoms, -s C.1-3,H.1.2 for carbons 1,2,3 and hydrogens 1 and 2, -s C1,H1a,H1b for any sites with the labels C1, H1a and H1b.

-f, --output-format <output_format>#

Output file format. If not specified, the format is guessed from output filename extension.If specified, it overrides the output filename extension.The txt, tsv and dat formats all produce tab separated files.The md format produces a markdown table and requires an optional dependency on the tabulate package.

Options:

csv | json | html | md | tex | txt | tsv | dat | xls | xlsx

-o, --output <output>#

Output file name. If not specified, output is printed to stdout.If the output file name has a recognised extension (see --output-format for allowed values), the format is guessed from that.The format can be overridden with the --output-format option.

-m, --merge#

If present, merge all files into a single output file.

--sortby <sortby>#

Sort by column. Defaults to sorting by site number. It can be any column in the output. For example --sortby EFG_Vzz

--sort-order <sort_order>#

Sort order. Defaults to ascending.

Options:

ascending | descending

--include <include>#

Include only certain columns. The columns are specified as a comma-separated list. For example --include MS_shielding,EFG_Vzz. Defaults to all columns.

--exclude <exclude>#

Exclude certain columns. The columns are specified as a comma-separated list. For example --exclude MS_alpha,MS_beta,MS_gamma. Defaults to None.

--query <query>#

Filter results based on query. The filter is specified as a pandas query. Note that you must enclose the query in quotes! Refer to the column names without the units. For example --query 'MS_shielding > 100'. You can combine queries with and and or etc. e.g. --query 'MS_shielding > 100 and MS_shielding < 180'. Defaults to no filter.

Arguments

FILES#

Required argument(s)

plotnmr#

Plot the NMR spectrum from a .magres file.

soprano plotnmr [OPTIONS] [FILES]...

Options

-c, --config <config>#

Read option defaults from the specified INI fileIf not set, first checks environment variable: SOPRANO_CONFIG and then ~/.soprano/config.ini

Default:

'/home/runner/.soprano/config.ini'

-v, --verbosity#

Increase verbosity. Use -v for info, -vv for debug. Defaults to only showing warnings and errors.

--view#

If present, view the structure(s) with the ASE GUI.Note that the ASE GUI can color the sites according to their tags. This can be used to see what sites were tagged as equivalent.

--symprec <symprec>#

Symmetry precision for symmetry reduction. Defaults to 1e-4.

--precision <precision>#

Precision of the output (number of decimal places). Defaults to 3.

-i, --isotopes <ISOTOPES>#

Isotopes specification (e.g. -i 13C for carbon 13 -i 2H,15N for deuterium and 15N). When nothing is specified it defaults to the most common NMR active isotope.

-g, --average-group <average_group>#

Group pattern for averaging. Currently only works for XHn groups such as CH3, CH2, NH2 etc. You can specify several, comma separated as in -g CH3,CH2,NH2. If not specified, no averaging is performed.

--euler <euler_convention>#

Convention for Euler angles. Defaults to zyz.

Options:

zyz | zxz

--references <references>#

Reference shielding for each element (in ppm). The format is --references C:170,H:123.

--gradients <gradients>#

Reference shielding gradients for each element. Defaults to -1 for all elements. Set it like this: --gradients H:-1,C:-0.97.

-s, --subset <subset>#

Selection string of subset of sites include. e.g. -s C for only and all carbon atoms, -s C.1-3,H.1.2 for carbons 1,2,3 and hydrogens 1 and 2, -s C1,H1a,H1b for any sites with the labels C1, H1a and H1b.

--reduce, --no-reduce#

Reduce the output by symmetry-equivalent sites. If there are CIF-style labels present, then these override the symmetry-grouping in case of a clash (though there should never be a clash…). Note that this doesn’t take into account magnetic symmetry! Defaults to True, so use --no-reduce to turn off symmetry reduction.

--query <query>#

Filter results based on query. The filter is specified as a pandas query. Note that you must enclose the query in quotes! Refer to the column names without the units. For example --query 'MS_shielding > 100'. You can combine queries with and and or etc. e.g. --query 'MS_shielding > 100 and MS_shielding < 180'. Defaults to no filter.

-p, --plot_type <plot_type>#

Plot type

Options:

2D | 1D

-x, --xelement <x_element>#

Required

-y, --yelement <y_element>#

Element to plot on the y-axis. If not specified, but a 2D plot is requested, the x-element is used.

--rcut <rcut>#

Cutoff distance for plotting. Defaults to 10 Angstrom.

--yaxis-order <yaxis_order>#

Single (1Q) or double (2Q) quantum order for the y-axis. Defaults to 1Q.

Options:

1Q | 2Q

--xlim <xlim>#

X-axis range. For example --xlim 20 100

--ylim <ylim>#

Y-axis range. For example --ylim 20 100

--markers, --no-markers#

Show markers? Default is True.

--marker-symbol <marker_symbol>#

Marker type. For example --marker-symbol o. Accepts any matplotlib marker type.

-ms, --max-marker-size <max_marker_size>#

Maximum marker size. Default is 50.

--marker-linewidth <marker_linewidth>#

Marker linewidth. Default is 0.5.

--scale-marker-by <scale_marker_by>#

Scale marker size by chosen property. fixed means that all the markers will have the same size. distance means that the marker size will be proportional to the distance between the sites. inversedistance means that the marker size will be proportional to the inverse of the distance between the sites. dipolar means that the marker size will be proportional to the dipolar coupling between the sites. Default is fixed.

Options:

fixed | distance | inversedistance | dipolar | jcoupling

--marker-color <marker_color>#

Marker color. Default is ‘C0’.

--legend, --no-legend#

Show marker legend? Default is True.

--diag, --no-diag#

Plot diagonal line if the x and y elements are the same. Defaults to True (i.e. showing the diagonal line).

--grid, --no-grid#

Show grid lines at the axis ticks. Defaults to True (i.e. showing the grid lines).

--connectors, --no-connectors#

Show horizontal connectors between points in the case of a 2Q plot. Defaults to True (i.e. show connectors).

--ticklabels, --no-ticklabels#

Show tick labels. Defaults to True (i.e. showing the tick labels).

--heatmap, --no-heatmap#

Show heatmap? Default is False.

--xbroadening <xbroadening>#

Broadening of the x-axis in ppm. Defaults to 5% of the range. Set to 0 to turn off broadening.

--ybroadening <ybroadening>#

Broadening of the y-axis in ppm. Defaults to 5% of the range. Set to 0 to turn off broadening.

-cmap, --colormap <colormap>#

Colour map for the heatmap. Default is ‘bone’. See https://matplotlib.org/stable/tutorials/colors/colormaps.html for more options. Try adding ‘_r’ to the end of the colormap name to reverse it.

--contour, --no-contour#

Show contour? Default is False.

--contour-levels <contour_levels>#

Number of contour levels. Default is 10.

--contour-color <contour_color>#

Contour color. Default is ‘C1’.

--contour-linewidth <contour_linewidth>#

Contour linewidth. Default is 0.5.

-o, --output <plot_filename>#

Name of the plot file. If not specified, the plot will be displayed in a window. The file extension determines the plot type (svg or pdf recommended).

--shielding#

Force plot shielding (even if references are present). Default is to plot shifts if references are given but shielding if no references given).

Arguments

FILES#

Optional argument(s)

splitmols#

Extract all molecules in a molecular crystal (in any ASE-readable format) and output the in individual structure files.

soprano splitmols [OPTIONS] FILENAME

Options

-s, --seedname <seedname>#

Seedname for the output files. Defaults to the input filename without its extension.

-o, --output-dir <output_dir>#

Output directory for the extracted molecules.

-f, --format <format>#

Output file format for the extracted molecules. This can be any format supported by ASE.

--no-write#

Disable output of the extracted molecules to files.

--cell <cell>#

Redefined unit cell for the extracted molecules. Use double-quotes to pass this option in. For example: `--cell "10.0 10.0 15.0"`. This can be provides as a single float (-> a cubic cell is created with that lattice constant) or as three floats (a b c -> an orthorhombic cell is created with the given side lengths) or as six floats (a b c alpha beta gamma) or as nine floats (a11 a12 a13 a21 a22 a23 a31 a32 a33) for the full unit cell matrix. Units are in Angstroms.

-c, --center, --centre#

Center the extracted molecules in the unit cell.

--vacuum, --vac <vacuum>#

Enforce a minimum vacuum between the extracted molecules and the cell boundaries. Applied in all directions.Only applies if the –center flag is set.See the ASE Atoms.center() documentation for how this works.

--cell-indices, --no-cell-indices#

Use cell indices when outputting the individual structures. This is useful for molecules that are split across periodic boundaries.default is to use the cell-indices.

--vdw-set <vdw_set>#

Set of Van der Waals radii to use. Default is csd S. Alvarez, 2013 (https://doi.org/10.1039/C3DT50599E).

Options:

ase | jmol | csd

--vdw-scale <vdw_scale>#

Scaling factor to apply to the base Van der Waals radii values. Values bigger than one make for more tolerant molecules.

--default-vdw <default_vdw>#

Default Van der Waals radius for species for whom no data is available. Default is 2.0 Angstroms.

--vdw-custom <vdw_custom>#

A comma-separated list of custom Van der Waals radii to use, overriding the existing ones, expressed as: H:1,C:2 etc. Units are in Angstroms.

-v, --verbosity#

Increase verbosity. Use -v for info, -vv for debug. Defaults to only showing warnings and errors.

--view#

If present, view the structure(s) with the ASE GUI.Note that the ASE GUI can color the sites according to their tags. This can be used to see what sites were tagged as equivalent.

Arguments

FILENAME#

Required argument

view#

Visualise the structure(s) in the given file(s) using the ASE GUI.

The user can select atoms to be tagged/hidden using the Soprano selection syntax.

soprano view [OPTIONS] FILES...

Options

-v, --verbosity#

Increase verbosity. Use -v for info, -vv for debug. Defaults to only showing warnings and errors.

-c, --config <config>#

Read option defaults from the specified INI fileIf not set, first checks environment variable: SOPRANO_CONFIG and then ~/.soprano/config.ini

Default:

'/home/runner/.soprano/config.ini'

-g, --average-group <average_group>#

Group pattern for averaging. Currently only works for XHn groups such as CH3, CH2, NH2 etc. You can specify several, comma separated as in -g CH3,CH2,NH2. If not specified, no averaging is performed.

-s, --subset <subset>#

Selection string of subset of sites include. e.g. -s C for only and all carbon atoms, -s C.1-3,H.1.2 for carbons 1,2,3 and hydrogens 1 and 2, -s C1,H1a,H1b for any sites with the labels C1, H1a and H1b.

--reduce, --no-reduce#

Reduce the output by symmetry-equivalent sites. If there are CIF-style labels present, then these override the symmetry-grouping in case of a clash (though there should never be a clash…). Note that this doesn’t take into account magnetic symmetry! Defaults to True, so use --no-reduce to turn off symmetry reduction.

--symprec <symprec>#

Symmetry precision for symmetry reduction. Defaults to 1e-4.

Arguments

FILES#

Required argument(s)