Tagged Data Manipulation¶

SD Tagged Data Manipulation¶

Meta information about a molecule is stored in what is known as ‘tagged data’. The most common example of this is the data fields found in SDF files. Since SD files are a common form of data storage and transfer from one system to another, OEChem provides several methods to manipulate this data. OEChem also provides round tripping SD data through the OEBinary, .oeb, and comma-separated-values, .csv file formats.

A simple class, OESDDataPair is used to set and retrieve SD data.

The following functions provide access to the SD data.

Since OESDDataPair stores SD data information in a string, numeric values have to be converted to a string with C#’s ToString() method before storing a value with either OESetSDData or OEAddSDData functions.

OEChem.OESetSDData(mol, "number of atoms", mol.NumAtoms().ToString());

Similarly the retrieved string can be converted to a numeric value with ToSingle() style methods.

if (OEChem.OEHasSDData(mol, "weight"))
{
    string str = OEChem.OEGetSDData(mol, "weight");
    float weight = System.Convert.ToSingle(str);
    System.Console.WriteLine("weight= " + weight);
}

The following example shows how to manipulate SD tagged data.

using System;
using OpenEye.OEChem;

public class ManipulateSDData
{
    public static int Main(string[] args)
    {
        OEGraphMol mol = new OEGraphMol();
        OEChem.OESmilesToMol(mol, "c1ccccc1");
        mol.SetTitle("benzene");

        // set some tagged data
        OEChem.OESetSDData(mol, "color", "brown");
        OEChem.OESetSDData(mol, new OESDDataPair("size", "small"));
        DumpSDData(mol);

        // check for existence of data, then delete it
        if (OEChem.OEHasSDData(mol, "size"))
        {
            OEChem.OEDeleteSDData(mol, "size");
        }

        DumpSDData(mol);

        // add additional color data
        OEChem.OEAddSDData(mol, "color", "black");
        DumpSDData(mol);

        // remove all SD data
        OEChem.OEClearSDData(mol);
        DumpSDData(mol);

        return 0;
    }

    private static void DumpSDData(OEMolBase mol)
    {
        System.Console.WriteLine("SD data of " + mol.GetTitle());

        // loop over SD data
        foreach (OESDDataPair dp in OEChem.OEGetSDDataPairs(mol))
        {
            System.Console.WriteLine(dp.GetTag() + " : " + dp.GetValue());
        }

        System.Console.WriteLine();
    }
}

The output of the preceding program is the following:

SD data of benzene
color : brown
size : small

SD data of benzene
color : brown

SD data of benzene
color : brown
color : black

SD data of benzene

CSV File Format¶

The CSV, comma-separated-values, file format is a comma file format used for data exchange in a wide variety of software. Other the years, the popularity of the format has out-stripped the robustness of many of its implementations leading to some subtle differences in how it is implemented between different software packages. This has led to creation and adoption of RFC 4180 as a standard for the CSV format. OEChem supports this standard as the base format for reading and writing molecules, OEMolBase objects, to .csv files. OEChem will read and write .csv files in the following layout:

0. The first line can optionally contain a header to use as the SD tag.
   • OEChem decides if the first line is a header by trying to interpret the first column of the first line as SMILES. See the OEIFlavor.CSV.Header flavor.
1. The first column is expected to be a SMILES string representing the molecule.
2. The second column is the molecule title, as accessed through OEMolBase.GetTitle.
3. Remaining columns will be read into SD data fields. The data is then accessible through OEGetSDData and OESetSDData.
   • If the file did not contain a header line, the SD tags will be named in the following pattern: OE_CSV_COLUMN_1, OE_CSV_COLUMN_2, ..., OE_CSV_COLUMN_N.
4. New-line characters are not supported inside a CSV record. They are round-tripped using the pipe character, |, instead.

Point #4 is a subtlety of meta-data interchange between SD files and CSV files. On the one hand, many CSV implementations do not support line-breaks inside CSV fields, Microsoft Excel does not and neither does OEChem. However, it is common to use multiple lines inside an SD data file like the following:

>  <activ_class>
Antiarthritic
Antiinflammatory
Cyclooxygenase-2 Inhibitor

OEChem implements a solution to this problem that ChemAxon has implemented and documented here. The solution is to use the pipe character, |, to represent line breaks inside a data field. For example, the previous example of a multi-line SD data field would look like the following:

SMILES,TITLE,active_class
...,...,Antiarthritic|Antiinflammatory|Cyclooxygenase-2 Inhibitor

This does cause a different problem for pipe characters inside data fields: how pipe characters are escaped? OEChem works around this problem by embedding the same semantics for CSV parsing to parse multi-line fields, just using the pipe character as the separator and the single quote character as the quoting escape character. Listing 2 demonstrates an example that writes out a tricky set of data to the OEFormat.CSV format.

using System;
using OpenEye.OEChem;

public class WriteCSV
{
    public static void Main(string[] args)
    {
        oemolostream ofs = new oemolostream();
        ofs.SetFormat(OEFormat.CSV);

        OEGraphMol mol = new OEGraphMol();
        OEChem.OESmilesToMol(mol, "O");
        mol.SetTitle("water");
        
        OEChem.OESetSDData(mol, "phases", "gas,liquid,solid");
        OEChem.OESetSDData(mol, "uses", "bathing\nwater guns\ntea|earl grey|hot");

        OEChem.OEWriteMolecule(ofs, mol);
        
        ofs.close();
    }
}

The output of Listing 2 will look like the following:

SMILES,TITLE,phases,uses
O,water,"gas,liquid,solid",bathing|water guns|'tea|earl grey|hot'

PDB Tagged Data Manipulation¶

The OEPDBDataPair class is used to set and retrieve PDB data pairs.

If you wish to store a numeric value, use C#’s .ToString() method to convert it to a string (see examples in SD Tagged Data Manipulation).

The following functions provide access to the PDB data.

The following PDB fields are stored as tagged PDB data when OEIFlavor.PDB.DATA input flavor is set:

The following example shows how to manipulate PDB tagged data.

using System;
using OpenEye.OEChem;

public class ManipulatePDBData
{
    public static int Main(string[] args)
    {
        if (args.Length != 1)
        {
            OEChem.OEThrow.Usage("ManipulatePDBData <pdbfile>");
        }

        oemolistream ifs = new oemolistream();
        if (!ifs.open(args[0]))
        {
            OEChem.OEThrow.Fatal("Unable to open " + args[0]);
        }

        // need to set input flavor to ensure PDB data is stored on molecule
        ifs.SetFlavor(OEFormat.PDB,
                      OEIFlavor.Generic.Default | OEIFlavor.PDB.Default | OEIFlavor.PDB.DATA);

        OEGraphMol mol = new OEGraphMol();

        while (OEChem.OEReadMolecule(ifs, mol))
        {
            if (OEChem.OEHasPDBData(mol, "COMPND"))
            {
                Console.WriteLine("COMPND:");
                Console.WriteLine(OEChem.OEGetPDBData(mol, "COMPND"));
            }

            if (OEChem.OEHasPDBData(mol, "HELIX "))
            {
                Console.WriteLine("HELIX:");
                Console.WriteLine(OEChem.OEGetPDBData(mol, "HELIX "));
            }

            if (OEChem.OEHasPDBData(mol, "SSBOND"))
            {
                Console.WriteLine("SSBOND:");

                foreach (OESDDataPair dp in OEChem.OEGetPDBDataPairs(mol))
                {
                    if (dp.GetTag().Equals("SSBOND"))
                        Console.WriteLine(dp.GetValue());
                }
            }
        }
        return 0;
    }
}

The output of the preceding program for 1D1H is the following:

COMPND:
    MOL_ID: 1;
HELIX:
   1   1 THR A   11  ASP A   14  5
SSBOND:
   1 CYS A    2    CYS A   16                          1555   1555
   2 CYS A    9    CYS A   21                          1555   1555
   3 CYS A   15    CYS A   28                          1555   1555

Multi-conformer molecules¶