Speciation

Speciation

Author:

Orion Cohen, Tingzheng Hou, Kara Fong

Year:

2021

Copyright:

GNU Public License v3

Explore the precise solvation shell of every solute.

Speciation tabulates the unique solvation shell compositions, their fraction, and their temporal locations.

From this, it provides search functionality to query for specific solvation shell compositions. Extremely convenient for visualization.

While speciation can be used in isolation, it is meant to be used as an attribute of the Solute class. This makes instantiating it and calculating the solvation data a non-issue.
class solvation_analysis.speciation.Speciation[source]
Calculate the solvation shells of every solute.

Speciation organizes the solvation data by the type of residue coordinated with the central solvent. It collects this information in a pandas.DataFrame indexed by the frame and solute number. Each column is one of the solvents in the solvent_name column of the solvation data. The column value is how many residue of that type are in the solvation shell.

Speciation provides the speciation of each solute in the speciation attribute, it also calculates the fraction of each unique shell and makes it available in the speciation_fraction attribute.

Additionally, there are methods for finding solvation shells of interest and computing how common certain shell configurations are.

Parameters:

solvation_data (pandas.DataFrame) – The solvation data frame output by Solute.

n_frames (int) – The number of frames in solvation_data.

n_solutes (int) – The number of solutes in solvation_data.

__init__(solvation_data, n_frames, n_solutes)[source]

static from_solute(solute)[source]

Generate a Speciation object from a solute.

Parameters:

solute (Solute)

Return type:

Pairing
calculate_shell_fraction(shell_dict)[source]
Calculate the fraction of shells matching shell_dict.

This function computes the fraction of solvation shells that exist with a particular composition. The composition is specified by the shell_dict. The fraction will be of all shells that match that specification.

Variables:

shell_dict (dict of {str: int}) – a specification for a shell composition. Keys are residue names (str) and values are the number of desired residues. e.g. if shell_dict = {‘mol1’: 4} then the function will return the fraction of shells that have 4 mol1. Note that this may include shells with 4 mol1 and any number of other solvents. To specify a shell with 4 mol1 and nothing else, enter a dict such as {‘mol1’: 4, ‘mol2’: 0, ‘mol3’: 0}.

Returns:

the fraction of shells

Return type:

float

Examples
# first define Li, BN, and FEC AtomGroups
>>> solute = Solute(Li, {'BN': BN, 'FEC': FEC, 'PF6': PF6})
>>> solute.run()
>>> solute.speciation.calculate_shell_fraction({'BN': 4, 'PF6': 1})
0.0898
get_shells(shell_dict)[source]

Find all solvation shells that match shell_dict.

This returns the frame, solute index, and composition of all solutes that match the composition given in shell_dict.

Variables:

shell_dict (dict of {str: int}) – a specification for a shell composition. Keys are residue names (str) and values are the number of desired residues. e.g. if shell_dict = {‘mol1’: 4} then the function will return all shells that have 4 mol1. Note that this may include shells with 4 mol1 and any number of other solvents. To specify a shell with 4 mol1 and nothing else, enter a dict such as {‘mol1’: 4, ‘mol2’: 0, ‘mol3’: 0}.

Returns:

the index and composition of all shells that match shell_dict

Return type:

pandas.DataFrame

property speciation_data

A dataframe containing the speciation of every solute at every trajectory frame. Indexed by frame and solute numbers. Columns are the solvent molecules and values are the number of solvent in the shell.

property speciation_fraction

The fraction of shells of each type. Columns are the solvent molecules and values are the number of solvent in the shell. The final column is the fraction of total shell of that particular composition.

property solvent_co_occurrence

The actual co-occurrence of solvents divided by the expected co-occurrence. In other words, given one molecule of solvent i in the shell, what is the probability of finding a solvent j relative to choosing a solvent at random from the pool of all coordinated solvents. This matrix will likely not be symmetric.