Introduction

This API provides access to your NGS quality data stored in the omnomicsQ quality control system for NGS sequencing data.

The API is available at https://q.omnomics.com/api/v1.

The API uses HTTP Basic authentication. For testing, you can use the same username and password that you use for the omnomicsQ web application. For real usage, please contact Euformatics for separate credentials.

All operations produce responses in JSON format.

Note
 Please note that the example responses below have been edited for brevity, and are not actually complete/realistic responses that you would get from the actual API.

Operations

Listing samples

GET /api/v1/samples/

Returns the list of all samples of your organization.

Curl request

$ curl 'https://q.omnomics.com/api/v1/samples/' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ {
    "id" : 4423,
    "sample_key" : "test",
    "run_date" : "2015-06-26T12:33:33+0000",
    "created" : "2015-06-26T12:33:33+0000",
    "updated" : "2016-04-08T09:22:28+0000",
    "organization_id" : 1,
    "device" : {
      "id" : 1,
      "name" : "My HiSeq 2000",
      "platform" : {
        "id" : 3,
        "seq_model" : "HiSeq 2000",
        "manufacturer" : "Illumina"
      }
    },
    "sop" : {
      "id" : 1081,
      "name" : "Default",
      "description" : null,
      "retired" : false,
      "kit" : {
        "id" : 61,
        "name" : "SureSelect XTHuman Whole Exome V5",
        "manufacturer" : "Agilent",
        "categ" : {
          "id" : 2,
          "name" : "Whole Exome"
        }
      }
    },
    "sample_type" : {
      "id" : 1,
      "name" : "Fresh"
    },
    "organism" : "Unknown",
    "tissue" : "Unknown",
    "trashed" : false
  }, {
    "id" : 431,
    "sample_key" : "test2",
    "run_date" : "2014-09-25T11:13:54+0000",
    "created" : "2014-09-25T11:13:54+0000",
    "updated" : "2016-10-17T11:12:39+0000",
    "organization_id" : 1,
    "device" : {
      "id" : 261,
      "name" : "My Genome Analyzer II",
      "platform" : {
        "id" : 8,
        "seq_model" : "Genome Analyzer II",
        "manufacturer" : "Illumina"
      }
    },
    "sop" : {
      "id" : 6421,
      "name" : "Default",
      "description" : "Default SOP for HaloPlexHS Noonan Syndrome",
      "retired" : false,
      "kit" : {
        "id" : 775,
        "name" : "HaloPlexHS Noonan Syndrome",
        "manufacturer" : "Agilent",
        "categ" : {
          "id" : 3,
          "name" : "Targeted"
        }
      }
    },
    "sample_type" : {
      "id" : 1,
      "name" : "Fresh"
    },
    "organism" : "Unknown",
    "tissue" : "Unknown",
    "trashed" : false
  } ]
}

Getting sample QC metrics

GET /api/v1/samples/{key}

Returns the details of a sample and its QC metrics.

An optional query parameter amplicon_qc_metrics can be used to control which amplicon-level QC metrics to include in the response. The supported values are:

all

Return data for both technical and clinical target features (default)

t

Return data for technical target features only

c

Return data for clinical target features only

none

Do not return feature-level data at all

Path parameters

Table 1. /api/v1/samples/{key}
Parameter Description

key

Sample key

Curl request

