MD DataRecord¶

MD DataRecord a brief overview¶

Molecular Dynamics (MD) simulations are notoriously time consuming and computational demanding. In terms of data, a lot of information need to be stored and retrieved such as atomic coordinates, atomic velocities, forces and energies just to cite only few; extracting and managing this data then becomes crucial. The MD DataRecord API simplifies the access to the md data in the MD floe programming for Orion. In the OpenEye Datarecord model, data is exchanged between cubes in format of data records where POD data, custom objects, json data etc. are stored and retrieved by using the associated field names and types. The MD Datarecord API is built on the top of the OpenEye Datarecord, standardizing the record content data produced during MD runs in a well-structured format and providing an API point to its access.

MD DataRecord structure¶

The MD data produced along MD runs is structured in what is named the md record:

the md record contains a sub-record named md stages where md information is saved. This sub-record is a list of md stage records;

each md stage is a record itself with an associated name, type, log data, topology and MD State info. The latter is a custom object that stores data useful to restart MD runs such as, atomic positions, velocities and box information;

the md record at the top level contains a Parmed object used to carry the whole system parametrization data

the md record at the top level can also contain other data such as the MDComponents object used to carry info related to the different md system parts such as ligand, protein, solvent, cofactors etc. or can contains the starting ligand and protein with their names, unique identifiers such as the flask id , cofactor ids etc.

The following picture shows the md record structure and its main components

Structure of the MD Record¶

The md record is user accessible by using the MDDataRecord API. In order to use it, the MDOrion package must be installed. The installation of the package also requires to have access to the OpenEye Magpie repository for some dependencies. The API has been designed to transparently work locally and in Orion. To use the API the user needs to create a MDDatarecord object starting from an OERecord object, after that getter and setter functions can be used to access the md data (see full MDDatatecord API Documentation).

Code snippets¶

The following code snippets give an idea on how to use the API.

Warning

In the following examples record is an OpenEye Datarecord produced running MD floes such as Solvate and Run MD or Solvate and Run Protein-Ligand MD. Starting from the MDOrion pkg v2.0.0, the datasets produced from the Short Trajectory MD with analysis floe is “ligand centric” and the MDDatarecord API cannot be directly applied to the produced records. However, the API still works on the conformer (poses) ligand sub-records which are still md records

from MDOrion.Standards.mdrecord import MDDataRecord

# To use the MD Datarecord API an MDDataRecord instance is built starting from an OERecord
md_record = MDDataRecord(record)

# At this point getters and setters can be used to
# extract/set info from/to the md record

# MD Stage names available
stage_names = md_record.get_stages_names

# Get a MD Record Stage
md_stage_production = md_record.get_stage_by_name(stage_names[2])

# Extract the logging info from a stage
info_stage = md_record.get_stage_info(stg_name=stage_names[2])

# Extract the MD State from a stage
md_set_up_state = md_record.get_stage_state(stg_name=stage_names[0])

# Extract the Parmed Structure from the md record and synchronize the
# positions, velocities and box data to the selected stage state
pmd_structure = md_record.get_parmed(sync_stage_name=stage_names[2])

# Extract the OEMol system flask from the record and its title
flask = md_record.get_flask
flask_title = md_record.get_title

# Extract the trajectory file name associated with a stage. In this
# case the stage trajectory in unpacked and the trajectory name
# can be used in any md analysis pkg to be loaded
trj_name = md_record.get_stage_trajectory(stg_name=stage_names[2])

# Add a new Stage to the md_stages record
md_record.add_new_stage(stage_name="New_Stage",
                        stage_type="NPT",
                        topology=flask,
                        mdstate=md_set_up_state,
                        data_fn="test.tar.gz")

MDDatatecord API Documentation¶

Follow the API documentation.

class orionmdcore.mdrecord.mdrecord.MDDataRecord(record, inplace=True)¶

This Class Implements the MD Datarecord API by using getter and setter functions

add_new_stage(stage_name, stage_type, topology, mdstate, data_fn, append=True, log=None, info=None, trajectory_fn=None, trajectory_engine=None, trajectory_orion_ui='OrionFile')¶

This method add a new MD stage to the MD stage record

Parameters

stage_name (String) – The new MD stage name
stage_type (String) – The MD stage type e.g. SETUP, MINIMIZATION etc.
topology (OEMol) – The topology
mdstate (MDState) – The new mdstate made of state positions, velocities and box vectors
data_fn (String) – The data file name is used only locally and is linked to the MD data associated with the stage. In Orion the data file name is not used
append (Bool) – If the flag is set to true the stage will be appended to the MD stages otherwise the last stage will be overwritten by the new created MD stage
log (String or None) – Log info
info (Python Dictionary or None) – Info Dictionary of Plain Data
trajectory_fn (String, Int or None) – The trajectory name for local run or id in Orion associated with the new MD stage
trajectory_engine (String or None) – The MD engine used to generate the new MD stage. Possible names: OpenMM or Gromacs
trajectory_orion_ui (String) – The trajectory string name to be displayed in the Orion UI

