soprano.scripts.nmr

CLI to extract and process NMR-related properties from .magres files.

TODO: add support for different shift {Haeberlen,NQR,IUPAC}and quadrupole {Haeberlen,NQR} conventions. TODO: check if df is too wide to fit in window – if so, split into multiple plots. TODO: spinsys output is not yet implemented. TODO: document config file setup

REFACTORED NMR_EXTRACRT ETC., NEED TO MAKE SURE THE OTHER CLI COMMANDS STILL WORK

Functions

build_nmr_df(atoms, fname[, isotopes, ...])	Build the dataframe containing the NMR properties.
check_equivalent_sites_ms(atoms, tags[, ...])	Check if the sites with the same tags have the same MS isotropy to within a tolerance.
get_efg_summary(atoms, isotopes, ...)	For an Atoms object with EFG tensor arrays, return a summary of the tensors.
get_ms_summary(atoms, euler_convention[, ...])	For an Atoms object with ms tensor arrays, return a summary of the tensors.
label_atoms(atoms)
merge_tagged_sites(atoms_in[, ...])	Merge sites that are tagged with the same tag.
nmr_extract_atoms(atoms[, subset, reduce, ...])	Extract NMR data from a single ASE Atoms object.
nmr_extract_multi(files[, merge, logger, ...])	Extract NMR data from magres file(s).
tag_functional_groups(average_group, atoms)	Average over groups of atoms based on the average_group string.

soprano.scripts.nmr.build_nmr_df(atoms, fname, isotopes={}, references={}, gradients={}, properties=['efg', 'ms'], euler_convention='zyz', logger=<Logger cli (WARNING)>)

Build the dataframe containing the NMR properties.

Parameters:

• atoms (ASE Atoms object) – the atoms object to be reloaded.

• fname (str) – the filename of the file being processed.

• all_selections (AtomSelection) – the AtomSelection object containing all selections.

• isotopes (dict) – dictionary of isotopes to use for each element. e.g. {‘H’: 2, ‘C’: 13}

• references (dict) – dictionary of shielding references for each element. e.g. {‘H’: 20.0, ‘C’: 100.0}

• gradients (dict) – dictionary of gradients for each element. e.g. {‘H’: -1.0, ‘C’: -0.95} defaults to {} == -1 for all elements.

• average_group (str) – string of comma-separated patterns to average over. e.g. ‘CH3,CH2’

• properties (list) – list of properties to extract. e.g. [‘efg’, ‘ms’]

• euler_convention (str) – the euler convention to use for the EFG tensor. Options are ‘zyz’ or ‘zxz’

• logger (Logger)

Returns:

the dataframe containing the NMR properties.

Return type:

df (pandas DataFrame)

soprano.scripts.nmr.check_equivalent_sites_ms(atoms, tags, tolerance=0.001)

Check if the sites with the same tags have the same MS isotropy to within a tolerance.

Parameters:

• atoms (Atoms) – the Atoms object

• tags (list) – the tags to check

• tolerance (float, optional) – the tolerance. Defaults to 1e-3.

Returns:

True if the sites are equivalent, False otherwise

Return type:

bool

soprano.scripts.nmr.get_efg_summary(atoms, isotopes, euler_convention)

For an Atoms object with EFG tensor arrays, return a summary of the tensors.

Parameters:

• atoms (Atoms) – the Atoms object

• isotopes (dict) – the isotopes to use for the quadrupolar constants

• euler_convention (str) – the euler convention to use

Returns:

a dictionary with the summary of the EFG tensors

Return type:

dict

soprano.scripts.nmr.get_ms_summary(atoms, euler_convention, references=None, gradients=None)

For an Atoms object with ms tensor arrays, return a summary of the tensors.

Parameters:

• atoms (Atoms) – the Atoms object

• euler_convention (str) – the euler convention to use

• references (dict, optional) – the reference tensors. Defaults to None. e.g. {‘C’: 100}

• gradients (dict, optional) – the gradient tensors. Defaults to None. e.g. {‘C’: -1}

Returns:

a dictionary with the summary of the ms tensors

Return type:

dict

soprano.scripts.nmr.merge_tagged_sites(atoms_in, merging_strategies={})

