Deliverable 8.2. Project ID Project Title. Project Acronym. Start Date of the Project. Duration of the Project. Work Package Number 8

Transcription

1 Deliverable 8.2 Project ID Project Title Project Acronym Start Date of the Project Duration of the Project A comprehensive and standardised e-infrastructure for analysing medical metabolic phenotype data PhenoMeNal 1st September Months Work Package Number 8 Work Package Title Deliverable Title Delivery Date Work Package leader Contributing Partners Authors Data provenance, compliance, and integrity D8.2 Modularised ISA model and format:biospecimen centric schema, corresponding xml schemas, reference implementation guidelines and validation rules M24 UOXF UOXF, EMBL-EBI,ICL. Philippe Rocca-Serra, Susanna-Assunta Sansone, Reza Salek, Kenneth Haug, Namrata Kale, Jake Pearce, Noureddin Saddawi, David Johnson, Alejandra Gonzalez- Beltran. Abstract: ISA representation is the data structure used by EMBL-EBI MetaboLights repository for metabolomic studies metadata. The format is also adopted by data-focussed publishers to handle datasets, such as Oxford University Press GigaScience and Springer Nature s Scientific Data). The initial format specifies rather informally the underlying model and how the syntactic elements are related to each other. The work presented here summarized how a set of JSON schemata, support JSON-LD context file for full semantic representations, as well as a clinical data set-orientated ISA configuration has been developed to produce a machine-readable serialization of the ISA model. Furthermore, this deliverable presents the latest developments of the ISA-API implementating the set of coding recommendations adopted by PhenoMeNal. EXECUTIVE SUMMARY 3 1

2 DETAILED REPORT OF THE DELIVERABLE 4 1. Creation of a machine-readable ISA model Background: Implementation: Normative documentations in readthedoc format Reference implementation: the ISA-API 6 2. Declaration of study design related information Background Coding Patterns and Recommendations Implementation 8 3. Declaration of Ethics and Legal Information Background Coding Patterns and Recommendations Implementation Declaration of Quality Control Elements Background Coding Patterns and Recommendation and Implementation Declaration of instrument vendor format and preprocessed data Background Coding Patterns, Recommendations and Implementation 16 WORK PLAN 16 DELIVERY AND SCHEDULE 17 CONCLUSION 17 2

3 1 EXECUTIVE SUMMARY The H2020 PhenoMeNal e-infrastructure project aims to deliver a scalable, robust and standards-compliant infrastructure for clinical phenotyping by means of metabolomics techniques. The main goal of the deliverable is to provide a formal, machine-readable specification of the ISA model, aiming at delivering a more prescriptive representation of experimental study metadata than those currently available from the initial ISA-Tab normative documents released in DETAILED REPORT OF THE DELIVERABLE 3

4 Creation of a machine-readable ISA model Background: The ISA specifications initially released in did not provide machine readable, formal representations, thus making it difficult for developers and implementers to built compliant tools owing to the potential risks associated with interpreting a textual description of a syntax specifications. The goal of the deliverable was to eliminate those shortcomings by producing a machine-readable serialization of the ISA model, to establish the foundation for a robust metadata management tracking and quality assessment for the PhenoMeNal project. Implementation: JSON Schema representation of ISA model WP8 has delivered an exhaustive and normative representation of the ISA syntax relying on JSON schema technology. A set of 21 JSON schemata have been produced, representing each of the core objects underlying the ISA tabular syntax (see figure 1); the work is available from the ISA github repository

5 Figure 1. An overview of the modular, JSON schema-based formal representation of the ISA model. Normative documentations in readthedoc format To further support the JSON schema representation, a full set of documentation has been released in the form of readthedoc microsite 3 (see Figure 2), 3 5

6 Figure 2. A screenshot showing the dedicated microsite based on the readthedoc approach. The site provides an up to date online resource for guiding users through the ISA specifications and serves information about the different types of serializations (tabular or JSON). Reference implementation: the ISA-API Built on top of the JSON schema definition, the ISA-API provides a set of tools to manipulate ISA objects, parse ISA documents in Tabular or JSON formats, build an object 6

7 representation and a graph data structure, which allows fast traversal of information, as well as validation against the syntax. Additional components have been added to further validate information supplied in ISA syntax. These additional validation steps are required in particular by conversion modules to third party formats. These are formats used by public repositories for non-metabolomics related omics data types such as transcriptomics and genomics. The ISA- API converters allow data processing for repositories such as EMBL-EBI ArrayExpress or EMBL-EBI Short Read Archive. Both repositories have specific annotation needs, which need to be dealt with. The ISA-API is available from the GitHub repository 4, Figure 3. A screenshot of the ISA-API GitHub repository, which provides documentation and assistance to developers that wish to use or contribute to the work. Declaration of study design related information 4 7

