jmzqc Parser, Writer and Validator for the HUPO-PSI MzQC format

This project is a parser, validator and serializer implementation for mzQC: Reporting and exchange format for mass spectrometry quality control data.

The Maven site with JavaDoc is available here.

Related Projects

• The official HUPO-PSI mzQC project

Table of contents

Table of Contents

• Related Projects
• Table of contents
• Building the project and generating client code from the command-line
• Using the project code releases via Maven Central
• Using the API programmatically
  • Reading MzQC JSON into the object model
  • Writing an MzQC object model to JSON
  • Validating MzQC
• References

Building the project and generating client code from the command-line

In order to build the client code and run the unit tests, execute the following command from a terminal:

./mvnw install

This generates the necessary domain specific code for Java.

Using the project code releases via Maven Central

This library requires Java 17 or later to run.

Note	The library will be made available via Maven Central. To search for releases, go to https://search.maven.org/search?q=g:org.lifs-tools+a:jmzqc

To use the parser libraries (reading and validation) in your own Maven projects, use the following dependency:

<dependency>
  <groupId>org.lifs-tools</groupId>
  <artifactId>jmzqc</artifactId>
  <version>${jmzqc.version}</version>
</dependency>

where jmzqc.version is the version of jmzqc you wish to use, e.g. for a release version:

<properties>
  <jmzqc.version>1.0.0</jmzqc.version>
</properties>

as defined in the properties section of your pom file.

Using the API programmatically

Reading MzQC JSON into the object model

To parse a JSON string directly:

MzQC mzQc = Converter.fromJsonString(....);

Alternatively, to read the content from a file:

MzQC mzQc = Converter.fromFile(new File("path/to/file.mzQC"));

Or, to read from a URL:

MzQC mzQc = Converter.fromUrl(new URL("https://raw.githubusercontent.com/HUPO-PSI/mzQC/main/specification_documents/draft_v1/examples/QC2-sample-example.mzQC"));

Writing an MzQC object model to JSON

You can use the jmzQC API to create an MzQC object:

var inputFileCvParams = asList(new CvParameter("MS:1000747", null, "completion time", "2017-12-08-T15:38:57Z"));
var infi = new InputFile(new CvParameter("MS:1000584", null, "mzML format", null), inputFileCvParams, new URI("file:///dev/null"), "file.raw");
var anso = new AnalysisSoftware("QC:9999999", null, "bigwhopqc", null, new URI("file:///dev/null"), "1.2.3");
var meta = new Metadata(asList(anso), null, asList(infi), "test_metadata");
var qm = new QualityMetric("QC:4000053", null, "RT duration", 99, null);
var rq = new BaseQuality(meta, asList(qm));
var sq = new BaseQuality(meta, asList(qm));
var cv = new ControlledVocabulary("TEST", new URI("https://www.eff.off"), null);
var mzqc = new MzQC(
        null,
        null,
        asList(cv),
        OffsetDateTime.now(),
        "pytest-test file",
        asList(rq),
        asList(sq),
        "1.0.0");

In order to write an MzQC object, you can also use the Converter:

Converter.toJsonFile(mzqc, new File("path/to/write/file.mzQC"));

Validating MzQC

You can validate MzQC files local files or JSON string:

Set<ValidationMessage> messages = Converter.validate(new File("path/to/file.mzQC"));

Or from a URL:

Set<ValidationMessage> messages = Converter.validate(new URL("https://raw.githubusercontent.com/HUPO-PSI/mzQC/main/specification_documents/draft_v1/examples/QC2-sample-example.mzQC"));

Or immediately from an MzQC object:

Set<ValidationMessage> messages = Converter.validate(mzqc);

The returned messages will be empty, if validation was successful. Otherwise, the messages will contain information on what was wrong and where in your mzQC document the issue was detected.

Alternatively, you can also download the 'cli' jar from Maven central https://search.maven.org/search?q=g:org.lifs-tools+a:jmzqc

Make the jmzqc-1.0.0-bin.jar executable. Please replace 1.0.0 with the correct version. Then run:

./jmzqc-1.0.0-bin.jar

to see the command line prompt:

usage: jmzqc
 -f,--file <arg>         Input a file name to read from for lipid name for
                         parsing. Each lipid name must be on a separate
                         line.
 -h,--help               Print help message.
 -o,--outputFile <arg>   Write output to provided file in tsv format
                         instead of to std out.
 -v,--version            Print version information.

The CLI jar will automatically validate any mzQC file provided against the latest JSON schema. If validation was successful, the return code will be 0 and Validation successful! will be printed to std out. If validation was unsuccessful, meaning validation messages have been produced, the exit code will be 1. Validation messages are printed to std err. This is an example for a file with an invalid date-time format (missing time zone information):

./jmzqc-1.0.0-cli.jar -f QC2-sample-example.mzQC
20:08:18 [main] ERROR com.networknt.schema.DateTimeValidator - Invalid date-time: No zone offset information found
Echoing output to stderr.
Code    Message Path    SchemaPath      Type    MessageString
1034    $.mzQC.creationDate: 2020-12-03T19:51:02 ist ein ungültiges date-time   $.mzQC.creationDate     #/properties/mzQC/properties/creationDate       dateTime        $.mzQC.creationDate: 2020-12-03T19:51:02 ist ein ungültiges date-time

Alternatively, you can redirect validation message output into a file:

./jmzqc-1.0.0-cli.jar -f QC2-sample-example.mzQC -o jmzqc-out.tsv
20:11:11 [main] ERROR com.networknt.schema.DateTimeValidator - Invalid date-time: No zone offset information found
Saving output to 'jmzqc-out.tsv'.

The file jmzqc-out.tsv will then contain the same output as the std out output above.

References