References

Core Graph Utilities (CGU)

Translate

translator(input_format, original_graph, ...)

To translate an input graph from a format/data model to another one

Format Translators

GraphFormatTranslator()	Abstract representation of translators handling graph formats.
GraphFormatTranslator.to_iron(graph)	To translate a graph object of a specific type into an Iron instance.
GraphFormatTranslator.from_iron(graph)	To translate an Iron instance into a graph object of another type.
GraphFormatCatalog()	Class to store the available GraphFormatTranslators

Data Model Converters

DataModelConverter()	Abstract representation of converters handling graph data models.
DataModelConverter.syngraph_to_iron(syngraph)	To translate a SynGraph object into an Iron graph
DataModelConverter.iron_to_syngraph(iron_graph)	To translate an Iron graph into a SynGraph object of the correct type
DataModelCatalog()	Class to store the available GraphFormatTranslators

Iron

Iron()	Class representing a graph in the Internal Representation Of Networks (IRON) format.
Iron.add_node(k, node)	To add a node to an Iron instance.
Iron.add_edge(k, edge)	To add an edge to an Iron instance.
Node(iid, properties, labels)	Class representing a node in an Iron instance.
Edge(iid, a_iid, b_iid, direction, ...)	Class representing an edge in an Iron instance.
Direction(dir_string)	Class representing the direction of an Iron edge.

Syngraph

SynGraph([initiator])	Abstract class implementing the homonym data model as a dictionary of sets.
SynGraph.add_node(nodes_tup)	To add a 'parent' node and its 'children' nodes to a SynGraph instance.
BipartiteSynGraph([initiator])	SynGraph subclass representing a Bipartite (Molecule and ChemicalEquation nodes) SynGraph
MonopartiteReacSynGraph([initiator])	SynGraph subclass representing a Monopartite (ChemicalEquation nodes only) SynGraph
MonopartiteMolSynGraph([initiator])	SynGraph subclass representing a Monopartite (Molecule nodes only) SynGraph

Syngraph Operations

merge_syngraph(list_syngraph)	To merge a list od SynGraph objects in a single graph instance.
remove_reaction_from_syngraph(syngraph, ...)	To remove a reaction (and optionally the possible dangling nodes) from a SynGraph object based on the reaction smiles
add_reaction_to_syngraph(syngraph, ...)	To add a chemical reaction to a SynGraph object
extract_reactions_from_syngraph(syngraph)	To extract the smiles of the chemical reaction included in a SynGraph object in a format suitable for atom mapping

Convert

converter(graph, out_data_model)

To convert a SynGraph object in other types of SynGraph

Route Mining

mine_routes(input_list[, root, ...])

To mine all the routes that can be found in tree obtained by merging the input list of routes.

Interfaces

Workflows

process_routes(input_dict[, output_format, ...])	Function process routed predicted by CASP tools: based on the input arguments, only the selected functionalities are performed. The mandatory start and stop actions are (i) to read a json file containing the routes predicted by a CASP tool, and (ii) to write the routes in an output file. Possible additional actions are: - performing the atom mapping of the reactions involved in the routes - computing route descriptors - computing the distance matrix between the routes - clustering the routes - merging the routes - extracting the reaction strings from the routes.
get_workflow_options([verbose])	Returns the available options for the 'process_routes' function.
WorkflowOutput(routes_list, descriptors, ...)	Class to store the outcome of the 'process_routes' function.

Facade

facade(functionality, routes, **kwargs)	To perform one of the main functionality of the package.
facade_helper([functionality, verbose])	Returns the available facade functions if no input is provided; if the name of a functionality is specified, the available parameters options for it are returned.

Route Evaluation and Metrics (REM)

Route Descriptors

descriptor_calculator(graph, descriptor)	To compute a route descriptor.
RouteDescriptor()	Abstract class for DescriptorCalculator.
RouteDescriptor.compute_descriptor(graph)	To calculate the descriptor for the given graph.
DescriptorsCalculatorFactory()	DescriptorCalculator Factory to give access to the descriptors.

Graph Distance

