Create a new qcML file

Using jqcML's intuitive and object-oriented object model, it is very straightforward and easy to create new qcML files.

The base container representing a qcML file is the QcML object. This object will contain all the relevant information that will subsequently be present in the qcML file.

// create a qcML object
QcML qcml = new QcML();

The first information that has to be added to the QcML object are references to controlled vocabularies. Controlled vocabularies are used in the qcML standard to unambiguously define each of the quality metrics. Therefore, a quality metric is invalid without a reference to a controlled vocabulary. jqcML enforces this by requiring that the controlled vocabulary used to define a quality metric is already present in the base QcML object before this quality metric can be added. Therefore these controlled vocabularies have to be added prior to adding the quality metrics.

// add references to the required controlled vocabularies (CV's)
Cv cvMS = new Cv("PSI-MS", "http://psidev.cvs.sourceforge.net/viewvc/psidev/psi/psi-ms/mzML/controlledVocabulary/psi-ms.obo", "MS");
qcml.addCv(cvMS);
Cv cvQC = new Cv("MS-QC", "http://code.google.com/p/qcml/source/browse/trunk/cv/qc-cv.obo", "QC");
qcml.addCv(cvQC);

Each qcML file can contain quality metrics for several mass spectrometry experiments, as well as quality metrics aggregated for a batch of experiments. Each set of metrics is denoted by a QualityAssessment object. Based on whether these metrics are for a single experiment, or aggregated for several experiments, the QualityAssessment object has to be added to the QcML object as a runQuality or a setQuality. The following example assume a runQuality. Often a qcML file will represent only a single experiment and contain only a single runQuality, although this is no requirement of the qcML standard.

// add a QualityAssessment to store the metrics
QualityAssessment run = new QualityAssessment("run");
qcml.addRunQuality(run);

Now the quality metrics can be added to the relevant QualityAssessment in the QcML object. The basic element to describe a quality metric is the QualityParameter object. This object represents a single quality metric and contains all the relevant information. Such information is for example a reference to the controlled vocabulary that contains a defintion for this metric, and an accession number that identifies the quality metric in this controlled vocabulary; and of course the value of the quality metric.

// add a QualityParameter representing a quality metric
QualityParameter param = new QualityParameter("A quality metric", cvQC, "param_id");
param.setAccession("CV:000000");
param.setValue("42");

run.addQualityParameter(param);

Besides simple quality metrics, the qcML format also allows attachments to store additional information. These attachments are represented by an AttachmentParameter object. They can contain two types of data: either tabular data, or binary data. Tabular data can easily be added to an AttachmentParameter based on the row and column indices of the element in the table. Furthermore, binary data can serve to add more complex data, such as for example image files, and can be added directly as a base64 encoded string. In addition, jqcML is able to read files and convert the contents to a base64 encoded string as well.

// add an AttachmentParameter containing an image plot for a specific quality metric
AttachmentParameter attachment = new AttachmentParameter("An attachment", cvQC, "attach_id");
attachment.setAccession("CV:000001");
attachment.setBinaryFromFile(new File("image.png"));
attachment.setQualityParameterRef(param);

run.addAttachmentParameter(attachment);

Furthermore, MetaDataParameters containing metadata about the parameters can be added in the same way.

After all parameters have been added, the QcML object can be saved to a file, or to a qcDB. To save a QcML object, an instance of the QcMLWriter interface is used (either a QcMLFileWriter to write to a qcML file, or a QcDBWriter to write to a qcDB). Remember to set the file name for the qcML file before saving it.

// save the qcML object to an XML-based qcML file
QcMLFileWriter writer = new QcMLFileWriter();
qcml.setFileName("example.qcML");
writer.writeQcML(qcml);

This will create a new qcML file with the specified name.

This example illustrates how easy it is to create a new qcML file. The quality metrics that have been added to the qcML file can originate from several sources: jqcML can be used to create new qcML files with metrics that have been computed in a previous step, or to convert metrics generated by another tool to the qcML format. This example highlighted the most important elements of the qcML format, however, jqcML supports all the different information a qcML file can contain. For more detailed information on how to use jqcML, please see the Javadoc, which contains a detailed description of all methods jqcML provides.