prolint2.core.universe

Authors:

Daniel P. Ramirez & Besian I. Sejdiu

Year:

2022

Copyright:

MIT License

class prolint2.core.universe.Universe(*args, universe=None, query=None, database=None, normalize_by: Literal['counts', 'actual_time', 'time_fraction'] = 'time_fraction', units: Literal['fs', 'ps', 'ns', 'us', 'ms', 's'] = 'us', add_lipid_types: list = [], **kwargs)

A subclass of MDAnalysis.Universe that adds a query and database attribute, and other useful methods.

Parameters: *args: Variable positional arguments for the parent class. universe: mda.Universe or None, optional. An existing Universe object to use as the basis for this Universe. query: mda.AtomGroup or None, optional. The AtomGroup used as a query during contact calculations. database: mda.AtomGroup or None, optional. The AtomGroup used as a database during contact calculations. normalize_by: Literal[‘counts’, ‘actual_time’, ‘time_fraction’], optional. The normalization method for time. units: TimeUnitLiteral, optional. The units for time conversion. add_lipid_types: list, optional. Additional lipid types to include in the database.

Attributes: query: ExtendedAtomGroup. The query AtomGroup used as a reference during contact calculation. database: ExtendedAtomGroup. The database AtomGroup used as a target during contact calculation. units: TimeUnitLiteral. The units for time conversion. normalize_by: str. The normalization method for time.

compute_contacts(*args, **kwargs)

Compute contacts between the query and database AtomGroups.

Args: *args: Additional positional arguments for ContactsProvider.compute. **kwargs: Additional keyword arguments for ContactsProvider.compute.

Returns: result: The result of the contact computation.

property database

The database AtomGroup.

Returns: ExtendedAtomGroup. The database AtomGroup.

load_contacts_from_file(file, *args, **kwargs)

Load contacts from a file.

Args: file: str. The path to the file containing contacts. *args: Additional positional arguments for ContactsProvider.load_from_file. **kwargs: Additional keyword arguments for ContactsProvider.load_from_file.

Returns: result: The result of the contact loading operation.

property normalize_by

The normalizer of the trajectory time.

Returns: str. The normalization method for time.

property query

The query AtomGroup.

Returns: ExtendedAtomGroup. The query AtomGroup.

property units

The units of the trajectory time.

Returns: TimeUnitLiteral. The units for time conversion.

update_database(new_database)

Update the database AtomGroup with a new AtomGroup.

Args: new_database: mda.AtomGroup. The new database AtomGroup.

Returns: None

update_query(new_query)

Update the query AtomGroup with a new AtomGroup.

Args: new_query: mda.AtomGroup. The new query AtomGroup.

Returns: None

prolint2.core.groups

Authors:

Daniel P. Ramirez & Besian I. Sejdiu

Year:

2022

Copyright:

MIT License

class prolint2.core.groups.ExtendedAtomGroup(*args, **kwargs)

An extended version of the MDAnalysis AtomGroup class.

This class extends the functionality of the MDAnalysis AtomGroup to provide additional features for working with atoms and residues.

add(resname=None, atomname=None, resnum=None, atomids=None)

Add atoms to the query or database.

Parameters: resname (str or list): Residue name(s) for filtering. atomname (str or list): Atom name(s) for filtering. resnum (int or list): Residue number(s) for filtering. atomids (int or list): Atom IDs for filtering.

Returns: ExtendedAtomGroup: A new ExtendedAtomGroup containing the selected atoms.

filter_resids_by_resname(resids: Iterable[int], resname: str)

Filter the residue IDs by residue name.

Parameters: resids (iterable): List of residue IDs to filter. resname (str): Residue name for filtering.

Returns: np.ndarray: Filtered residue IDs.

get_resid(resname: str)

Get the residue ID of a residue in the AtomGroup.

Parameters: resname (str): Residue name.

Returns: int: Residue ID associated with the given residue name.

get_resids(resnames: ~typing.Iterable[str], out: ~typing.Union[list, ~typing.Dict[str, int]] = <class 'list'>)

Get the residue IDs of a list of residues in the AtomGroup.

Parameters: resnames (iterable): List of residue names. out (list or dict): Output format.

Returns: list or dict: Residue IDs corresponding to the given residue names. Raises: ValueError: If the ‘out’ parameter is not ‘list’ or ‘dict’.

get_resname(resid: int)

Get the residue name of a residue in the AtomGroup.

Parameters: resid (int): Residue ID.

Returns: str: Residue name associated with the given residue ID.

get_resnames(resids: ~typing.Iterable[int], out: ~typing.Union[list, ~typing.Dict[int, str]] = <class 'list'>)