8 Background A systematic analysis of EMBL-EBI Metabolights has been performed as means to test the validity and efficiency of PhenoMenal workflows. The results indicate that nearly 50% of ISA archives served by the European repository contain a syntactic or structural error. A finer review shows that 25% fail a basic syntactic validation invoking the relevant function from ISA-API. Another 24% reveals errors, when tested for semantic content using additional function from the ISA-API. The errors belong to 2 distinct classes but both affect automatic handling of the document by analysis workflows. The first type of error corresponds to the declaration of spurious ISA Experimental Factors, which are meant to represent independent variables as declared by experimentalists. They are therefore meant to encompass a range of discrete values. A simple inspection of the ranges exposes the errors. In a number of cases, submitters and curators confuse independent variables and covariates (e.g. typically experiments declaring more than 6 factors should attract suspicion: e.g. MTBLS124 or MTBLS93 with combinations). The second type of error is structural and corresponds to a failure to properly represent the underlying relationships between subject-derived material and data acquisition events. This type of error is harder to detect as the ISA-Tab documents are syntactically valid however the information representation is erroneous. This leads to failure to properly determine sample size and therefore computation cannot be automated or if it passes the checks would produce erroneous results. Coding Patterns and Recommendations As pointed out already, the possibilities offered by PhenoMeNal workflows in terms of batch processing public datasets highlighted problems in annotation consistency. The ISA-API function to pull datasets from NIH Metabolomics Workbench, the US counterpart for EMBL-EBI MetaboLights also revealed metadata elements absent from MetaboLights metadata. To address these issues and converge towards a common set of descriptors, the PhenoMeNal ISA configuration now provided several new fields in the Study Design Descriptor Section of ISA document to report key summary information, which can help data discovery. These are summarized below. Augmented annotation for study designs Study Design Ontology Terms: {full factorial design, fractional factorial design} Comment[number of factor level] Comment[study subject count] Comment[number of treatment groups] Implementation 8

9 The ISA-API now implements several curation functions to detect and, to some extent, correct errors of the type mentioned above. At least, the newly developed functions provide curators additional information to direct their actions. The functions deliver simple yet effective means to significantly increase the quality of ISA archive documents generated by submission tools and pipeline. The ISA-API is now augmented with a creation mode, which can be used to bootstrap the creation of ISA documents by using study design information from users. The main feature of the code behind the functionality is the reliance of patterns, specific to a number of experimental designs (e.g. factorial design, balanced design, repeated measure designs), which can be applied irrespective of the type of data acquisition used. While the initial function has been developed to primarily support the reporting the MS and NMR based studies, we demonstrated the portability of the approach by implementing support for DNA microarray and next generation sequencing based signal acquisition. The code is available from the following github repository 5. To further demonstrate the benefits of the component, a series of jupyter notebooks have been built and can be used as basis for tutorial and training. A youtube video is being prepared and will be released as an update to this deliverable. The code is available from the following github repository 6 (see also Figure 4). Figure 4: A screenshot of the ISA-tools github repository showing six ipython notebooks devised to showcase the ISA-API capability to support MS and NMR based metabolomics studies but also applications of molecular biology technique for transcriptomics and genomics studies

10 As indicated above, the ISA-API can support multi-omics datasets owing to its native support for an array of molecular biology technique, a benefit from the modular approach allowed by the new ISA JSON schemata and the reliance on ISA configurations (see figure 5). Figure 5: A detailed view of the ipython notebook showing mobilisation of ISA-API create mode to rapidly generate an ISA archive document based on study design information prompted by the toolkit from users. This example shows how this is a applied to the specific case of NMR based data acquisition. 10

11 Declaration of Ethics and Legal Information Background In order to comply with EU regulations on data protection, privacy and ethics, metadata descriptors covering terms of use, consent availability and additional ancillary information has to be provided as part of study archives. Such information, when present in the ISA structured Metabolomics study metadata, could be used in downstream workflows to check whether requesters have the relevant privileges against the dataset s actual terms of use. Having such information embedded in ISA documents would greatly enhance the possibilities of devising a set of safety checks in additions to those already in place. Coding Patterns and Recommendations ISA documents can be annotated with data use information, implementing a series of ISA Comment fields holding values selected from the DUO, the data use ontology 7,8 values. The practice is in agreement with efforts carried out in the context of the Global Alliance for Genomic Health (GA4GH). 9 An ISA configuration file for clinical context has been amended and posted to Github: It is now the pattern to follow to report: - terms of use - ethical committee name - ethical committee project identification - url to data access committee - information about patient consent availability Implementation ISA configurations relevant to human patient based studies have been updated accordingly. The code is available from the GitHub repository "The Data Use Ontology - EMBL-EBI." 20 Feb. 2017, Accessed 31 Aug "The Data Use Ontology - The OBO Foundry." Accessed 31 Aug "Global Alliance for Genomics and Health." Accessed 31 Aug

12 Figure 6. panel a: an overview of the PhenoMeNal specific ISA configuration, documenting the implementation guidelines and patterns. 12

13 Figure 6. Panel b: The investigation.xml. 13