Merge sites that are tagged with the same tag.

Parameters:

• atoms (Atoms) – Atoms object. Must have tags.

• merging_strategies (dict) – dictionary of merging strategies. See merge_sites for more details.

• atoms_in (Atoms)

Return type:

Atoms

soprano.scripts.nmr.nmr_extract_atoms(atoms, subset='', reduce=True, average_group='', merging_strategies={'labels': <function <lambda>>, 'positions': <function <lambda>>}, symprec=0.0001, logger=<Logger cli (WARNING)>)

Extract NMR data from a single ASE Atoms object.

Parameters:

• atoms (Atoms) – the Atoms object to extract data from.

• subset (str) – subset of atoms to extract data from. e.g. “H1,H2,C” for all H1, H2 and C atoms.

• reduce (bool) – whether to reduce to symmetry equivalent sites (using either the CIF labels or symmetry operations found using SPGLIB).

• average_group (str) – comma-separated list of functional groups to average over e.g. methyl groups. e.g. “CH3” averages over H atoms in methyl groups.

• merging_strategies (dict) – dictionary of merging strategies to use for each property. e.g. {“positions”: lambda x: x[0]}.

• symprec (float) – tolerance for symmetry operations. Default is 1e-4.

• logger (logging.Logger) – logger to use for logging. If not provided, we use the default logger for the cli.

Returns:

the (subset of the) Atoms object with the extracted data.

Return type:

atoms (Atoms)

soprano.scripts.nmr.nmr_extract_multi(files, merge=False, logger=None, sortby=None, sort_order='ascending', isotopes={}, references={}, gradients={}, properties=['efg', 'ms'], euler_convention='zyz', include=[], exclude=[], query='', **kwargs)

Extract NMR data from magres file(s). See CLI help for more details on the arguments. (soprano nmr –help)

Parameters:

• files (list) – list of magres files to extract data from.

• merge (bool) – whether to merge the pandas dataframes from more than one .magres file.

• logger (logging.Logger) – logger to use for logging. If None, a new logger is created.

• sortby (str) – column to sort the dataframe by.

• sort_order (str) – order to sort the dataframe by. Options are ‘ascending’ or ‘descending’.

• isotopes (dict) – dictionary of isotope labels to use for each element. e.g. {“H”: “1H”, “C”: “13C”}.

• references (dict) – dictionary of shielding reference values to use for each element. e.g. {“H”: 30.0, “C”: 100.0}.

• gradients (dict) – dictionary of gradient reference values to use for each element. e.g. {“H”: -1.0, “C”: -0.95}. If not provided, the gradient is assumed to be -1 for all elements.

• properties (list) – list of properties to extract. Options are ‘efg’, ‘ms’.

• euler_convention (str) – convention to use for Euler angles. Options are ‘zyz’ or ‘zxz’.

• include (str) – comma-separated list of columns to include in the output.

• exclude (str) – comma-separated list of columns to exclude from the output.

• query (str) – query string to filter the dataframe.

Expected kwargs:

subset (str): subset of atoms to extract data from. e.g. “H1,H2,C” for all H1, H2 and C atoms. reduce (bool): whether to reduce to symmetry equivalent sites (using either the CIF labels or symmetry operations found using SPGLIB). average_group (str): comma-separated list of functional groups to average over e.g. methyl groups. e.g. “CH3” averages over H atoms in methyl groups. merging_strategies (dict): dictionary of merging strategies to use for each property. e.g. {“positions”: lambda x: x[0]}. symprec (float): tolerance for symmetry operations. Default is 1e-4.

Returns:

list of pandas DataFrames containing the extracted data. images (list): list of ASE Atoms objects containing the crystal structures.

Return type:

dfs (list)

soprano.scripts.nmr.tag_functional_groups(average_group, atoms, vdw_scale=1.0)

Average over groups of atoms based on the average_group string. See find_XHn_groups for more details.

Parameters:

• average_group (str) – string of comma-separated patterns to average over. e.g. ‘CH3,CH2’

• atoms (Atoms) – Atoms object

• vdw_scale (float) – scaling factor for the van der Waals radii. Default is 1.0.

Returns:

Atoms

Return type:

Atoms