$ curl 'https://q.omnomics.com/api/v1/samples/test' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "id" : 4423,
  "sample_key" : "test",
  "run_date" : "2015-06-26T12:33:33+0000",
  "created" : "2015-06-26T12:33:33+0000",
  "updated" : "2016-04-08T09:22:28+0000",
  "organization_id" : 1,
  "device" : {
    "id" : 1,
    "name" : "My HiSeq 2000",
    "platform" : {
      "id" : 3,
      "seq_model" : "HiSeq 2000",
      "manufacturer" : "Illumina"
    }
  },
  "sop" : {
    "id" : 1081,
    "name" : "Default",
    "description" : "Default SOP for SureSelect XTHuman Whole Exome V5",
    "retired" : false,
    "kit" : {
      "id" : 61,
      "name" : "SureSelect XTHuman Whole Exome V5",
      "manufacturer" : "Agilent",
      "categ" : {
        "id" : 2,
        "name" : "Whole Exome"
      }
    },
    "base_qual_thresh" : 13
  },
  "sample_type" : {
    "id" : 1,
    "name" : "Fresh"
  },
  "organism" : "Homo sapiens",
  "tissue" : "Bone marrow",
  "trashed" : false,
  "sample_meta" : {
    "dna_amount" : 60,
    "lot_number_1" : "ACME114"
  },
  "fail_status" : "pass",
  "qc_metrics" : {
    "MEAN_QUALITY" : {
      "value" : 29.7,
      "lab_diff" : -11.8,
      "ind_diff" : -17.5,
      "warn_low" : 27.8,
      "warn_high" : null,
      "fail_low" : 22.7,
      "fail_high" : null,
      "fail_status" : "pass"
    }
  },
  "amplicon_qc_metrics" : {
    "amp_dropout_thresh" : 15,
    "amp_dropout_thresh_strand" : 5,
    "detection_limit" : 10,
    "detection_limit_strand" : 4,
    "cli_amp_dropout_thresh" : null,
    "cli_amp_dropout_thresh_strand" : null,
    "cli_detection_limit" : null,
    "cli_detection_limit_strand" : null,
    "items" : [ {
      "chr" : "17",
      "start_pos" : 29682823,
      "end_pos" : 29688620,
      "read_depth_avg" : 26.8,
      "read_depth_fwd_avg" : 11.5,
      "read_depth_rev_avg" : 15.3,
      "quality_avg" : 29.1,
      "breadth_of_coverage" : 60.3,
      "description" : "ENSE00002705870",
      "target_type" : "t",
      "complete_dropout" : false,
      "partially_covered" : false
    } ]
  }
}

Response fields

Path Type Description

id

Number

Identifier of the sample

sample_key

String

Sample key; an identifier for the sample within the organization

run_date

String

Timestamp when the sample was sequenced (defaults to same as created)

created

String

Timestamp when the sample was first created (QC metrics initially submitted)

updated

String

Timestamp when the sample was last updated

organization_id

Number

Identifier of the organization

device.id

Number

Identifier of the sequencer device

device.name

String

Name of the sequencer device

device.platform.id

Number

Identifier of the sequencing platform

device.platform.seq_model

String

Sequencer model

device.platform.manufacturer

String

Sequencer manufacturer

sop.id

Number

Identifier of the SOP

sop.name

String

Name of the SOP

sop.description

String

Description of the SOP

sop.retired

Boolean

true if the SOP has been retired, false if it is active

sop.kit.id

Number

Identifier of the capture/amplification kit

sop.kit.name

String

Name of the kit

sop.kit.manufacturer

String

Manufacturer of the kit

sop.kit.categ

Object

Category of the kit

sop.base_qual_thresh

Number

Minimum Phred score for counting read depth

sample_type.id

Number

Type of the sample (identifier)

sample_type.name

String

Type of the sample (human-readable)

organism

String

Name of the organism

tissue

String

Name of the tissue

trashed

Boolean

Whether the sample has been discarded (Y/N)

sample_meta.*

Array

Sample metadata attributes

fail_status

String

Overall status (pass/fail/warn)

qc_metrics.*

Array

Sample QC metrics

qc_metrics.*.value

Number

Value

qc_metrics.*.lab_diff

Number

Difference to the laboratory average (percent)

qc_metrics.*.ind_diff

Number

Difference to the industry average (percent); available only if opted-in to data sharing

qc_metrics.*.warn_low

Number

Warning threshold, low

qc_metrics.*.warn_high

Number

Warning threshold, high

qc_metrics.*.fail_low

Number

Failure threshold, low

qc_metrics.*.fail_high

Number

Failure threshold, high

qc_metrics.*.fail_status

String

Status (pass/fail/warn/absent)

amplicon_qc_metrics.amp_dropout_thresh

Number

Average read depth threshold for dropout, technical target

amplicon_qc_metrics.amp_dropout_thresh_strand

Number

Average single-strand read depth threshold for dropout, technical target

amplicon_qc_metrics.detection_limit

Number

Single base read depth threshold for gap, technical target

amplicon_qc_metrics.detection_limit_strand

Number

Single base read depth threshold for gap, single strand, technical target

amplicon_qc_metrics.cli_amp_dropout_thresh

Null

Average read depth threshold for dropout, clinical target

amplicon_qc_metrics.cli_amp_dropout_thresh_strand

Null

Average single-strand read depth threshold for dropout, clinical target

amplicon_qc_metrics.cli_detection_limit

Null

Single base read depth threshold for gap, clinical target

amplicon_qc_metrics.cli_detection_limit_strand

