Reports

Report JSON specification

The report JSON is quite flexibly on the information it can contain. Here are some guidelines to promote consistency on the reports generated by each component. In general, the reports file is an array of JSON objects that contain relevant information for each executed process in the pipeline:

reportFile = [{<processA/tagA reports>}, {<processB/tagB reports>}, ... ]

Nextflow metadata

The nextflow metada is automatically added to the reportFile as a single JSON entry with the nfMetadata key that contains the following information:

"nfMetadata": {
    "scriptId": "${workflow.scriptId}",
    "scriptName": "${workflow.scriptId}",
    "profile": "${workflow.profile}",
    "container": "${workflow.container}",
    "containerEngine": "${workflow.containerEngine}",
    "commandLine": "${workflow.commandLine}",
    "runName": "${workflow.runName}",
    "sessionId": "${workflow.sessionId}",
    "projectDir": "${workflow.projectDir}",
    "launchDir": "${workflow.launchDir}",
    "start_time": "${workflow.start}"
}

Note

Unlike the remaining JSON entries in the report file, which are generated for each process execution, the nfMetadata entry is generated only once per project execution.

Root

The reports contained in the reports.json file for each process execution are added to the root object:

{
    "pipelineId": 1,
    "processId": pid,
    "processName": task_name,
    "projectid": RUN_NAME,
    "reportJson": reports,
    "runName": RUN_NAME,
    "scriptId": SCRIPT_ID,
    "versions": versions,
    "trace": trace,
    "userId": 1,
    "username": "user",
    "workdir": dirname(abspath(report_json))
}

The other key:values are added automatically when the reports are compiled for each process execution.

Versions

Inside the root, the signature key for software version information is versions:

"versions": [{
    "program": "progA",
    "version": "1.0.0",
    "build": "1"
}, {
    "program": "progB",
    "version": "2.1"
}]

Only the program and version keys are mandatory.

ReportJson

Table data

Inside reportJson, the signature key for table data is tableRow:

 "reportJson": {
     "tableRow": [{
         "sample": "strainA",
         "data": [{
             "header": "Raw BP",
             "value": 123,
             "table": "qc",
         }, {
             "header": "Coverage",
             "value": 32,
             "table": "qc"
         }],
         "sample": "strainB",
         "data": [{
             "header": "Raw BP",
             "value": 321,
             "table": "qc",
         }, {
             "header": "Coverage",
             "value": 22,
             "table": "qc"
         }]
     }]
}

tableRow should contain an array of JSON for each sample with two key:value pairs:

  • sample: Sample name
  • data: Table data (see below).

data should be an array of JSON with at least three key:value pairs:

  • header: Column header
  • value: The data value
  • table: Informs to which table this data should go.

Note

Available table keys: typing, qc, assembly, abricate, chewbbaca.

Plot data

Inside reportJson, the signature key for plot data is plotData:

"reportJson": {
    "plotData": [{
        "sample": "strainA",
        "data": {
            "sparkline": 23123,
            "otherplot": [1,2,3]
         }
    }],
}

plotData should contain an array of JSON for each sample with two key:value pairs:

  • sample: Sample name
  • data: Plot data (see below).

data should contain a JSON object with the plot signatures as keys, and the relevant plot data as value. This data can be any object (integer, float, array, JSON, etc). It will be up to the components in the flowcraft web application to parse this data and generate the appropriate chart.

Warnings and fails

Inside reportJson, the signature key for warnings is warnings and for failures is fail:

"reportJson": {
    "warnings": [{
        "sample": "strainA",
        "table": "qc",
        "value": ["message 1", "message 2"]
    }],
    "fail": [{
        "sample": "strainA",
        "table": "assembly",
        "value": ["message 1"]
    }]
}

warnings/fail should contain an array of JSON for each sample with two key:value pairs:

  • sample: Sample name
  • value: An array with one or more string messages.
  • table [optional]: If a table signature is provided, the warning/fail messages information will appear on that table. Otherwise, it will appear as a general warning/error that is associated to the sample but not to any particular table.