ligning.utils

Utility functions

Graph to smiles, mol conversion, visualization etc.

ligning.utils.MW_array_to_number_average(MW: nparray) → float

calculate the number average molecular weight from an array of molecular weight

Parameters

MW (nparray) – molecular weight of a population

Returns

MW_mean – number average molecular weight

Return type

float

ligning.utils.MW_array_to_weight_average(MW: nparray) → float

calculate the number average molecular weight from an array of molecular weight

Parameters

MW (nparray) – molecular weight of a population

Returns

MW_mean_weight – weight average molecular weight

Return type

float

ligning.utils.adjust_indices(G: nxgraph) → nxgraph

Adjust the indices due to node removal

Parameters

G (nxgraph) – the graph

Returns

Gcopy – the new graph

Return type

nxgraph

ligning.utils.cal_CI(y: nparray, confidence: Optional[float] = 0.95) → nparray

Calculate the 95% confidence interval

Parameters

  • y (nparray) – data array

  • confidence (Optional[float], optional) – confidence level, by default 0.95

Returns

CI – CI array

Return type

nparray

ligning.utils.cal_distance(metrics_target: nparray, metrics_P: nparray, metrics_weights: Optional[nparray] = None) → float

Calculate the distance between two metrics array

Parameters

  • metrics_target (nparray) – the metrics array of the target

  • metrics_P (nparray) – the metrics array of the polymer

  • metrics_weights (nparray) – the weights array of each metrics

Returns

d – distance

Return type

float

ligning.utils.clean_csv_cache(FilePath: str)

Delete the file generated previously

Parameters

FilePath (str) – the file path

ligning.utils.counts_to_metrics(counts: nparray, additional: Optional[bool] = False) → nparray

Convert counts array to metrics array

Parameters

  • counts (nparray) – counts array

  • additional (Optional[bool], optional) – include additional metrics, by default False

Returns

metrics – metrics array in the same size

Return type

nparray

ligning.utils.draw_atomic_graph(G: nxgraph) → None

Plot the atomic graph

Parameters

G (nxgraph) – a connected graph, each node is an atom

ligning.utils.draw_big_graph(G: nxgraph) → None

Plot the big graph

Parameters

G (nxgraph) – a connected graph, each node is a monomer

ligning.utils.draw_graph(G: nxgraph, node_labels: Optional[dict] = None, node_shape: Optional[str] = 'o', node_size: Optional[int] = 500) → None

Plot the connected graph

Parameters

  • G (nxgraph) – a connected graph

  • node_labels (Optional[dict], optional) – dictionary of node labels to show, by default None (indices are the labels) keys are the indices, values are the the node labels

  • node_shape (Optional[str], optional) – node marker symbol, by default ‘o’

  • node_size (Optional[int], optional) – node marker size, by default 300

ligning.utils.formula_to_MW(formula: str) → float

Calculate molecular weight from the chemical formula

Parameters

formula (str) – chemical formula for the molecule

Returns

MW – molecular weight

Return type

float

ligning.utils.generate_random_branching_state(branching_propensity: float, random_state: Optional[numpy.random.RandomState] = None) → bool

Generate a random branching state based on the propensity

Parameters

  • branching_propensity (float) – branching propensity, the likelihood of forming a branch

  • random_state (Optional[RandomState], optional) – RandomState object in numpy, by default None

Returns

branching_state – branching state, True for allowing branching

Return type

bool

ligning.utils.generate_random_linkage(linkage_distribution: nparray, random_state: Optional[numpy.random.RandomState] = None) → str

Generate a random linkage type based on target distribution

Parameters

  • linkage_distribution (nparray) – linkage distribution

  • random_state (Optional[RandomState], optional) – RandomState object in numpy, by default None

Returns

linkage_name – linkage name

Return type

str

ligning.utils.generate_random_monomer(monomer_distribution: nparray, random_state: Optional[numpy.random.RandomState] = None) → str

Generate a monomer type based on target distribution

monomer_distributionnparray

monomer distribution

random_stateOptional[RandomState], optional

RandomState object in numpy, by default None

Returns

mtype – monomer type

Return type

str

ligning.utils.generate_random_size_from_distribution(mean_size: Tuple[int, float], max_size: Tuple[int, float], distribution_scaling: Optional[float] = 1.0, size_in_MW: Optional[bool] = False, random_state: Optional[numpy.random.RandomState] = None) → float

Generate a random size from a normal distribution

Parameters

  • mean_size (Tuple[int, float]) – the expected mean size, either number average molecular weight or expected monomer count

  • max_size (Tuple[int, float]) – the max size limit, either number average molecular weight or max monomer count

  • distribution_scaling (Optional[float], optional) – factor to control the width of molecular weight distribution between 0 and 1, by default 1.0

  • size_in_MW (Optional[bool], optional) – size is in molecular weight, by default False

  • random_state (Optional[RandomState], optional) – RandomState object in numpy, by default None

Returns

size – random size

Return type

float

