Tutorial

cockatoo is an implementation of a distance metric for the comparison of macromolecular crystallization cocktails (or conditions). A cockatil is a mixture of distinct chemical components. A screen is a collection of one or more cocktails. Using cockatoo we can compare the similarity between two cocktails or screens.

Distance between cocktails

Cocktails are represented in JSON format. For example, C0160.json:

{
    "name": "8_C0160",
    "ph": 7.5,
    "components": [
        {
            "conc": 4.48,
            "molecular_weight": 58.4428,
            "name": "sodium chloride",
            "smiles": "[Na+].[Cl-]",
            "unit": "M"
        },
        {
            "conc": 0.1,
            "density": 1.325,
            "molecular_weight": 238.3045,
            "name": "hepes",
            "smiles": "[O-]S(=O)(=O)CCN1CC[NH+](CC1)CCO",
            "unit": "M"
        }
    ]
}

Here we define a cocktail named 8_C0160 with two chemical components at pH 7.5. To compare the distance between two cocktails we can use the cockatoo command line utility:

$ cockatoo -v cdist -1 C0160.json -2 C0163.json
Computing distance between 8_C0160 and 8_C0163...
Distance: 0.252356552114

Distance between screens

Screens are also represented in JSON format. For example, hwi-gen8.json:

{
    "name": "hwi-gen8",
    "cocktails": [
        {
            "name": "8_C0160",
            "ph": 7.5,
            "components": [
                {
                    "conc": 4.48,
                    "molecular_weight": 58.4428,
                    "name": "sodium chloride",
                    "smiles": "[Na+].[Cl-]",
                    "unit": "M"
                },
                {
                    "conc": 0.1,
                    "density": 1.325,
                    "molecular_weight": 238.3045,
                    "name": "hepes",
                    "smiles": "[O-]S(=O)(=O)CCN1CC[NH+](CC1)CCO",
                    "unit": "M"
                }
            ]
        },
        ...
        ...
    ]
}

To compute the distance between two screens we can use the cockatoo command line utility:

$ cockatoo -v sdist -1 hwi-gen8.json -2 hwi-gen8A.json
Computing distance between hwi-gen8 and hwi-gen8A...
Distance: 0.00200980839646

Converting screens to JSON format

Crystallization screens can be stored in CSV format and converted to JSON using the cockatoo command line utility. The CSV format is as follows:

name,overall_ph,[conc,unit,name,ph]*

where [conc,unit,name,ph] is repeated 1 or more times for each compound

C1,3.4,0.100,M,MOPS,,1.000,M,ammonium chloride,
C2,3.9,0.100,M,MOPS,,1.000,M,ammonium chloride,
C3,4.4,0.100,M,MOPS,,1.000,M,ammonium chloride,
C4,4.9,0.100,M,MOPS,,1.000,M,ammonium chloride,

We also need to provide cockatoo information about each compound such as molecular weight, SMILES, etc. An example of this file can be found in the source distributuion data/hwi-compounds.csv. This file should contain information on each compound used in your cocktails in TAB delimitted format. For example:

name,conc_max,conc_min,formula,smiles,molecular_weight,density

To convert a screen to JSON format we run:

$ cockatoo -v convert -i screen.csv -o screen.json -n screen_name -s hwi-compounds.csv