14 Figure 6. panel c: studysample.xml hold the ELSI related annotation elements in the form the ISA Comment fields configured to hold Data Use Ontology (DUO) terms (shown highlighted in pale yellow). Declaration of Quality Control Elements Background 14

15 It has been pointed out that metabolomics signal can only be properly analyzed if all the contextual information surrounding data acquisition events is provided. In particular, the reporting of all controls injected alongside test samples in mass spectrometry applications constitutes an essential quality insurance element. Up until now no requirements were made on users to deposit such data by public repositories. There was therefore no guideline for submission. The work reported in this deliverable closes this gap. Coding Patterns and Recommendation and Implementation Introduction the Terminology for reporting QC as established by the working group 8 and reported earlier. The terminology defined then is now available for us in the form of a new version of the ISA configuration for handling patient based datasets. The configuration is available from the ISA-tools github repository. More specifically, the element to consider is the following i. header="material Type", required=true <list-values>specimen,long-term reference,external long-term reference,study reference,dilution series reference,standard reference material,normal blank,reagent blank,sample preparation blank,batch terminus,negative control reference (blank),positive control reference (standard)</list-values> In addition, the ISA-API create mode is being augmented with a function allowing the reporting of all control elements following the definition and declaration of the experimental plan. This feature has been developed based on a similar function present in Mastr-MS and following discussions with Dr Saravanan Dayalan (Australia, Queensland university). NOTE: This work is not complete at time of the deliverable but the implementation is ongoing. Declaration of instrument vendor format and preprocessed data Background Instrument generated data most often come in vendor specific formats, some of which are organized in a directory structure. Such is the case for Bruker NMR data. While open standard formats exist to produce a vendor neutral equivalent information file (.e.g mzml in mass spectrometry context, nmrml in nuclear magnetic resonance context), there is a demand for keeping native instrument output. This request by users and metabolomics practitioners highlighted the need for coding guidelines for representing both types of raw information. In ISA format, a specific syntactic element (Raw Data File) exists but it is not repeatable. In other words, only one occurrence of the field element may appear in any one ISA assay 15

16 table. Therefore users need guidance to represent vendor native data as well as vendor neutral corresponding information. Coding Patterns, Recommendations and Implementation Reporting Vendor Specific Formatted Data Only (no conversion to open standard) Use of ISA Raw Data File and provide vendor file as tar.gz file and a ISA Comment[vendor] Field Reporting both Vendor Specific and Open Standard converted data: ISA NMR: Bruker files ISA Raw Data File: to provide uri to zip, md5 checksummed vendor file ISA Derived Data File to provide URI to nmrml zipped and checksummed file. MS: Waters files ISA Raw Data File: to provide uri to zip, md5 checksummed vendor file ISA Raw Data File: to provide uri to zip, md5 checksummed vendor file ISA Derived Data File to provide URI to mzml zipped and checksummed file. WORK PLAN Consistent with the work so far and building on it, WP8 s attention for deliverable D8.4 has been focused on collecting the needs from the community and practitioners, regularly meeting with them and reaching out for input in order to shape specifications attuned to use cases. The actual delivery of the standardization format and supporting documentation is meant to take place in the remaining tasks and deliverables (T8.4 and D8.4.1-D8.4.2, on month 24 and month 30 respectively. Objectives O8.1 Define metadata and data exchange standards, along with technical and user documentations. O8.2 Implement and maintain PhenoMeNal reference implementations. Tasks T8.1: Use cases and state of the art of communication standards T8.2: Standards for exchanging experimental and clinical metadata T8.3: Data standards exchange formats T8.4: Harmonization of data matrices and analytical results 16

17 T8.5: Maintain documentation and disseminate information Deliverables D8.1 Report on community standards for reporting, access and integrity supported in the PhenoMeNal grid; to be disseminated in a dedicated BioSharing page and via the project website. (M12) D8.2: Modularized ISA model and format: biospecimen centric schema, corresponding xml schemas, reference implementation guidelines and validation rules. (M24) D8.3: nmrml, mzml data exchange formats and associated terminologies for instrument raw, with reference implementation guidelines and validation rules. (M18) D8.4: Signal processing and analysis data exchange format D8.4.1: Specifications for derived data matrices, specifications and terminology for description of analysis and statistical results (M24) D8.4.2: Reference implementation guidelines and validation rules (M30) DELIVERY AND SCHEDULE The delivery is delayed: No CONCLUSION The delivery of the machine readable specifications of the ISA syntax along with the supporting ISA-API for read/write calls, syntactic validation and content checking, as well as conversion capabilities to other formats gives metabolomics users powerful tools for structuring experimental metadata to high levels of quality. The recent addition of a create mode to boostrap creation of ISA documents adds a unique capability, that of moving data management from a retrospective activity to a prospective one. Indeed, the ISA-API create function enables the creation of prepopulation metadata capture templates by placing the notion of study design at the core of the reporting. The coming months will see deeper validation and testing of the approach by deploying the API with several Phenome Centres. 17