Null

Single base read depth threshold for gap, single strand, clinical target

amplicon_qc_metrics.items[]

Array

Per-amplicon (contig) QC metrics, for each line of the target BED file

amplicon_qc_metrics.items[].chr

String

Chromosome

amplicon_qc_metrics.items[].start_pos

Number

Start position

amplicon_qc_metrics.items[].end_pos

Number

End position

amplicon_qc_metrics.items[].read_depth_avg

Number

Average read depth

amplicon_qc_metrics.items[].quality_avg

Number

Average quality

amplicon_qc_metrics.items[].breadth_of_coverage

Number

Breadth of coverage

amplicon_qc_metrics.items[].description

String

Name of contig/amplicon (from BED file)

amplicon_qc_metrics.items[].target_type

String

Type of contig/amplicon ("c" = clinical, "t" = technical)

amplicon_qc_metrics.items[].complete_dropout

Boolean

Whether contig/amplicon is has average read depth less than threshold

amplicon_qc_metrics.items[].partially_covered

Boolean

Whether contig/amplicon less than full coverage at required quality level

Listing genes not covered

GET api/v1/samples/{key}/genes-not-covered

Returns an alphabetically ordered list of names of genes not covered. The "gene" is the start of the description string from the BED file, up to a dot ‘.’ or, if the description does not contain a dot, the whole description.

Curl request

$ curl 'https://q.omnomics.com/api/v1/samples/gap-api-testing-sample-1/genes-not-covered' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ "IDH2", "KIT", "NRAS" ]
}

Considers all clinical targets that have either an average read depth below the set threshold, or a breadth of coverage less than 100.

Listing Illumina runs

GET /api/v1/illumina-runs/

Returns the list of all illumina runs of your organization.

Curl request

$ curl 'https://q.omnomics.com/api/v1/illumina-runs/' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ {
    "id" : 4,
    "run_key" : "160226_M02784_0100_000000000-AKRG3",
    "run_date" : "2016-02-26T00:00:00+0000",
    "created" : "2016-05-27T09:32:19+0000",
    "updated" : "2017-06-06T11:41:47+0000",
    "organization_id" : 1,
    "run_comment" : "Nextera - 318bp",
    "device" : {
      "id" : 1741,
      "name" : "gh",
      "platform" : {
        "id" : 8,
        "seq_model" : "Genome Analyzer II",
        "manufacturer" : "Illumina"
      }
    }
  }, {
    "id" : 141,
    "run_key" : "151102_SN956_1934_AH55WMBBXX",
    "run_date" : "2015-11-02T00:00:00+0000",
    "created" : "2016-09-19T08:19:17+0000",
    "updated" : "2016-09-19T08:19:17+0000",
    "organization_id" : 1,
    "run_comment" : null,
    "device" : {
      "id" : 1221,
      "name" : "HiSeq 1500",
      "platform" : {
        "id" : 41,
        "seq_model" : "HiSeq 1500",
        "manufacturer" : "Illumina"
      }
    }
  } ]
}

Getting Illumina run metrics

GET /api/v1/illumina-runs/{key}

Returns the details of an Illumina run and its metrics.

Path parameters

Table 1. /api/v1/illumina-runs/{key}
Parameter Description

key

Run key

Curl request