compute_distance_matrix(syngraphs, ged_method)	To compute the distance matrix of a set of routes.
Ged()	Abstract class for Ged calculators.
Ged.compute_ged(syngraph1, syngraph2, ged_params)	To calculate the Graph Edit Distance for a pair of graphs.
GedFactory()	GED Factory to give access to the GED calculators.
graph_distance_factory(syngraph1, syngraph2, ...)	To compute the graph edit distance between 2 SynGraph objects

Clustering

clusterer(syngraphs, ged_method, ...[, ...])	To cluster a list of SynGraph objects based on their graph edit distance
ClusterCalculator()	Definition of the abstract class for ClusterCalculator
ClusterCalculator.get_clustering(...)	To apply the clustering algorithm to the provided distance matrix
ClusterFactory()	Definition of the Cluster Factory to give access to the clustering algorithms.

Cheminfo

Constructors

MoleculeConstructor([...])	Class implementing the constructor of the Molecule class
ChemicalEquationConstructor([...])	Class implementing the constructor of the ChemicalEquation class

Models

Molecule(smiles, ...)	Class holding information of a chemical compound
ChemicalEquation(catalog, role_map, ...)	Dataclass holding information of a chemical reaction
Ratam(full_map_info, atom_transformations, ...)	Dataclass holding information of a reaction atom-to-atom mapping

Atom Mapping

perform_atom_mapping(reactions_list, mapper_name)	To map a list of reaction smiles
MappingOutput(mapped_reactions, ...)	Dataclass to store the results of an atom-to-atom mapping
Mapper()	Abstract class for the atom mappers
Mapper.map_chemical_equations(reactions_list)

Configuration (Settings and Secrets)

For the User

This software needs some configuration setting to function, including some secrets, like authentication details.

We use dynaconf (www.dynaconf.com/) to manage settings and secrets. This tool natively supports a layered approach that sources settings from files in multiple formats and from environment variables.

The package contains some default values for non-secret parameters, encoded into the package source code.

The user can partially or totally override these values by providing a custom settings.yaml file.

By default the program looks into the user home directory (<home_dir>) for a folder that has the name of the package (<package_name>) and for a settings.yaml and .secrets.yaml files inside it.

If the directory or the necessary files are missing the program stops with an error message: it is necessary to create them!

Tha package provides a convenient cli to create them, using defaults

<package_name>_configure

By executing this command in the environment where the package is installed, the command will generate the missing files.

The settings.yaml file will be populated using the encoded default values

If required, .secrets.yaml is also created containing only keys, leaving it to the user to complete it.

The program uses the values provided in the settings.yaml and .secrets.yaml files, overriding the encoded defaults.

It is possible to override the instruction provided settings.yaml by pointing to another settings file:

the values provided in this file override the values in the <home_dir>/<package_name>/.settings.yaml file.

This is done by setting the environment variable INCLUDES_FOR_DYNACONF and pointing it to a user-specific setting file (https://www.dynaconf.com/configuration/)

export INCLUDES_FOR_DYNACONF='/path/to/user_specific_settings.yaml'

NOTE for Windows users: it is possible to set environment variables for each users or globally using the OS

1. Open the Start menu and type “edit ENV” into the search bar

2. Tap “Edit Environment variables for your account”

3. Press “Environment variables” in the “System Variables” section

4. Click “Edit”

5. In the window that opens, hit “Variable value” and input the path you would like to add

the commands to set and to visualize environment variables are, respectively:

set ENV_KEY='env_value'
echo %ENV_KEY%

For the Developer

The subpackage “configuration” contains a config.py module: do not change this file because this contains the main module interface to the package.

Te developer can/should modify the module defaults.py. This module exposes two dictionaries to the config.py module:

1. settings = {“key1”: “value1”, “key2”: “value2”}

2. secrets = { “key1”: “<put the correct value here and keep it secret>”, “key2”: “<put the correct value here and keep it secret>”}

While we populate the settings keys, we leave placeholders for those in secrets. This reflects on the files create by the configuration command: we do not encode the secrets value in the code!

ConfigurationFileHandler()

class to handle (search, check, create, configuration files)