February 19, 2021

CDD Vault Update (February 2021 [#3]): New API Endpoints for Analyzing & Editing Protocol Data; ChemAxon Upgrade

This exciting release contains useful enhancements to the CDD Vault Application Programming Interface (API) as well as an update to the ChemAxon JChem chemistry cartridge used within CDD Vault.

Retrieve Protocol and Run Data Export via API

There is a new “format=csv” parameter available for the existing GET Protocol Data API call that will generate a csv file which mimics the export from the Run Details page within the CDD Vault web interface.

GET /api/v1/vaults/<vault_id>/protocols/<id>/data?format=csv

Using the "format=csv" parameter converts the API call into an async call so you must use the GET Exports API call to download the resulting csv file. The csv file is a report that includes exactly what you get via the application. So, data like the Control State and Z' factor are included. The only additional parameter allowed when you use the "format=csv" parameter is the "runs" parameter but if you do, you may only pass 1 run id.

GET /api/v1/vaults/<vault_id>/protocols/<id>/data?format=csv&runs=<run_id>

GET Protocol API Endpoint Returns Additional Protocol Statistics

The GET Protocol API call now returns additional protocol statistics.

GET /api/v1/vaults/<vault_id>/protocols/<id>

There is a new "statistics" section under the protocol_statistics section in the JSON with information similar to this:

    "statistics": [
                    {
                        "name": "z_prime_factor",
                        "count": 136,
                        "average": "0.69",
                        "standard_deviation": "967E-06"
                    },
                    {
                        "name": "positive_control",
                        "count": 136,
                        "average": "116",
                        "standard_deviation": "19.8"
                    },
                    {
                        "name": "negative_control",
                        "count": 136,
                        "average": "2.85E+03",
                        "standard_deviation": "279"
                    },
                    {
                        "name": "reference_molecule",
                        "count": 16,
                        "average": "1.88E+03",
                        "standard_deviation": "1.13E+03"
                    }
                ]

GET Runs

The GET Runs API endpoint has been modified to now return the same information as what is displayed interactively in the Run Summary page. The JSON returned includes a new "Statistics" section with information similar to this:

GET /api/v1/vaults/<vault_id>/runs/<run_id>

  "plate_statistics": [
           {
            "plate": {
                "id": 113344,
                "name": "Plate ABC123"
            },
            "readout_definition": {
                "id": 558822,
                "name": "Raw Data"
            },
            "statistics": [
                {
                    "name": "z_prime_factor",
                    "value": 0.6913198633901083
                },
                {
                    "name": "positive_control_mean",
                    "mean": 30.46875,
                    "standard_deviation": 11.642481652648547,
                    "count": 32
                },
                {
                    "name": "negative_control_mean",
                    "mean": 2936.5625,
                    "standard_deviation": 287.37532359773553,
                    "count": 32
                }
            ]

PUT Readout_Rows

The new PUT Readout_rows API endpoint allows you to update existing readout rows and flag a readout as an outlier via the API.

PUT /api/v1/vaults/<vault_id>/readout_rows/<readout_row_id>

To use this PUT Readouts call, you must submit JSON to indicate which edit is to be made to the readout row.

        {
          "readouts": {
            "283130": ">99",
            "283131": 77}
        }

The above JSON will edit 2 numeric readouts for a single row of data, one of which includes a modifier. Noteworthy tips:

The GET Protocol Data API call will be useful to ascertain the id of the readout row id for the Protocol data you wish to edit.
The GET Protocols API call also provides the readout definition IDs.
The JSON below is an example of the syntax used to set a readout value to null:
```
{
  "readouts": {
    "283130": ">99",
    "283131": null}
}
```
The JSON below is an example of the syntax used to flag a readout value as an outlier:
```
{"readouts":
  {"640916": {"outlier": true}}
}
```
The JSON below is an example of the syntax used to simultaneously flag a readout value as an outlier and update the value of the readout simultaneously:
```
{"readouts":
  {"119506": {"value":">99",
              "outlier": true}
  }
}
```

DELETE Readout_Rows

The new DELETE Readout_rows API endpoint allows you to delete an existing readout row via the API.

DELETE api/v1/vaults/<vault_id>/readout_rows/<readout_row_id>

The above API call will return JSON results like:

        {"message": "Readout row with ID 312653077 has been destroyed"}

Note: If the specified readout row does not exist, the API call returns:

    "error": "Couldn't find readout row with 'id'=<readout_row_id>"

Upgrade of the ChemAxon JChem Chemistry Cartridge

The ChemAxon JChem chemistry cartridge used within CDD Vault is now at version 21.2.

Tag(s): CDD Vault Updates , CDD Blog