Get the residue names of a list of residues in the AtomGroup.

Parameters: resids (iterable): List of residue IDs. out (list or dict): Output format.

Returns: list or dict: Residue names corresponding to the given residue IDs. Raises: ValueError: If the ‘out’ parameter is not ‘list’ or ‘dict’.

remove(resname=None, atomname=None, resnum=None, atomids=None)

Remove atoms from the query or database.

Parameters: resname (str or list): Residue name(s) for filtering. atomname (str or list): Atom name(s) for filtering. resnum (int or list): Residue number(s) for filtering. atomids (int or list): Atom IDs for filtering.

Returns: ExtendedAtomGroup: A new ExtendedAtomGroup with the selected atoms removed.

property resname_counts

Get the number of residues of each residue name in the AtomGroup.

Returns: collections.Counter: Counter object with residue name counts.

static static_filter_resids_by_resname(resids: ndarray, resnames: ndarray, resids_subset: ndarray, resname: str)

Filter the residue IDs by residue name using a static method.

Parameters: resids (np.ndarray): All residue IDs in the AtomGroup. resnames (np.ndarray): All residue names in the AtomGroup. resids_subset (np.ndarray): Subset of residue IDs to filter. resname (str): Residue name for filtering.

Returns: np.ndarray: Filtered residue IDs from the subset.

property unique_resnames

Get the unique residue names in the AtomGroup.

Returns: np.ndarray: Array of unique residue names.

class prolint2.core.groups.PLAtomGroupBase

An abstract base class for AtomGroup objects.

This abstract base class defines a set of methods and properties for working with AtomGroup objects.

abstract add(resname=None, atomname=None, resnum=None, atomids=None)

Add atoms to the query or database.

Parameters:

• resname (str, optional) – The residue name to filter by.

• atomname (str, optional) – The atom name to filter by.

• resnum (int, optional) – The residue number to filter by.

• atomids (List[int], optional) – A list of atom IDs to add.

abstract filter_resids_by_resname(resids: ndarray, resname: str)

Filter the residue IDs by residue name.

Parameters:

• resids (np.ndarray) – An array of residue IDs to filter.

• resname (str) – The residue name to filter by.

Returns:

An array of residue IDs that match the specified residue name.

Return type:

np.ndarray

abstract get_resid(resname: str)

Get the residue ID of a residue in the AtomGroup.

Parameters:

resname (str) – The residue name.

Returns:

The residue ID of the specified residue name.

Return type:

int

abstract get_resids(resnames: Iterable[str])

Get the residue IDs of a list of residues in the AtomGroup.

Parameters:

resnames (Iterable[str]) – An iterable of residue names.

Returns:

A list of residue IDs corresponding to the input residue names.

Return type:

List[int]

abstract get_resname(resid: int)

Get the residue name of a residue in the AtomGroup.

Parameters:

resid (int) – The residue ID.

Returns:

The residue name of the specified residue.

Return type:

str

abstract get_resnames(resids: Iterable[int])

Get the residue names of a list of residues in the AtomGroup.

Parameters:

resids (Iterable[int]) – An iterable of residue IDs.

Returns:

A list of residue names corresponding to the input residue IDs.

Return type:

List[str]

abstract remove(resname=None, atomname=None, resnum=None, atomids=None)

Remove atoms from the query or database.

Parameters:

• resname (str, optional) – The residue name to filter by.

• atomname (str, optional) – The atom name to filter by.

• resnum (int, optional) – The residue number to filter by.

• atomids (List[int], optional) – A list of atom IDs to remove.

abstract property resname_counts

Get the number of residues of each residue name in the AtomGroup.

Returns:

A dictionary containing the counts of each unique residue name.

Return type:

dict

abstract property unique_resnames

Get the unique residue names in the AtomGroup.

Returns:

A set of unique residue names present in the AtomGroup.

Return type:

set

prolint2.core.contact_provider

Authors:

Daniel P. Ramirez & Besian I. Sejdiu

Year:

2022

Copyright:

MIT License

class prolint2.core.contact_provider.ComputedContacts(contact_strategy_instance: BaseContactStore, provider: ContactsProvider)

A class to compute contacts between residues and lipids.

Parameters:

• contact_strategy_instance (BaseContactStore) – An instance of a contact strategy class.

• provider (ContactsProvider) – The contact provider that will be used to compute contacts.

apply_function(func: Callable, target_lipid_name=None) → DefaultDict[ResidueID, DefaultDict[LipidName, Dict[LipidId, float]]]

Apply the given function to the contacts for the given lipid name.

compute_metric(metric: str, target_lipid_name=None) → DefaultDict[ResidueID, DefaultDict[LipidName, Dict[LipidId, float]]]

