The isoenum API Reference¶

This package provides routines to generate isotopically-resolved InChI (International Chemical Identifier) from non-isotopically labeled CTfile formatted files (e.g. Molfiles, SDfiles) or non-isotopically labeled InChI identifiers.

This package includes the following modules:

cli: This module provides the command-line interface for the isoenum package.
api: This module provides routines to augment CTfile objects with additional information and used by isoenum package CLI.
labeling: This module provides functions for generating a labeling schema.
nmr: This module provides descriptions of coupling combinations that could be observed within NMR experiments.
openbabel: This module provides functions to call the Open Babel software to convert between InChI and CTfile formatted files.
conf: This module provides the processing of configuration files necessary for isotopic enumerator.
fileio: This module provides functions for generating CTfile objects and convert CTfile objects into InChI.
utils: This module provides reusable utility functions.
exceptions: This module provides isoenum package custom exceptions.

isoenum.cli¶

Isotopic enumerator (isoenum) command-line interface

Usage:

isoenum -h | –help

isoenum –version

isoenum name (<path-to-ctfile-file-or-inchi-file-or-inchi-string>): [–specific=<isotope:element:position>…] [–all=<isotope:element>…] [–enumerate=<isotope:element:min:max>…] [–complete | –partial] [–ignore-iso] [–format=<format>] [–output=<path>] [–verbose]
isoenum ionize (<path-to-ctfile-file-or-inchi-file-or-inchi-string>): (–state=<element:position:charge>…) [–format=<format>] [–output=<path>]
isoenum nmr (<path-to-ctfile-file-or-inchi-file-or-inchi-string>): [–type=<experiment-type>] [–jcoupling=<name>…] [–decoupled=<element>…] [–format=<format>] [–output=<path>] [–subset] [–verbose]
isoenum vis (<path-to-ctfile-file-or-inchi-file-or-inchi-string>): (–format=<format>) (–output=<path>)

Options:

`-h, --help`	Show this screen.
`--verbose`	Print more information.
`-v, --version`	Show version.
`-a, --all=<isotope:element>`
	Specify element and isotope, e.g. -a 13:C or –all=13:C
`-s, --specific=<isotope:element:position>`
	Specify element, isotope and specific position, e.g. -s 13:C:1 or –specific=13:C:1.
`-e, --enumerate=<isotope:element:min:max>`
	Enumerate all isotopically-resolved CTfile or InChI, e.g. -e 13:C:2:4 or –enumerate=13:C:2:4
`-c, --complete`	Use complete labeling schema, i.e. every atom must specify “ISO” property, partial labeling schema will be used otherwise for specified labeling information only.
`-p, --partial`	Use partial labeling schema, i.e. generate labeling schema from the provided labeling information.
`-i, --ignore-iso`
	Ignore existing “ISO” specification in the CTfile or InChI.
`-f, --format=<format>`
	Format of output: inchi, mol, sdf, csv, json [default: inchi].
`-o, --output=<path>`
	Path to output file.
`-t, --type=<experiment-type>`
	Type of NMR experiment [default: 1D1H].
`-j, --jcoupling=<type>`
	Allowed J couplings.
`-d, --decoupled=<element>`
	Turn off J coupling for a given element.
`-z, --state=<element:position:charge>`
	Create ionized form of InChI from neutral molecule, e.g. N:6:+1, O:8:-1.
`--subset`	Create atom subsets for each resonance.

isoenum.cli.cli(cmdargs)[source]¶

Process command-line arguments.

Parameters:	cmdargs (dict) – Command-line arguments.
Returns:	None.
Return type:	`None`

isoenum.cli.save_output(outputstr, path, file_format)[source]¶

Save output results into file or print to stdout.

Parameters:	outputstr (str) – Output string. path (str) – Where to save results. file_format (str) – File format to create file extension.
Returns:	None.
Return type:	`None`

isoenum.cli.create_output(sdfile, path=None, file_format='inchi')[source]¶

Create output containing conversion results.

Parameters:	sdfile (`SDfile`.) – `SDfile` instance. path (str) – Path to where file will be saved. file_format (str) – File format: ‘inchi’, ‘mol’, ‘sdf’, ‘json’, or ‘csv’.
Returns:	None.
Return type:	`None`

isoenum.labeling¶

This module contains a function to generate a labeling schema based on provided cli parameters.

isoenum.labeling.create_labeling_schema(complete_labeling_schema, ignore_existing_isotopes, all_iso, specific_iso, existing_iso, enumerate_iso, isotopes_conf, ctfile)[source]¶

Create labeling schema.

Parameters:	complete_labeling_schema (bool) – Specifies if default isotopes to be added to isotopic layer. ignore_existing_isotopes (bool) – Specifies if will ignore existing isotopic layer. all_iso (dict) – Atom specific isotopes –all option. specific_iso (dict) – Atom number specific isotopes from –specific option. existing_iso (dict) – Atom number specific isotopes from `Molfile`. enumerate_iso (list) – List of isotopes from –enumerate option. isotopes_conf (dict) – Default isotopes. ctfile (`Molfile`) – Instance of `Molfile`.
Returns:	Labeling schema.
Return type:	`list`