ligning.utils.graph_to_mol(G: nxgraph, save_mol: Optional[bool] = False, name: Optional[str] = 'test', save_path: Optional[str] = '/home/docs/checkouts/readthedocs.org/user_builds/ligningraphs/checkouts/latest/docs/source') → molecule

Convert the graph to the mol object in RDKit and save it as a figure

Parameters

  • G (nxgraph) – a connected graph, each node is an atom

  • save_mol (Optional[bool], optional) – flag to save the mol as a figure, by default False

  • name (Optional[str], optional) – name of the molecule, by default ‘test’

  • save_path (Optional[str], optional) – path to save the figure, by default os.getcwd()

Returns

mol – the molecule object in RDKit

Return type

molecule

ligning.utils.graph_to_smile(G: nxgraph) → str

Convert the graph to smile string

Parameters

G (nxgraph) – a connected graph, each node is an atom

Returns

smiles – smiles string of the molecule

Return type

str

ligning.utils.join_two(G1: nxgraph, G2: nxgraph) → nxgraph

union the two graphs

Parameters

  • G1 (nxgraph) – graph 1

  • G2 (nxgraph) – graph 2

Returns

union – the union of two graphs

Return type

nxgraph

ligning.utils.make_available(G: nxgraph, node_index: int) → nxgraph

make a single C atom available for bonding by changing the bonding property to True

Parameters

  • G (nxgraph) – the graph

  • node_index (int) – the carbon atom index

Returns

G – the new graph

Return type

nxgraph

ligning.utils.make_multi_available(G: nxgraph, monomer_type: str) → nxgraph

make a multiple C atom available for bonding in a monomer by changing the bonding property to True

Parameters

  • G (nxgraph) – the graph

  • monomer_type (str) – monomer type, must be ‘H’, ‘G’ or ‘S’

Returns

the new graph

Return type

G ： nxgraph

Raises

ValueError – Input monomer type not allowed

ligning.utils.make_unavailable(G: nxgraph, node_index: int) → nxgraph

make a single C atom unavailable for bonding by changing the bonding property to False

Parameters

  • G (nxgraph) – the graph

  • node_index (int) – the carbon atom index

Returns

G – the new graph

Return type

nxgraph

ligning.utils.metrics_array_to_dict(metrics_array: nparray, metrics_names: List[str]) → dict

Convert an array of metrics into dictionary

Parameters

  • metrics_array (nparray) – metrics array

  • metrics_names (List[str]) – metrics names

Returns

metrics_dict – metrics names as keys and values in a dictionary

Return type

dict

ligning.utils.plot_distance_trajectory(distances: list, simulation_name: Optional[str] = 'x', distance_name: Optional[str] = None, save_path: Optional[str] = None)

Plot the distribution for each metrics

Parameters

  • Distance (list) – Distance values

  • simulation_name (list) – names of the simulation

  • distance_name (str) – names of the distance, population or individual

  • save_path (Optional[str], optional) – path to save the figure, by default None

ligning.utils.plot_metrics(metrics_target: dict, metrics_current: dict, metrics_population: nparray, metrics_names: list, save_path: Optional[str] = None)

Plot the distribution for each metrics

Parameters

  • metrics_target (dict) – objective (target) values

  • metrics_current (dict) – current values

  • metrics_population (nparray) – metrics matrix for a population

  • metrics_names (list) – names of the metrics for comparison

  • save_path (Optional[str], optional) – path to save the figure, by default None

ligning.utils.plot_single_distribution(ypred_all: nparray, ypred: Optional[Tuple[int, float]] = None, yobj: Optional[Tuple[int, float]] = None, metric_name: Optional[str] = 'x', save_path: Optional[str] = None)

Compare the normal distribution fitted by the predicted data with the object value

Parameters

  • ypred_all (nparray) – the array for the predicted value

  • ypred (Tuple[int, float]) – current value, by default None

  • yobj (Tuple[int, float]) – objective (target) value, by default None

  • metric_name (Optional[str], optional) – name of the metric, by default ‘x’

  • save_path (Optional[str], optional) – path to save the figure, by default None

ligning.utils.select_one_from_many(many: list) → object

Select a random item from a list

Parameters

many (list) – list of items

Returns

random_item – a random item

Return type

object

ligning.utils.select_one_from_many_with_index(many: list) → Tuple[object, int]

Select a random item from a list and return the index

Parameters

many (list) – list of items

Returns

  • random_item (object) – a random item

  • index (int) – the index

ligning.utils.set_random_state(seed: Optional[int] = None)

set random state for a MC trajectory

Parameters

seed (Optional[int], optional) – random seed, by default None

Returns

random_state – RandomState object in numpy

Return type

RandomState

ligning.utils.smiles_to_formula(smiles: str) → str

Convert the smiles to the chemical formula in C, H and O

Parameters

smiles (str) – smiles string of the molecule

Returns

formula – chemical formula for the molecule

Return type

str

ligning.utils.write_output_on_individual(row_data: list, column_names: list, OutputPath: str)

write to the output file for an individual structure :param row_data: data in a list :type row_data: list :param column_names: column names in a list :type column_names: list :param OutputPath: output file path :type OutputPath: str