Contents of the JSON Output File

The output.json file is the main output file of CHAP and contains all data except for what is needed in 3D molecular visualisation. It abides by the specification of the JSON file format and can easily be read into any common programming language for visualisation or further processing.

By default, CHAP writes its output to a minified JSON file, which means that when you open output.json in a text editor, you will find all data in one line and without any white spaces. This is done to save disk space and speed up the reading and writing process, but does not result in a human-readable file. You can use a tool such as jq to prettify the JSON file. If you run

jq . output.json >> prettified.json

the resulting prettified.json file will contain nicely reformatted JSON with just one record per line. This is helpful to get an overview of how output.json is structured, but for most use cases it will be more appropriate to read the minified JSON file into the scripting language of your choice and to process the data therein.

On the highest level, output.json contains six JSON objects, which are summarised in the table below:

The remainder of this chapter will provide a detailed description of the information contained in each of these JSON objects.

Reproducibility Information

The reproducibility information is intended to help you retrace the steps undertaken to obtain a result. It contains information on the version of CHAP that generated a given data file and the command line call used to invoke chap. In practice, it may look like this:

{
  "reproducibilityInformation": {
    "version": {
      "string": "0.7.0",
      "major": "0",
      "minor": "7",
      "patch": "0",
      "gitHash": "e8766d6074820abbe93981cdf486f8a2a8327975"
    },
    "commandLine": "chap -f pr.xtc -s pr.tpr -sel-pathway 1 -sel-solvent 16"
  }
}

Here version is an object that contains the version number, which is generally written as a dot-separated string of the major, minor, and patch version number. The gitHash entry is an automatically generated serial number that changes every time the underlying code of CHAP changes. The commandLine entry is simply a string that can be copied to re-execute CHAP with the same parameters as the run that generated output.json.

Pathway Summary

The pathway summary provides information on the scalar-valued variables that describe the permeation pathway as a whole. Each of these quantities is given as a set of summary statistics (in particular the minimum, maximum, mean, standard deviation, and variance) that describe how the variable fluctuates over time. Inside output.json the pathway summary may look like this:

{
  "pathwaySummary": {
    "argMinRadius": {
      "min": 7.898504257202148,
      "max": 8.483589172363281,
      "mean": 8.265358924865723,
      "sd": 0.15247607231140137,
      "var": 0.023248951882123947
    },
    "minRadius": { 
		...
    },
    "length": {
		...
    },
    "volume": {
		...
    },
    "numPathway": {
		...
    },
    "numSample": {
		...
    },
    "argMinSolventDensity": {
		...
    },
    "minSolventDensity": {
		...
    },
    "bandWidth": {
		...
    }
  }
}

For brevity, the summary statistics have been omitted for all but the first variable in the above example. The following table gives a brief description of each of the variables contained within pathwaySummary:

Pathway Profile

The pathwayProfile object contains time-averaged data on variables that vary along the length of the permeation pathway. It is laid out as an object of multiple same-length JSON arrays (you can think of this as a data table). The first JSON array contains the pathway coordinate s; all other arrays contain summary statistics of pathway properties evaluated at the given value of s. In particular, the minimum, maximum, mean, and standard deviation of each variable are available and the array name is a composition of the variable name and the summary statistic:

{
  "pathwayProfile":{
    "s": [...],
    "radiusMin": [...],
    "radiusMax": [...],
    "radiusMean": [...],
    "radiusSd": [...],
    "densityMin": [...],
    "densityMax": [...],
    "densityMean": [...],
    "densitySd": [...],
    "energyMin": [...],
    "energyMax": [...],
    "energyMean": [...],
    "energySd": [...],
    "...": [...]
  }
}

Note that for brevity not all properties are explicitly listed in the above example and that for further clarity the number contained within each array have been omitted. The following table gives a comprehensive overview of all pathway properties in pathwayProfile. The summary statistic suffix is omitted here.

Note that the range and granularity of s values for which profile data is written to output.json can be controlled with the -out-extrap-dist and -out-num-points flags.

Pathway Scalar Time Series

The pathwayScalarTimeSeries object contains time series data arrays for all scalar-valued pathway properties in pathwaySummary. In addition, it contains an array of time stamps and is overall of the following form:

{
  "pathwayScalarTimeSeries": {
    "t": [...],
    "argMinRadius": [...],
    "minRadius": [...],
    "length": [...],
    "volume": [...],
    "numPathway": [...],
    "numSample": [...],
    "argminSolventDensity": [...],
    "minSolventDensity": [...],
    "bandWidth": [...]
  }
}

Pathway Profile Time Series

The pathwayProfileTimeSeries object contains time series for all properties for which time-averaged data exists in the pathwayProfile object with the exception of energy, which is only meaningfully defined as time-averaged property. It contains one JSON array for each pathway property as well as two additional JSON arrays containing the time stamps and spatial coordinates:

{
  "pathwayProfileTimeSeries": {
    "t": [...],
    "s": [...],
    "radius": [...],
    "density": [...],
    "plHydrophobicity": [...],
    "pfHydrophobicity": [...]
  }
}

The pathwayProfileTimeSeries object can therefore be thought of as a long-format data table, with time being the leading dimension (i.e. the value of t is repeated as many times as there are different values of s).

Residue Summary

The residueInformation object contains data on a per-residue basis and in particular the following variables:

For all but the first four variables, which are essentially non-varying database values, the minimum, maximum, mean, standard deviation, and variance (over time) are available.

Units and Further Notes

By default CHAP output contains the following units:

Please also keep in mind the following additional notes:

• CHAP defines the variance and standard deviation to be zero in cases where fewer than two samples are present. While a more mathematically intuitive approach would define these quantities as infinite in these cases, setting both quantities to zero allows reusing plot scripts with error bars.
• Due to a technical limitation of the JSON format, CHAP output can not contain infinities (which may occur as energy values where the density drops to zero). Wherever infinities do occur these are written to output as the largest representable floating point number, with the sign being the same as the sign of the infinity.