isoenum.nmr¶

This module provides descriptions of coupling combinations that could be observed within NMR experiments.

class isoenum.nmr.ResonanceAtom(atom, isotope)[source]¶: Resonance atom - part of the coupling path.

class isoenum.nmr.Coupling(coupling_path=None, nmr_active_atoms=None, subset_atoms=None)[source]¶

Coupling provides information on the connectivity of molecules.

coupling_type¶

Coupling type.

Returns:	Coupling type.
Return type:	`str`

subset¶

Generate coupling path subsets.

Returns:	Coupling path subsets.
Return type:	`list`

is_resonance_compatible(resonance)[source]¶

Test if coupling is compatible with resonance.

Parameters:	resonance (`Coupling`) – Subclass of `Coupling`.
Returns:	True if compatible, False otherwise.
Return type:	`True` or False

classmethod couplings(atom)[source]¶

Generate list of possible couplings for a given atom type.

Parameters:	atom (`ctfile.Atom`) – Atom type.
Returns:	List of couplings.
Return type:	`list`

name¶

Specific coupling name that indicates interacting atoms.

Returns:	Specific coupling name.
Return type:	`str`

hydrogen_coupling_path¶

Coupling path that consists of hydrogen atoms.

Returns:	Coupling path.
Return type:	`list`

hydrogen_coupling_path_repr¶

Hydrogen coupling path representation.

Returns:	List of hydrogen groups representing hydrogen coupling path.
Return type:	`list`

class isoenum.nmr.J1CH(coupling_path=None, nmr_active_atoms=None, subset_atoms=None)[source]¶

J1CH coupling type: C-H.

couplings(carbon_atom)[source]¶

Generate list of possible J1CH couplings.

Parameters:	carbon_atom – Carbon atom.
Returns:	List of couplings.
Return type:	`list`

class isoenum.nmr.J2HH(coupling_path=None, nmr_active_atoms=None, subset_atoms=None)[source]¶

J2HH coupling type: H-C-H.

couplings(carbon_atom)[source]¶

Generate list of possible J2HH couplings.

Parameters:	carbon_atom – Carbon atom.
Returns:	List of couplings.
Return type:	`list`

class isoenum.nmr.J3HH(coupling_path=None, nmr_active_atoms=None, subset_atoms=None)[source]¶

J3HH coupling type: H-C-C-H.

couplings(carbon_atom)[source]¶

Generate list of possible J3HH couplings.

Parameters:	carbon_atom – Carbon atom.
Returns:	List of couplings.
Return type:	`list`

is_resonance_compatible(resonance)[source]¶

Test if J3HH coupling is compatible with resonance.

Parameters:	resonance (`Coupling`) – Subclass of `Coupling`.
Returns:	True if compatible, False otherwise.
Return type:	`True` or False

class isoenum.nmr.HResonance(coupling_path=None, nmr_active_atoms=None, subset_atoms=None)[source]¶

Hydrogen resonance.

couplings(carbon_atom)[source]¶

Generate resonance.

Parameters:	carbon_atom – Carbon atom.
Returns:	List of couplings.
Return type:	`list`

class isoenum.nmr.NMRExperiment(name, couplings, decoupled, default_coupling_definitions)[source]¶

NMR experiment.

generate_coupling_combinations(molfile, subset=False)[source]¶: Generate possible J couplings for a Molfile.

class isoenum.nmr.NMR1D1H(name, couplings=None, decoupled=None, default_coupling_definitions=(HResonance(coupling_path=None), J1CH(coupling_path=None), J2HH(coupling_path=None), J3HH(coupling_path=None)))[source]¶

1D 1H NMR experiment.

generate_coupling_combinations(molfile, subset=False)[source]¶

Generate 1D 1H NMR experiment J couplings for a Molfile.

Parameters:	molfile (`ctfile.Molfile`) – `Molfile` object. subset (`True` or `False`) – Generate couplings subsets?
Returns:	List of possible couplings for a given `Molfile`.
Return type:	`list`

class isoenum.nmr.NMR1DCHSQC(name, couplings=None, decoupled=None, default_coupling_definitions=(HResonance(coupling_path=None), J1CH(coupling_path=None), J2HH(coupling_path=None), J3HH(coupling_path=None)))[source]¶: 1D 13C HSQC NMR experiment.

isoenum.nmr.create_nmr_experiment(name, couplings=None, decoupled=None)[source]¶

Create NMR experiment upon provided experiment type.

Parameters:	name (str) – NMR experiment type. couplings (list) – List of coupling types. decoupled (list) – List of elements.
Returns:	NMR experiment.
Return type:	`NMRExperiment`.