$ curl 'https://q.omnomics.com/api/v1/illumina-runs/160226_M02784_0100_000000000-AKRG3' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "id" : 4,
  "run_key" : "160226_M02784_0100_000000000-AKRG3",
  "run_date" : "2016-02-26T00:00:00+0000",
  "created" : "2016-05-27T09:32:19+0000",
  "updated" : "2017-06-06T11:41:47+0000",
  "organization_id" : 1,
  "run_comment" : "Nextera - 318bp",
  "device" : {
    "id" : 1741,
    "name" : "gh",
    "platform" : {
      "id" : 8,
      "seq_model" : "Genome Analyzer II",
      "manufacturer" : "Illumina"
    }
  },
  "reads" : [ {
    "read_number" : 1,
    "is_index" : false,
    "summary" : {
      "yield_g" : 3.539956808,
      "percent_aligned" : 1.09,
      "error_rate" : 0.54,
      "first_cycle_intensity" : 218,
      "percent_gt_q30" : 95.64
    },
    "lanes" : [ {
      "lane" : 1,
      "tile_count" : 38,
      "density" : {
        "mean" : 1160860,
        "stddev" : 18198
      },
      "percent_pf" : {
        "mean" : 88.99,
        "stddev" : 2.02
      },
      "phasing_mean" : 0.128,
      "prephasing_mean" : 0.053,
      "reads" : 26501598,
      "reads_pf" : 23599710,
      "percent_gt_q30" : 95.64,
      "yield_g" : 3.539956808,
      "percent_aligned" : {
        "mean" : 1.09,
        "stddev" : 0.04
      },
      "error_rate" : {
        "mean" : 0.54,
        "stddev" : 0.05
      },
      "first_cycle_intensity" : {
        "mean" : 217.87,
        "stddev" : 31.95
      }
    } ]
  } ],
  "nonindex_reads_summary" : {
    "yield_g" : 7.079913616,
    "percent_aligned" : 1.08,
    "error_rate" : 0.58,
    "first_cycle_intensity" : 216,
    "percent_gt_q30" : 92.92
  },
  "total_reads_summary" : {
    "yield_g" : 7.410309792,
    "percent_aligned" : 1.08,
    "error_rate" : 0.58,
    "first_cycle_intensity" : 252,
    "percent_gt_q30" : 92.94
  },
  "index_summary" : [ {
    "lane" : 1,
    "index_number" : 1,
    "sample_key" : "16_79915",
    "project_name" : "NA",
    "index1" : "GGACTCCT",
    "index2" : "TATCCTCT",
    "fraction_mapped" : 32.5504
  } ]
}

Response fields

Path Type Description

id

Number

Internal identifier for the Illumina run

run_key

String

Identifier for the Illumina run within the organization

run_date

String

Run date (sequencing date)

created

String

Timestamp when the run was created (metrics first submitted)

updated

String

Timestamp when the run was last updated

organization_id

Number

Identifier of the owning organization

run_comment

String

Free-text comment

device

Object

Device

reads[]

Array

An array of metrics for sequencing reads

reads[].read_number

Number

Sequencing read number

reads[].is_index

Boolean

Whether this is an index read

reads[].summary

Object

Summary metrics for the sequencing reads

reads[].summary.yield_g

Number

Number of gigabases sequenced

reads[].summary.percent_aligned

Number

Percentage of the sample that aligned to the PhiX genome

reads[].summary.error_rate

Number

Calculated error rate of the reads that aligned to PhiX

reads[].summary.first_cycle_intensity

Number

Average of the channel A intensity measured at the first cycle averaged over filtered clusters

reads[].summary.percent_gt_q30

Number

Percentage of bases with a quality score of 30 or higher

reads[].lanes[]

Object

Summary metrics for each lane within this sequencing read

reads[].lanes[].lane

Number

Lane number

reads[].lanes[].tile_count

Number

Number of tiles in lane

reads[].lanes[].density

Object

Density of clusters detected by image analysis (mean and standard deviation)

reads[].lanes[].percent_pf

Object

Percentage of clusters passing filtering (mean and standard deviation)

reads[].lanes[].phasing_mean

Number

Percentage of molecules in a cluster for which sequencing falls behind the current cycle within a read (mean)

reads[].lanes[].prephasing_mean

Number

Percentage of molecules in a cluster for which sequencing falls jumps ahead of the current cycle within a read (mean)

reads[].lanes[].reads

Number

Number of clusters

reads[].lanes[].reads_pf

Number

Number of clusters passing filtering

reads[].lanes[].percent_gt_q30

Number

Percentage of bases with a quality score of 30 or higher

reads[].lanes[].yield_g

Number

Number of bases sequenced which passed filter

reads[].lanes[].percent_aligned

Object

Percentage that aligned to the PhiX genome (mean and standard deviation)

reads[].lanes[].error_rate

Object

Calculated error rate as determined by PhiX alignment (mean and standard deviation)

reads[].lanes[].first_cycle_intensity

Object

Average of the channel A intensity measured at the first cycle averaged over filtered clusters (mean and standard deviation)

nonindex_reads_summary

Object

Summary of the non-index sequencing reads

nonindex_reads_summary

Object

Summary of the all sequencing reads

index_summary[]

Array

Summary for indexing information

index_summary[].lane

Number

Lane number

index_summary[].index_number

Number

Unique number assigned to each index

index_summary[].sample_key

String

Sample identifier (sample key) assigned to an index in the sample sheet

index_summary[].project_name

String

Project assigned to an index in the sample sheet

index_summary[].index1

String