Returns

boolean – True if the MD stage creation was successful

Return type

Bool

delete_stage_by_idx(idx)¶

This method deletes an MD stage selected by passing its index. If the stage index cannot be found an exception is raised.

Parameters: idx (Int) – The MD stage index
Returns: boolean – True if the deletion was successful
Return type: Bool

delete_stage_by_name(stg_name='last')¶

This method deletes an MD stage selected by passing the string name. If the string “last” is passed (default) the last MD stage is deleted. If no stage name has been found an exception is raised.

Parameters: stg_name (String) – The MD stage name
Returns: boolean – True if the deletion was successful
Return type: Bool

property delete_stages¶

This method deletes all the record stages

Returns: boolean – True if the deletion was successful
Return type: Bool

property get_conf_id¶

This method returns the identification field CONF ID present on the record

Returns: conformed_id – The conformer id
Return type: Int

property get_flask¶

This method returns the flask molecule present on the record

Returns: flask – The flask present on the record otherwise an error is raised
Return type: OEMol

property get_flask_id¶

This method returns the integer value of the flask identification field present on the record

Returns: flask_id – The unique flask identifier
Return type: Int

property get_last_stage¶

This method returns the last MD stage of the MD record stages

Returns: record – The last stage of the MD record stages
Return type: OERecord

property get_lig_id¶

This method returns the ligand identification field present on the record

Returns: ligand_id – The ligand identification id number
Return type: Int

property get_ligand¶

This method returns the ligand molecule present on the record

Returns: ligand – The ligand molecule if the ligand has been set on the record otherwise an error is raised
Return type: OEMol

property get_md_components¶

This method returns the MD Components if present on the record

Returns: md_components – The MD Components object
Return type: MDComponents

property get_primary¶

This method returns the primary molecule present on the record

Returns: record – The Primary Molecule
Return type: OEMol

property get_protein¶

This method returns the protein molecule present on the record

Returns: protein – The protein molecule if the protein has been set on the record otherwise an error is raised
Return type: OEMol

property get_record¶

This method returns the record

Returns: record – The record to be passed with the cubes
Return type: OERecord

get_stage_by_idx(idx)¶

This method returns a MD stage selected by passing an index. If the stage is not found an exception is raised.

Parameters: idx (Int) – The stage index to retrieve
Returns: record – The MD stage selected by its index
Return type: OERecord

get_stage_by_name(stg_name='last')¶

This method returns a MD stage selected by passing the string stage name. If the string “last” is passed (default) the last MD stage is returned. If multiple stages have the same name the first occurrence is returned. If no stage name has been found an exception is raised.

Parameters: stg_name (String) – The MD stage name
Returns: record – The MD stage selected by its name
Return type: OERecord

get_stage_info(stg_name='last')¶

This method returns the info related to the selected stage name. If no stage name is passed the last stage is selected.

Parameters: stg_name (String) – The MD stage name
Returns: info_string – The info associated with the selected MD stage otherwise None
Return type: String

get_stage_logs(stg_name='last')¶

This method returns the logs related to the selected stage name. If no stage name is passed the last stage is selected.

Parameters: stg_name (String) – The MD stage name
Returns: info_string – The info associated with the selected MD stage
Return type: String

get_stage_state(stg_name='last')¶

This method returns the MD State of the selected stage name. If no stage name is passed the last stage is selected

Parameters: stg_name (String) – The MD stage name
Returns: state – The MD state of the selected MD stage
Return type: MDState

get_stage_topology(stg_name='last')¶

This method returns the MD topology of the selected stage name. If no stage name is passed the last stage is selected.

Parameters: stg_name (String) – The MD stage name
Returns: topology – The topology of the selected MD stage
Return type: OEMol

get_stage_trajectory(stg_name='last')¶

This method returns the trajectory file name associated with the md data. If the trajectory is not found None is return

Parameters: stg_name (String) – The MD stage name
Returns: trajectory_filename – Trajectory file name if the process was successful otherwise None
Return type: String or None

property get_stages¶

This method returns the MD stage record list with all the MD stages.

Returns: record_list – The MD stages record list
Return type: list

property get_stages_names¶

This method returns the list names of the MD stages.

Returns: list – The MD stage name list
Return type: list

property get_title¶

This method returns the title present on the record

Returns: title – The title string if present on the record otherwise an error is raised
Return type: String

property has_conf_id¶