isoenum.conf¶

This module provides processing of configuration files necessary for isotopic enumerator.

isoenum.fileio¶

This module provides routines to generate CTfile objects and convert CTfile objects into InChI and vice versa.

isoenum.fileio.create_ctfile(path_or_id, xyx_coordinates='--gen2D', explicit_hydrogens='-h')[source]¶

Guess what type of path is provided, i.e. is it existing file in Molfile format, existing file in SDfile file format, existing file containing InChI string, or InChI string and tries to create CTfile object.

Parameters:	path_or_id (str) – Path to `Molfile`, `SDfile`, `InChI`, or `InChI` string. xyx_coordinates (str) – Option that generates x, y, z coordinates (e.g., “–gen2D” or “–gen3D”). explicit_hydrogens (str) – Option that makes hydrogens atoms explicit when generating `CTfile` object.
Returns:	Subclass of `CTfile` object.
Return type:	`Molfile` or `SDfile`

isoenum.fileio.create_ctfile_from_ctfile_str(ctfile_str)[source]¶

Create CTfile object from CTfile string.

Parameters:	ctfile_str (str) – `CTfile` string.
Returns:	Subclass of `CTfile` object.
Return type:	`CTfile`

isoenum.fileio.create_ctfile_from_identifier_file(path, output_format='mol', **options)[source]¶

Create CTfile instance from InChI or SMILES identifier file.

Parameters:	path (str) – Path to file containing `InChI` or `SMILES` identifier. output_format (str) – Output file format used by Open Babel to generate `CTfile`. options – Additional options to be passed to Open Babel.
Returns:	Subclass of `CTfile` object.
Return type:	`CTfile`

isoenum.fileio.create_ctfile_from_identifier_str(identifier_str, output_format='mol', **options)[source]¶

Create CTfile instance from InChI or SMILES identifier string.

Parameters:	identifier_str (str) – `InChI` or `SMILES` identifier string. output_format (str) – Output file format used by Open Babel to generate `CTfile`. options – Additional options to be passed to Open Babel.
Returns:	Subclass of `CTfile` object.
Return type:	`CTfile`

isoenum.fileio.guess_identifier_format(identifier_str)[source]¶

Guess identifier format.

Parameters:	identifier_str (str) – Chemical identifier string.
Returns:	‘inchi’ or ‘smiles’ string.
Return type:	`str`

isoenum.fileio.create_inchi_from_ctfile_obj(ctf, **options)[source]¶

Create InChI from CTfile instance.

Parameters:	ctf (`CTfile`) – Instance of `CTfile`.
Returns:	`InChI` string.
Return type:	`str`

isoenum.fileio.normalize_ctfile_obj(ctf, xyx_coordinates='--gen2D', explicit_hydrogens='-h')[source]¶

Normalize CTfile object.

Parameters:	ctf (`CTfile`) – `CTfile` object.
Returns:	Normalized `CTfile` object.
Return type:	`CTfile`

isoenum.fileio.create_empty_sdfile_obj()[source]¶

Create empty SDfile object.

Returns:	`SDfile` object.
Return type:	`SDfile`

isoenum.fileio.create_empty_molfile_obj()[source]¶

Create empty Molfile object.

Returns:	`Molfile` object.
Return type:	`Molfile`

isoenum.fileio.create_svg_str(inchi_str, **options)[source]¶

Create SVG string from InChI identifier string.

Parameters:	inchi_str (str) – `InChI` identifier. options – Additional options to be passed to Open Babel.
Returns:	SVG XML code.
Return type:	`str`

isoenum.fileio.circular_consistency_test(inchi_str)[source]¶

Perform conversion from InChI string to Molfile and back to InChI string.

Parameters:	inchi_str (str) – `InChI` string.
Returns:	None
Return type:	`None`

isoenum.utils¶

This module provides reusable utility functions.

isoenum.utils.is_url(path)[source]¶

Test if path represents a valid URL.

Parameters:	path (str) – Path to file.
Returns:	True if path is valid url string, False otherwise.
Return type:	`True` or `False`

isoenum.utils.all_combinations(items)[source]¶

Generate combinations of variable size.

Parameters:	items – Sequence of items.
Returns:	List of all combinations.
Return type:	`list`

isoenum.openbabel¶

This module provides convert() to convert between different file formats used in molecular modeling and computational chemistry (e.g. InChI, SMILES, Molfile, etc.).

isoenum.openbabel.convert(input_file_path, output_file_path, input_format, output_format, **options)[source]¶

Convert between formats using Open Babel.

Parameters:	input_file_path (str) – Path to input file. output_file_path (str) – Path to output file. input_format (str) – Input file format. output_format (str) – Output file format. options – Additional key-value options to pass to Open Babel.
Returns:	None.
Return type:	`None`

isoenum.exceptions¶

Custom exceptions.

exception isoenum.exceptions.EmptyCTFileError[source]¶: Invalid CTFile object error.