Sequence for the first index read (I7)

index_summary[].index2

String

Sequence for the second index read (I5)

index_summary[].fraction_mapped

Number

Percentage of passing filter reads mapped to this index

Listing QC metrics

GET /api/v1/qc-metrics/

Returns the list of all QC metrics.

Curl request

$ curl 'https://q.omnomics.com/api/v1/qc-metrics/' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ {
    "categ" : "Raw data",
    "measure_name" : "READS_TOTAL",
    "measure_full" : "Reads total",
    "description" : "Total number of sequences"
  }, {
    "categ" : "Raw data",
    "measure_name" : "TOTAL_BASES",
    "measure_full" : "Bases total",
    "description" : "Total number of bases"
  }, {
    "categ" : "Raw data",
    "measure_name" : "BASES_ABOVE_Q30",
    "measure_full" : "Bases above Q30 (%)",
    "description" : "Bases with quality over 30 or 99.9% accuracy"
  } ]
}

Response fields

Path Type Description

items.[].categ

String

Category of the measure, e.g. "Alignment", "Raw data", "Variant calling", "RNA sequencing".

items.[].measure_name

String

Measure name (internal)

items.[].measure_full

String

Measure name (human-readable)

items.[].description

String

Description of the measure

Listing sample metadata attributes

GET /api/v1/sample-meta/

Returns the list of all sample metadata attributes.

Curl request

$ curl 'https://q.omnomics.com/api/v1/sample-meta/' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ {
    "cli_name" : "technician",
    "data_type" : "string",
    "name" : "Technician",
    "description" : "Identifier for technician that performed the DNA extraction, library construction, sequencing reaction"
  }, {
    "cli_name" : "dna_amount",
    "data_type" : "number",
    "name" : "DNA amount (ng)",
    "description" : null
  }, {
    "cli_name" : "lot_1",
    "data_type" : "string",
    "name" : "Lot number of capture/amplification kit",
    "description" : null
  } ]
}

Response fields

Path Type Description

items.[].cli_name

String

Name (identifier)

items.[].data_type

String

Data type, e.g. "number" or "string"

items.[].name

String

Name (human readable)

items.[].description

Varies

Description

Listing SOPs

GET /api/v1/sops/

Returns the list of all SOPs.

An optional query parameter all controls whether also retired SOPs are returned. Supported values are:

false

Do not include retired SOPs (default)

true

Include also retired SOPS

Curl request

$ curl 'https://q.omnomics.com/api/v1/sops/' -i -u 'user:password' \
    -H 'Accept: application/json'

Response body

{
  "items" : [ {
    "id" : 1081,
    "name" : "Default",
    "description" : "Default SOP for SureSelect XTHuman Whole Exome V5",
    "retired" : false,
    "kit" : {
      "id" : 61,
      "name" : "SureSelect XTHuman Whole Exome V5",
      "manufacturer" : "Agilent",
      "categ" : {
        "id" : 2,
        "name" : "Whole Exome"
      }
    }
  }, {
    "id" : 1082,
    "name" : "30X",
    "description" : "30X SOP for SureSelect XTHuman Whole Exome V5",
    "retired" : false,
    "kit" : {
      "id" : 61,
      "name" : "SureSelect XTHuman Whole Exome V5",
      "manufacturer" : "Agilent",
      "categ" : {
        "id" : 2,
        "name" : "Whole Exome"
      }
    }
  }, {
    "id" : 6421,
    "name" : "Default",
    "description" : "Default SOP for HaloPlexHS Noonan Syndrome",
    "retired" : false,
    "kit" : {
      "id" : 775,
      "name" : "HaloPlexHS Noonan Syndrome",
      "manufacturer" : "Agilent",
      "categ" : {
        "id" : 3,
        "name" : "Targeted"
      }
    }
  } ]
}

Response fields

Path Type Description

items[].id

Number

SOP id

items[].name

String

SOP name

items[].description

String

SOP description

items[].retired

Boolean

true if the SOP has been retired, false if it is active

items[].kit.id

Number

Kit id

items[].kit.name

String

Kit name

items[].kit.manufacturer

String

Kit manufacturer

items[].kit.categ.id

Number

Kit category numerical code

items[].kit.categ.name

String

Kit category name

Known issues

This section lists known issues in the API at the time of publication.

  • Some missing quality metrics are reported as 0 (zero) instead of being absent.

Feedback

For feedback and bug reports, please send email to support@euformatics.com.