JSON (JavaScript Object Notation) is a simple human-readable format that expresses data objects in name-value pairs. Over the years, it has surpassed XML to become the preferred data exchange format between applications. As a result, I’ve recently added the --json command-line option to DSSR to make its numerous derived parameters easily accessible.

The DSSR JSON output is contained in a compact one-line text string that may look cryptic to the uninitiated. Yet, with commonly available JSON parsers or libraries, it is straightforward to make sense of the DSSR JSON output. In this blogpost, I am illustrating how to parse DSSR-derived .json file via two command-line tools, jq and Underscore-CLI.

jq — lightweight and flexible command-line JSON processor

According to its website,

jq is like sed for JSON data – you can use it to slice and filter and map and transform structured data with the same ease that sed, awk, grep and friends let you play with text.

Moreover, like DSSR per se, “jq is written in portable C, and it has zero runtime dependencies.” Prebuilt binaries are available for Linux, OS X and Windows. So it is trivial to get jq up and running. The current stable version is 1.5, released on August 15, 2015.

Using the crystal structure of yeast phenylalanine tRNA (1ehz) as an example, here are some sample usages with DSSR-derived JSON output:

    # Pretty print JSON
x3dna-dssr -i=1ehz.pdb --json | jq .
    # Extract the top-level keys, in insertion order 
x3dna-dssr -i=1ehz.pdb --json | jq keys_unsorted
    # Extract parameters for nucleotides
x3dna-dssr -i=1ehz.pdb --json | jq .nts
    # Extract nucleotide id and its base reference frame
x3dna-dssr -i=1ehz.pdb --json | jq '.nts[] | (.nt_id, .frame)'

Underscore-CLI — command-line utility-belt for hacking JSON and Javascript.

Underscore-CLI is built upon Node.js, and can be installed using the npm package manager. It is claimed as ‘the “swiss-army-knife” tool for processing JSON data – can be used as a simple pretty-printer, or as a full-powered Javascript command-line.’

Following the above examples illustrating jq, here are the corresponding commands for Underscore-CLI:

x3dna-dssr -i=1ehz.pdb --json | underscore print --color
x3dna-dssr -i=1ehz.pdb --json | underscore keys --color
x3dna-dssr -i=1ehz.pdb --json | underscore select .nts --color
x3dna-dssr -i=1ehz.pdb --json | underscore select .nts | underscore select '.nt_id, .frame' --color

jq or Underscore-CLI — which one to use?

As always, it depends. While jq feels more like a standard Unix utility (as sed, awk, grep etc), Underscore-CLI is better integrated into the Javascript language. For simple applications such as parsing DSSR output, either jq or Underscore-CLI is more than sufficient.

I use jq most of the time, but resort to Underscore-CLI for its “smart whitespace”. Here is an example to illustrate the difference between the two:

# z-axis of A.G1 (1ehz) base reference frame
# jq output, split in 5 lines
    "z_axis": [
      0.799,
      0.488,
      -0.352
    ]
# Underscore-CLI, in a more-readable one line
    "z_axis": [0.799, 0.488, -0.352]