Compute a pre-defined metric for all lipids or a specific lipid.

Parameters:

• metric (str) – The metric to compute. Must be one of ‘max’, ‘sum’, ‘mean’.

• target_lipid_name (str, optional) – The name of the lipid to compute the metric for. If None, the metric will be computed for all lipids.

Returns:

A dictionary of computed metrics for all lipids.

Return type:

Dict[str, Dict[str, Dict[int, float]]]

Examples

>>> c.compute('max')
>>> c.compute('sum', 'DOPC')
>>> c.compute('median') # raises ValueError. Use `apply_function` instead.

property contact_frames: DefaultDict[ResidueID, DefaultDict[LipidName, Dict[LipidId, Iterable[FrameIndex]]]]

The computed contacts.

property contacts: DefaultDict[ResidueID, DefaultDict[LipidName, Dict[LipidId, Iterable[float]]]]

The computed contacts.

create_dataframe(n_frames: int) → DataFrame

Create a pandas DataFrame from the computed contacts.

Parameters:

n_frames (int) – The number of frames in the trajectory.

Returns:

A pandas DataFrame with the computed contacts.

Return type:

pd.DataFrame

difference(other: ComputedContacts) → ComputedContacts

Compute the difference of two contact providers. Given two contact providers (c1 and c2), the difference between them (c2 -c1) is defined as the contacts of c2 that are not present in c1.

Parameters:

other (ComputedContacts) – The other contact provider to compute the difference with.

Returns:

A new contact provider with the difference of the contacts of both contact providers.

Return type:

ContactsProvider

Examples

>>> ts = Universe('coordinates.gro', 'trajectory.xtc')
>>> c1 = ts.compute_contacts(cutoff=7)
>>> c2 = ts.compute_contacts(cutoff=8)
>>> c3 = c2 - c1
>>> c1 - c2 == c2 - c1 # False, c1 - c2 will be an empty contact provider if c1 is a subset of c2

get_contact_data(residue_id: int, lipid_id: int, output: str = 'contacts') → list

Get the contact data for a given residue and lipid.

Parameters:

• residue_id (int) – The residue id.

• lipid_id (int) – The lipid id.

• output (str, optional) – The output format. Must be one of ‘contacts’ or ‘indices’.

Returns:

A list of contacts or frame indices.

Return type:

list

get_lipids_by_residue_id(residue_id: int) → list

Get all LipidIds that interact with the given ResidueID.

get_residues_by_lipid_id(lipid_id: int) → list

Get all ResidueIDs that interact with the given LipidId.

intersection(other: ComputedContacts) → ComputedContacts

Compute the intersection of two contact providers. Note that ProLint contacts use a radial cutoff. This means that the intersection between two contact providers (c1 and c2) will be equal to the contact provider with the smallest cutoff. ProLint, however, defines the intersection between two contact providers (c1 and c2) to be equal to the lipid ids of the contact provider with the smallest cutoff, and the frame indices of the contact provider with the largest cutoff. This way the intersection between two contact providers is meaningful and computationaly allows for chaining of contact providers (See example below).

Parameters:

other (ComputedContacts) – The other contact provider to compute the intersection with.

Returns:

A new contact provider with the intersection of the contacts of both contact providers.

Return type:

ContactsProvider

Examples

>>> ts = Universe('coordinates.gro', 'trajectory.xtc')
>>> c1 = ts.compute_contacts(cutoff=7)
>>> c2 = ts.compute_contacts(cutoff=8)
>>> c3 = c1 + c2
>>> c1 + c2 == c2 + c1 # True

property pooled_contacts: DefaultDict[ResidueID, DefaultDict[LipidName, Dict[LipidId, Iterable[float]]]]

The computed contacts.

class prolint2.core.contact_provider.ContactsProvider(query, database, params=None, compute_strategy: Literal['default'] = 'default', contact_strategy: Literal['exact', 'aprox'] = 'exact')

Class that provides the contacts computation functionality.

compute(strategy_or_computer=None, start=None, stop=None, step=1, **kwargs)

Compute contacts between the query and the database.

Parameters:

• strategy_or_computer (str or ContactComputerBase, optional) – The strategy to compute contacts. If None, the default strategy is used.

• **kwargs – Additional arguments to pass to the contact computer.

Returns:

The computed contacts.

Return type:

ComputedContacts

load_from_file(file, **kwargs)

Load contacts from a file.

Parameters:

• file (str or pathlib.Path) – The path to the file to load the contacts from.

• **kwargs – Additional arguments to pass to the contact loader.

Returns:

The computed contacts.

Return type:

ComputedContacts