This method checks if the identification field CONF ID is present on the record

Returns: boolean – True if the conformer id field is present on the record otherwise False
Return type: Bool

property has_extra_data_tar¶

This method returns True if extra data file in tar format is attached to the record

Returns: boolean – True if extra data file is present on the record otherwise False
Return type: Bool

property has_flask_id¶

This method checks if the flask identification field is present on the record

Returns: boolean – True if the flask ID field is present on the record otherwise False
Return type: Bool

property has_lig_id¶

This method checks if the ligand identification field is present on the record

Returns: boolean – True if the ligand identification field is present on the record otherwise False
Return type: Bool

property has_ligand¶

This method returns True if ligand molecule is present on the record

Returns: boolean – True if the ligand molecule is present on the record otherwise False
Return type: Bool

property has_ligand_traj¶

This method checks if the multi conformer ligand is on the record.

Returns: boolean – True if the multi conformer ligand is on the record otherwise False
Return type: Bool

property has_md_components¶

This method returns True if the MD Components object is present on the record

Returns: boolean – True if the md components object is present on the record otherwise False
Return type: Bool

property has_parmed¶

This method checks if the Parmed object is on the record.

Returns: boolean – True if the Parmed object is on the record otherwise False
Return type: Bool

property has_protein¶

This method returns true if the protein molecule is present on the record

Returns: boolean – True if the protein molecule is present on the record otherwise False
Return type: Bool

property has_protein_traj¶

This method checks if the multi conformer protein is on the record.

Returns: boolean – True if the multi conformer protein is on the record otherwise False
Return type: Bool

has_stage_info(stg_name='last')¶

This method returns True if MD stage selected by passing the string name has infos present on the MD stage record otherwise False.

Parameters: stg_name (String) – The MD stage name
Returns: boolean – True if the MD stage has info otherwise False
Return type: Bool

has_stage_name(stg_name)¶

This method returns True if MD stage selected by passing the string name is present on the MD stage record otherwise False.

Parameters: stg_name (String) – The MD stage name
Returns: boolean – True if the MD stage name is present on the MD stages record otherwise False
Return type: Bool

property has_stages¶

This method returns True if the record has a MD record list otherwise False

Returns: boolean – True if the record has a list of MD stages otherwise False
Return type: Bool

property has_title¶

This method checks if the Title field is present on the record

Returns: boolean – True if the Title field is resent on the record otherwise False
Return type: Bool

property has_water_traj¶

This method checks if the multi conformer water is on the record.

Returns: boolean – True if the multi conformer water is on the record otherwise False
Return type: Bool

set_conf_id(conf_id)¶

This method sets the identification field for the conformer on the record

Parameters: conf_id (Int) – An identification integer for the record
Returns: boolean – True if the conformed id has been set on the record otherwise an error is raised
Return type: Bool

set_flask(flask)¶

This method sets the flask molecule on the record

Parameters: flask (OEMol) – The flask molecule to set on the record
Returns: record – True if the flask molecule has been set on the record otherwise an error is raised
Return type: Bool

set_flask_id(id)¶

This method sets the integer value of the flask identification field on the record

Parameters: id (Int) – An integer value for the flask identification field
Returns: boolean – True if the flask identification ID has been set as an integer on the record
Return type: Bool

set_lig_id(sys_id)¶

This method sets the ligand identification field on the record

Parameters: sys_id (Int) – An integer value for the ligand identification field
Returns: boolean – True if the value for the ligand identification field was successfully set on the record
Return type: Bool

set_ligand(ligand)¶

This method sets the ligand molecule on the record

Returns: boolean – returns True if the ligand has been set on the record otherwise an error is raised
Return type: Bool

set_md_components(md_components)¶

This method sets the MD Components on the record

Parameters: md_components (MDComponents) – The MD Components instance
Returns: boolean – True if the md components field was successfully set on the record
Return type: Bool

set_primary(primary_mol)¶

This method sets the primary molecule on the record

Parameters: primary_mol (OEMol) – The primary molecule to set on the record
Returns: boolean – True if the primary molecule has been set on the record
Return type: Bool

set_protein(protein)¶

This method sets the protein molecule on the record

Returns: boolean – returns True if the protein has been set on the record otherwise an error is raised
Return type: Bool

set_stage_info(info_dic, stg_name='last')¶

This method sets the stage info field on the selected stage by name

Parameters

stg_name (String) – The MD Stage name
info_dic (Python dic) – The dictionary containing the Plain Data info to save

Returns

boolean – True if the system Title has been set on the record

Return type

Bool

set_title(title)¶

This method sets the system Title field on the record

Parameters: title (String) – A string used to identify the molecular system
Returns: boolean – True if the system Title has been set on the record
Return type: Bool