-
Notifications
You must be signed in to change notification settings - Fork 6
/
Copy pathmzTab_m_swagger.yml
1912 lines (1850 loc) · 97.5 KB
/
mzTab_m_swagger.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
swagger: '2.0'
info:
description: This is the mzTab-M reference implementation and validation API service.
version: 2.0.0
title: mzTab-M reference implementation and validation API.
contact:
email: nils.hoffmann@cebitec.uni-bielefeld.de
license:
name: Apache 2.0
url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
host: apps.lifs-tools.org
basePath: /mztabvalidator/rest/v2/
x-global-options:
go_package: mztabm
schemes:
- https
tags:
- name: validate
description: mzTab validation
externalDocs:
description: mzTab-M specification
url: 'https://github.com/HUPO-PSI/mzTab'
paths:
/validatePlain:
post:
description: |
Validates an mzTab file in plain text representation / tab-separated format and reports
syntactic, structural, and semantic
errors.
operationId: validatePlainMzTabFile
tags:
- validatePlain
consumes:
- text/tab-separated-values
- text/plain
produces:
- application/json
parameters:
- in: body
name: mztabfile
description: mzTab file that should be validated.
required: true
schema:
type: string
- name: level
in: query
description: >-
The level of errors that should be reported, one of ERROR, WARN,
INFO.
required: false
type: string
enum:
- info
- warn
- error
default: info
- name: maxErrors
in: query
description: The maximum number of errors to return.
required: false
type: integer
format: int32
minimum: 0
maximum: 500
default: 100
- name: semanticValidation
in: query
description: >-
Whether a semantic validation against the default rule set should be
performed.
required: false
type: boolean
default: false
responses:
'200':
description: Validation Okay
schema:
type: array
default: []
items:
$ref: '#/definitions/ValidationMessage'
'415':
description: Unsupported content type
'422':
description: Invalid input
schema:
type: array
default: []
items:
$ref: '#/definitions/ValidationMessage'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/validate:
post:
description: >
Validates an mzTab file in XML or JSON representation and reports
syntactic, structural, and semantic
errors.
operationId: validateMzTabFile
tags:
- validate
consumes:
- application/json
- application/xml
produces:
- application/json
parameters:
- name: mztabfile
in: body
description: mzTab file that should be validated.
required: true
schema:
$ref: '#/definitions/MzTab'
- name: level
in: query
description: >-
The level of errors that should be reported, one of ERROR, WARN,
INFO.
required: false
type: string
enum:
- info
- warn
- error
default: info
- name: maxErrors
in: query
description: The maximum number of errors to return.
required: false
type: integer
format: int32
minimum: 0
maximum: 500
default: 100
- name: semanticValidation
in: query
description: >-
Whether a semantic validation against the default rule set should be
performed.
required: false
type: boolean
default: false
responses:
'200':
description: Validation Okay
schema:
type: array
default: []
items:
$ref: '#/definitions/ValidationMessage'
'415':
description: Unsupported content type
'422':
description: Invalid input
schema:
type: array
default: []
items:
$ref: '#/definitions/ValidationMessage'
default:
description: Unexpected error
schema:
$ref: '#/definitions/Error'
/convertPlain:
post:
description: >
Converts an mzTab file in tab separated format to XML or JSON representation.
If this method returns an error code 422, the provided file did not pass validation.
operationId: convertPlainMzTabFile
tags:
- convertPlain
consumes:
- application/json
- application/xml
produces:
- text/tab-separated-values
parameters:
- in: body
name: mztabfile
description: mzTab file that should be converted.
required: true
schema:
type: string
responses:
'200':
description: Conversion Okay
schema:
$ref: '#/definitions/MzTab'
'415':
description: Unsupported content type
'422':
description: Invalid input
default:
description: Unexpected error
/convert:
post:
description: >
Converts an mzTab file in JSON or XML format to the tab-separated representation.
If this method returns an error code 422, the provided file did not pass validation.
operationId: convertMzTabFile
tags:
- convert
consumes:
- text/tab-separated-values
- text/plain
produces:
- application/json
parameters:
- name: mztabfile
in: body
description: mzTab file that should be validated.
required: true
schema:
$ref: '#/definitions/MzTab'
responses:
'200':
description: Conversion Okay
schema:
type: string
'415':
description: Unsupported content type
'422':
description: Invalid input
default:
description: Unexpected error
definitions:
MzTab:
type: object
description: |
mzTab-M is intended as a reporting standard for quantitative results from metabolomics/lipodomics approaches.
This format is further intended to provide local LIMS systems as well as MS metabolomics repositories a simple way to share and combine basic information.
The mzTab-M format consists of four cross-referenced data tables:
* Metadata (MTD),
* Small Molecule (SML),
* Small Molecule Feature (SMF) and the
* Small Molecule Evidence (SME).
The MTD and SML tables are mandatory, and for a file to contain any evidence about how molecules were quantified or identified by software, then all four tables must be present. The tables must follow the order MTD, SML, SMF and SME, with a blank line separating each table.
The structure of each table, in terms of the rows and columns that must be present is tightly specified and formally defined and explained in the mzTab-M specification document.
mzTab-M files MUST have one Metadata (MTD) section and one Small Molecule (SML) Section. In practice, we expect that most files SHOULD also include one Small Molecule Feature (SMF) section, and one Small Molecule Evidence (SME) Section.
Files lacking SMF and SME sections can only present summary data about quantified molecules, without any evidence trail for how those values were derived. It will be left to reading software to determine whether additional validation will be requested such that SMF and SME tables MUST be present.
required:
- metadata
- smallMoleculeSummary
- smallMoleculeFeature
- smallMoleculeEvidence
properties:
metadata:
$ref: '#/definitions/Metadata'
smallMoleculeSummary:
description: |
The small molecule section is table-based. The small molecule section MUST always come after the metadata section. All table columns MUST be Tab separated. There MUST NOT be any empty cells; missing values MUST be reported using “null” for columns where Is Nullable = “True”.
Each row of the small molecule section is intended to report one final result to be communicated in terms of a molecule that has been quantified. In many cases, this may be the molecule of biological interest, although in some cases, the final result could be a derivatized form as appropriate – although it is desirable for the database identifier(s) to reference to the biological (non-derivatized) form. In general, different adduct forms would generally be reported in the Small Molecule Feature section.
The order of columns MUST follow the order specified below.
All columns are MANDATORY except for “opt_” columns.
type: array
default: []
minItems: 1
items:
$ref: '#/definitions/SmallMoleculeSummary'
smallMoleculeFeature:
description: |
The small molecule feature section is table-based, representing individual MS regions (generally considered to be the elution profile for all isotopomers formed from a single charge state of a molecule), that have been measured/quantified. However, for approaches that quantify individual isotopomers e.g. stable isotope labelling/flux studies, then each SMF row SHOULD represent a single isotopomer.
Different adducts or derivatives and different charge states of individual molecules should be reported as separate SMF rows.
The small molecule feature section MUST always come after the Small Molecule Table. All table columns MUST be Tab separated. There MUST NOT be any empty cells. Missing values MUST be reported using “null”.
The order of columns MUST follow the order specified below.
All columns are MANDATORY except for “opt_” columns.
type: array
default: []
items:
$ref: '#/definitions/SmallMoleculeFeature'
smallMoleculeEvidence:
description: |
The small molecule evidence section is table-based, representing evidence for identifications of small molecules/features, from database search or any other process used to give putative identifications to molecules. In a typical case, each row represents one result from a single search or intepretation of a piece of evidence e.g. a database search with a fragmentation spectrum. Multiple results from a given input data item (e.g. one fragment spectrum) SHOULD share the same value under evidence_input_id.
The small molecule evidence section MUST always come after the Small Molecule Feature Table. All table columns MUST be Tab separated. There MUST NOT be any empty cells. Missing values MUST be reported using “null”.
The order of columns MUST follow the order specified below.
All columns are MANDATORY except for “opt_” columns.
type: array
default: []
items:
$ref: '#/definitions/SmallMoleculeEvidence'
comment:
description: |
Comment lines can be placed anywhere in an mzTab file. These lines must start with the three-letter code COM and are ignored by most parsers. Empty lines can also occur anywhere in an mzTab file and are ignored.
type: array
default: []
items:
$ref: '#/definitions/Comment'
Comment:
type: object
description: |
Comment lines can be placed anywhere in an mzTab file. These lines must start with the three-letter code COM and are ignored by most parsers. Empty lines can also occur anywhere in an mzTab file and are ignored.
x-mztab-example: |
COM This is a comment line
required:
- prefix
- msg
properties:
prefix:
type: string
enum:
- COM
default: COM
msg:
type: string
line_number:
type: integer
format: int32
# IndexedElement:
# type: object
# description: Indexed elements (IDs) define a unique ID for a collection of multiple metadata elements of the same type within the mzTab-M document, e.g. for sample, assay, study variable etc.
# x-mztab-example: |
# MTD sample[1]-species[1] [NCBITaxon, NCBITaxon:9606, Homo sapiens, ]
# MTD assay[1] first assay description
# MTD study_variable[1] Group B (spike-in 0.74 fmol/uL)
# discriminator: elementType
# required:
# - id
# - elementType
# properties:
# id:
# type: integer
# format: int32
# minimum: 1
# elementType:
# type: string
# default: element_type
Metadata:
type: object
description: |
The metadata section provides additional information about the dataset(s) reported in the mzTab file. All fields in the metadata section are optional apart from those noted as mandatory. The fields in the metadata section MUST be reported in order of the various fields listed here. The field’s name and value MUST be separated by a tab character.
x-mztab-example: |
MTD mzTab-version 2.0.0-M
MTD mzTab-ID MTBL1234
MTD title Effects of Rapamycin on metabolite profile
...
required:
- prefix
- fileDescription
- mzTab-version
- mzTab-ID
- quantification_method
- software
- ms_run
- assay
- study_variable
- cv
- database
- small_molecule-quantification_unit
- small_molecule_feature-quantification_unit
- id_confidence_measure
properties:
prefix:
type: string
description: |
The metadata section prefix. MUST always be MTD.
enum:
- MTD
default: MTD
example: MTD
mzTab-version:
type: string
description: |
The version of the mzTab file. The suffix MUST be "-M" for mzTab for metabolomics (mzTab-M).
pattern: '^\d{1}\.\d{1}\.\d{1}-[A-Z]{1}$'
x-mztab-example: |
MTD mzTab-version 2.0.0-M
MTD mzTab-version 2.0.1-M
mzTab-ID:
type: string
description: |
The ID of the mzTab file, this could be supplied by the repository from which it is downloaded or a local identifier from the lab producing the file. It is not intended to be a globally unique ID but carry some locally useful meaning.
example: MTD mzTab-ID MTBLS214
title:
type: string
description: |
The file’s human readable title.
example: MTD title My first test experiment
description:
type: string
description: |
The file’s human readable description.
example: MTD description An experiment investigating the effects of Il-6.
contact:
type: array
description: The contact’s name, affiliation and e-mail. Several contacts can be given by indicating the number in the square brackets after "contact". A contact has to be supplied in the format [first name] [initials] [last name].
default: []
items:
$ref: '#/definitions/Contact'
x-mztab-example: |
MTD contact[1]-name James D. Watson
MTD contact[1]-affiliation Cambridge University, UK
MTD contact[1]-email watson@cam.ac.uk
MTD contact[2]-name Francis Crick
MTD contact[2]-affiliation Cambridge University, UK
MTD contact[2]-email crick@cam.ac.uk
MTD contact[2]-orcid 0000-0002-1825-0097
publication:
type: array
description: A publication associated with this file. Several publications can be given by indicating the number in the square brackets after “publication”. PubMed ids must be prefixed by “pubmed:”, DOIs by “doi:”. Multiple identifiers MUST be separated by “|”.
default: []
items:
$ref: '#/definitions/Publication'
x-mztab-example: |
MTD publication[1] pubmed:21063943|doi:10.1007/978-1-60761-987-1_6
MTD publication[2] pubmed:20615486|doi:10.1016/j.jprot.2010.06.008
uri:
type: array
description: A URI pointing to the file’s source data (e.g., a MetaboLights records).
default: []
items:
$ref: '#/definitions/Uri'
x-mztab-example: |
MTD uri[1] https://www.ebi.ac.uk/metabolights/MTBLS517
external_study_uri:
type: array
description: A URI pointing to an external file with more details about the study design (e.g., an ISA-TAB file).
default: []
items:
$ref: '#/definitions/Uri'
x-mztab-example: |
MTD external_study_uri[1] https://www.ebi.ac.uk/metabolights/MTBLS517/files/i_Investigation.txt
instrument:
type: array
description: The name, source, analyzer and detector of the instruments used in the experiment. Multiple instruments are numbered [1-n].
default: []
items:
$ref: '#/definitions/Instrument'
x-mztab-example: |
MTD instrument[1]-name [MS, MS:1000449, LTQ Orbitrap,]
MTD instrument[1]-source [MS, MS:1000073, ESI,]
…
MTD instrument[2]-source [MS, MS:1000598, ETD,]
MTD instrument[1]-analyzer[1] [MS, MS:1000291, linear ion trap,]
…
MTD instrument[2]-analyzer[1] [MS, MS:1000484, orbitrap,]
MTD instrument[1]-detector [MS, MS:1000253, electron multiplier,]
…
MTD instrument[2]-detector [MS, MS:1000348, focal plane collector,]
quantification_method:
$ref: '#/definitions/Parameter'
description: The quantification method used in the experiment reported in the file.
x-mztab-example: |
MTD quantification_method [MS, MS:1001834, LC-MS label-free quantitation analysis, ]
sample:
type: array
description: |
Specification of sample.
(empty) name: A name for each sample to serve as a list of the samples that MUST be reported in the following tables. Samples MUST be reported if a statistical design is being captured (i.e. bio or tech replicates). If the type of replicates are not known, samples SHOULD NOT be reported.
species: The respective species of the samples analysed. For more complex cases, such as metagenomics, optional columns and userParams should be used.
tissue: The respective tissue(s) of the sample.
cell_type: The respective cell type(s) of the sample.
disease: The respective disease(s) of the sample.
description: A human readable description of the sample.
custom: Custom parameters describing the sample’s additional properties. Dates MUST be provided in ISO-8601 format.
default: []
items:
$ref: '#/definitions/Sample'
x-mztab-example: |
COM Experiment where all samples consisted of the same two species
MTD sample[1] individual number 1
MTD sample[1]-species[1] [NCBITaxon, NCBITaxon:9606, Homo sapiens, ]
MTD sample[1]-tissue[1] [BTO, BTO:0000759, liver, ]
MTD sample[1]-cell_type[1] [CL, CL:0000182, hepatocyte, ]
MTD sample[1]-disease[1] [DOID, DOID:684, hepatocellular carcinoma, ]
MTD sample[1]-disease[2] [DOID, DOID:9451, alcoholic fatty liver, ]
MTD sample[1]-description Hepatocellular carcinoma samples.
MTD sample[1]-custom[1] [,,Extraction date, 2011-12-21]
MTD sample[1]-custom[2] [,,Extraction reason, liver biopsy]
MTD sample[2] individual number 2
MTD sample[2]-species[1] [NCBITaxon, NCBITaxon:9606, Homo sapiens, ]
MTD sample[2]-tissue[1] [BTO, BTO:0000759, liver, ]
MTD sample[2]-cell_type[1] [CL, CL:0000182, hepatocyte, ]
MTD sample[2]-description Healthy control samples.
sample_processing:
type: array
description: |
A list of parameters describing a sample processing, preparation or handling step similar to a biological or analytical methods report. The order of the sample_processing items should reflect the order these processing steps were performed in. If multiple parameters are given for a step these MUST be separated by a “|”. If derivatization was performed, it MUST be reported here as a general step, e.g. 'silylation' and the actual derivatization agens MUST be specified in the Section 6.2.54 part.
default: []
items:
$ref: '#/definitions/SampleProcessing'
x-mztab-example: |
MTD sample_processing[1] [MSIO, MSIO:0000107, metabolism quenching using precooled 60 percent methanol ammonium bicarbonate buffer,]
MTD sample_processing[2] [MSIO, MSIO:0000146, centrifugation,]
MTD sample_processing[3] [MSIO, MSIO:0000141, metabolite extraction,]
MTD sample_processing[4] [MSIO, MSIO:0000141, silylation,]
software:
type: array
description: Software used to analyze the data and obtain the reported results. The parameter’s value SHOULD contain the software’s version. The order (numbering) should reflect the order in which the tools were used. A software setting used. This field MAY occur multiple times for a single software. The value of this field is deliberately set as a String, since there currently do not exist CV terms for every possible setting.
default: []
items:
$ref: '#/definitions/Software'
x-mztab-example: |
MTD software[1] [MS, MS:1002879, Progenesis QI, 3.0]
MTD software[1]-setting Fragment tolerance = 0.1 Da
…
MTD software[2]-setting Parent tolerance = 0.5 Da
derivatization_agent:
type: array
description: A description of derivatization agents applied to small molecules, using userParams or CV terms where possible.
default: []
items:
$ref: '#/definitions/Parameter'
x-mztab-example: |
MTD derivatization_agent[1] [XLMOD, XLMOD:07014, N-methyl-N-t-butyldimethylsilyltrifluoroacetamide, ]
ms_run:
type: array
description: |
Specification of ms_run.
location: Location of the external data file e.g. raw files on which analysis has been performed. If the actual location of the MS run is unknown, a “null” MUST be used as a place holder value, since the [1-n] cardinality is referenced elsewhere. If pre-fractionation has been performed, then [1-n] ms_runs SHOULD be created per assay.
instrument_ref: If different instruments are used in different runs, instrument_ref can be used to link a specific instrument to a specific run.
format: Parameter specifying the data format of the external MS data file. If ms_run[1-n]-format is present, ms_run[1-n]-id_format SHOULD also be present, following the parameters specified in Table 1.
id_format: Parameter specifying the id format used in the external data file. If ms_run[1-n]-id_format is present, ms_run[1-n]-format SHOULD also be present.
fragmentation_method: The type(s) of fragmentation used in a given ms run.
scan_polarity: The polarity mode of a given run. Usually only one value SHOULD be given here except for the case of mixed polarity runs.
hash: Hash value of the corresponding external MS data file defined in ms_run[1-n]-location. If ms_run[1-n]-hash is present, ms_run[1-n]-hash_method SHOULD also be present.
hash_method: A parameter specifying the hash methods used to generate the String in ms_run[1-n]-hash. Specifics of the hash method used MAY follow the definitions of the mzML format. If ms_run[1-n]-hash is present, ms_run[1-n]-hash_method SHOULD also be present.
default: []
items:
$ref: '#/definitions/MsRun'
x-mztab-example: |
COM location can be a local or remote URI
MTD ms_run[1]-location file:///C:/path/to/my/file.mzML
MTD ms_run[1]-instrument_ref instrument[1]
MTD ms_run[1]-format [MS, MS:1000584, mzML file, ]
MTD ms_run[1]-id_format [MS, MS:1000530, mzML unique identifier, ]
MTD ms_run[1]-fragmentation_method[1] [MS, MS:1000133, CID, ]
COM for mixed polarity scan scenarios
MTD ms_run[1]-scan_polarity[1] [MS, MS:1000130, positive scan, ]
MTD ms_run[1]-scan_polarity[2] [MS, MS:1000129, negative scan, ]
MTD ms_run[1]-hash_method [MS, MS:1000569, SHA-1, ]
MTD ms_run[1]-hash de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3
assay:
type: array
description: |
Specification of assay.
(empty) name: A name for each assay, to serve as a list of the assays that MUST be reported in the following tables.
custom: Additional custom parameters or values for a given assay.
external_uri: An external reference uri to further information about the assay, for example via a reference to an object within an ISA-TAB file.
sample_ref: An association from a given assay to the sample analysed.
ms_run_ref: An association from a given assay to the source MS run. All assays MUST reference exactly one ms_run unless a workflow with pre-fractionation is being encoded, in which case each assay MUST reference n ms_runs where n fractions have been collected. Multiple assays SHOULD reference the same ms_run to capture multiplexed experimental designs.
default: []
items:
$ref: '#/definitions/Assay'
x-mztab-example: |
MTD assay[1] first assay
MTD assay[1]-custom[1] [MS, , Assay operator, Fred Blogs]
MTD assay[1]-sample_ref sample[1]
MTD assay[1]-ms_run_ref ms_run[1]
MTD assay[1]-external_uri https://www.ebi.ac.uk/metabolights/MTBLS517/files/i_Investigation.txt?STUDYASSAY=a_e04_c18pos.txt
MTD assay[2] second assay
MTD assay[2]-sample_ref sample[2]
study_variable:
type: array
description: |
Specification of study_variable.
(empty) name: A name for each study variable (experimental condition or factor), to serve as a list of the study variables that MUST be reported in the following tables. For software that does not capture study variables, a single study variable MUST be reported, linking to all assays. This single study variable MUST have the identifier “undefined“.
assay_refs: Bar-separated references to the IDs of assays grouped in the study variable.
average_function: The function used to calculate the study variable quantification value and the operation used is not arithmetic mean (default) e.g. “geometric mean”, “median”. The 1-n refers to different study variables.
variation_function: The function used to calculate the study variable quantification variation value if it is reported and the operation used is not coefficient of variation (default) e.g. “standard error”.
description: A textual description of the study variable.
factors: Additional parameters or factors, separated by bars, that are known about study variables allowing the capture of more complex, such as nested designs.
default: []
items:
$ref: '#/definitions/StudyVariable'
x-mztab-example: |
MTD study_variable[1] control
MTD study_variable[1]-assay_refs assay[1]| assay[2]| assay[3]
MTD study_variable-average_function [MS, MS:1002883, median, ]
MTD study_variable-variation_function [MS, MS:1002885, standard error, ]
MTD study_variable[1]-description Group B (spike-in 0.74 fmol/uL)
MTD study_variable[1]-factors [,,rapamycin dose,0.5mg]
MTD study_variable[2] 1 minute
custom:
type: array
description: Any additional parameters describing the analysis reported.
default: []
items:
$ref: '#/definitions/Parameter'
x-mztab-example: |
MTD custom[1] [,,MS operator, Florian]
cv:
type: array
description: |
Specification of controlled vocabularies.
label: A string describing the labels of the controlled vocabularies/ontologies used in the mzTab file as a short-hand e.g. "MS" for PSI-MS.
full_name: A string describing the full names of the controlled vocabularies/ontologies used in the mzTab file.
version: A string describing the version of the controlled vocabularies/ontologies used in the mzTab file.
uri: A string containing the URIs of the controlled vocabularies/ontologies used in the mzTab file.
default: []
items:
$ref: '#/definitions/CV'
x-mztab-example: |
MTD cv[1]-label MS
MTD cv[1]-full_name PSI-MS controlled vocabulary
MTD cv[1]-version 4.1.11
MTD cv[1]-uri https://raw.githubusercontent.com/HUPO-PSI/psi-ms-CV/master/psi-ms.obo
small_molecule-quantification_unit:
$ref: '#/definitions/Parameter'
description: Defines what type of units are reported in the small molecule summary quantification / abundance fields.
x-mztab-example: |
MTD small_molecule-quantification_unit [MS, MS:1002887, Progenesis QI normalised abundance, ]
small_molecule_feature-quantification_unit:
$ref: '#/definitions/Parameter'
description: Defines what type of units are reported in the small molecule feature quantification / abundance fields.
x-mztab-example: |
MTD small_molecule_feature-quantification_unit [MS, MS:1002887, Progenesis QI normalised abundance, ]
small_molecule-identification_reliability:
$ref: '#/definitions/Parameter'
description: The system used for giving reliability / confidence codes to small molecule identifications MUST be specified if not using the default codes.
x-mztab-example: |
MTD small_molecule-identification_reliability [MS, MS:1002896, compound identification confidence level, ]
or
MTD small_molecule-identification_reliability [MS, MS:1002955, hr-ms compound identification confidence level, ]
database:
type: array
description: |
Specification of databases.
(empty): The description of databases used. For cases, where a known database has not been used for identification, a userParam SHOULD be inserted to describe any identification performed e.g. de novo. If no identification has been performed at all then "no database" should be inserted followed by null.
prefix: The prefix used in the “identifier” column of data tables. For the “no database” case "null" must be used.
version: The database version is mandatory where identification has been performed. This may be a formal version number e.g. “1.4.1”, a date of access “2016-10-27” (ISO-8601 format) or “Unknown” if there is no suitable version that can be annotated.
uri: The URI to the database. For the “no database” case, "null" must be reported.
default: []
items:
$ref: '#/definitions/Database'
x-mztab-example: |
MTD database[1] [MIRIAM, MIR:00100079, HMDB, ]
MTD database[1]-prefix hmdb
MTD database[1]-version 3.6
MTD database[1]-uri http://www.hmdb.ca/
MTD database[2] [,, "de novo", ]
MTD database[2]-prefix dn
MTD database[2]-version Unknown
MTD database[2]-uri null
MTD database[3] [,, "no database", null ]
MTD database[3]-prefix null
MTD database[3]-version Unknown
MTD database[3]-uri null
id_confidence_measure:
type: array
description: The type of small molecule confidence measures or scores MUST be reported as a CV parameter [1-n]. The CV parameter definition should formally state whether the ordering is high to low or vice versa. The order of the scores SHOULD reflect their importance for the identification and be used to determine the identification’s rank.
default: []
items:
$ref: '#/definitions/Parameter'
x-mztab-example: |
MTD id_confidence_measure[1] [MS,MS:1002889,Progenesis MetaScope Score,]
MTD id_confidence_measure[2] [MS,MS:1002890,fragmentation score,]
MTD id_confidence_measure[3] [MS,MS:1002891,isotopic fit score,]
colunit-small_molecule:
type: array
description: Defines the used unit for a column in the small molecule section. The format of the value has to be \{column name}=\{Parameter defining the unit}. This field MUST NOT be used to define a unit for quantification columns. The unit used for small molecule quantification values MUST be set in small_molecule-quantification_unit.
default: []
items:
$ref: '#/definitions/ColumnParameterMapping'
x-mztab-example: |
COM colunit for optional small molecule summary column with the name 'opt_global_cv_MS:MS:1002954_collisional_cross_sectional_area'
MTD colunit-small_molecule opt_global_cv_MS:MS:1002954_collisional_cross_sectional_area=[UO,UO:00003241, square angstrom,]
colunit-small_molecule_feature:
type: array
description: Defines the used unit for a column in the small molecule feature section. The format of the value has to be \{column name}=\{Parameter defining the unit}. This field MUST NOT be used to define a unit for quantification columns. The unit used for small molecule quantification values MUST be set in small_molecule_feature-quantification_unit.
default: []
items:
$ref: '#/definitions/ColumnParameterMapping'
x-mztab-example: |
COM colunit for optional small molecule feature column with the name 'opt_ms_run[1]_cv_MS:MS:1002476_ion_mobility_drift_time' referencing ms_run[1]
MTD colunit-small_molecule_feature opt_ms_run[1]_cv_MS:MS:1002476_ion_mobility_drift_time=[UO,UO:0000031, minute,]
colunit-small_molecule_evidence:
type: array
description: Defines the used unit for a column in the small molecule evidence section. The format of the value has to be \{column name}=\{Parameter defining the unit}.
default: []
items:
$ref: '#/definitions/ColumnParameterMapping'
x-mztab-example: |
COM colunit for optional small molecule evidence column with the name 'opt_global_mass_error'
MTD colunit-small_molecule_evidence opt_global_mass_error=[UO, UO:0000169, parts per million, ]
SmallMoleculeSummary:
type: object
description: |
The small molecule summary section is table-based, represented summarized quantitative information across assays and study variables, grouped by identification in rows. The small molecule section MUST always come after the metadata section. All table columns MUST be Tab separated. There MUST NOT be any empty cells; missing values MUST be reported using “null” for columns where Is Nullable = “True”.
Each row of the small molecule section is intended to report one final result to be communicated in terms of a molecule that has been quantified. In many cases, this may be the molecule of biological interest, although in some cases, the final result could be a derivatized form as appropriate – although it is desirable for the database identifier(s) to reference to the biological (non-derivatized) form. In general, different adduct forms would generally be reported in the Small Molecule Feature section.
The order of columns MUST follow the order specified below.
All columns are MANDATORY except for “opt_” columns.
required:
- sml_id
properties:
prefix:
type: string
description: The small molecule table row prefix. SML MUST be used for rows of the small molecule table.
x-mztab-example: |
SML 1 …
enum:
- SML
default: SML
readOnly: true
header_prefix:
type: string
description: The small molecule table header prefix. SMH MUST be used for the small molecule table header line (the column labels).
x-mztab-example: |
SMH SML_ID …
enum:
- SMH
default: SMH
readOnly: true
sml_id:
type: integer
description: A within file unique identifier for the small molecule.
x-mztab-example: |
SMH SML_ID …
SML 1 …
SML 2 …
format: int32
smf_id_refs:
type: array
description: References to all the features on which quantitation has been based (SMF elements) via referencing SMF_ID values. Multiple values SHOULD be provided as a “|” separated list. This MAY be null only if this is a Summary file.
x-mztab-example: |
SMH SML_ID SMF_ID_REFS
SML 1 2|3|11…
default: []
items:
type: integer
format: int32
database_identifier:
type: array
description: |
A list of “|” separated possible identifiers for the small molecule; multiple values MUST only be provided to indicate ambiguity in the identification of the molecule and not to demonstrate different identifier types for the same molecule. Alternative identifiers for the same molecule MAY be provided as optional columns.
The database identifier must be preceded by the resource description (prefix) followed by a colon, as specified in the metadata section.
A null value MAY be provided if the identification is sufficiently ambiguous as to be meaningless for reporting or the small molecule has not been identified.
x-mztab-example: |
A list of “|” separated possible identifiers for the small molecule; multiple values MUST only be provided to indicate ambiguity in the identification of the molecule and not to demonstrate different identifier types for the same molecule. Alternative identifiers for the same molecule MAY be provided as optional columns.
The database identifier must be preceded by the resource description (prefix) followed by a colon, as specified in the metadata section.
A null value MAY be provided if the identification is sufficiently ambiguous as to be meaningless for reporting or the small molecule has not been identified.
default: []
items:
type: string
chemical_formula:
type: array
description: |
A list of “|” separated potential chemical formulae of the reported compound. The number of values provided MUST match the number of entities reported under “database_identifier”, even if this leads to redundant reporting of information (i.e. if ambiguity can be resolved in the chemical formula), and the validation software will throw an error if the number of “|” symbols does not match. “null” values between bars are allowed.
This should be specified in Hill notation (EA Hill 1900), i.e. elements in the order C, H and then alphabetically all other elements. Counts of one may be omitted. Elements should be capitalized properly to avoid confusion (e.g., “CO” vs. “Co”). The chemical formula reported should refer to the neutral form.
Example: N-acetylglucosamine would be encoded by the string “C8H15NO6”.
x-mztab-example: |
SMH SML_ID … chemical_formula …
SML 1 … C17H20N4O2 …
default: []
items:
type: string
smiles:
type: array
description: A list of “|” separated potential molecule structures in the simplified molecular-input line-entry system (SMILES) for the small molecule. The number of values provided MUST match the number of entities reported under “database_identifier”, and the validation software will throw an error if the number of “|” symbols does not match. “null” values between bars are allowed.
x-mztab-example: |
SMH SML_ID … chemical_formula smiles …
SML 1 … C17H20N4O2 C1=CC=C(C=C1)CCNC(=O)CCNNC(=O)C2=CC=NC=C2 …
default: []
items:
type: string
inchi:
type: array
description: |
A list of “|” separated potential standard IUPAC International Chemical Identifier (InChI) of the given substance.
The number of values provided MUST match the number of entities reported under “database_identifier”, even if this leads to redundant information being reported (i.e. if ambiguity can be resolved in the InChi), and the validation software will throw an error if the number of “|” symbols does not match. “null” values between bars are allowed.
x-mztab-example: |
SMH SML_ID … chemical_formula … inchi …
SML 1 … C17H20N4O2 … InChI=1S/C17H20N4O2/c22-16(19-12-6-14-4-2-1-3-5-14)9-13-20-21-17(23)15-7-10-18-11-8-15/h1-5,7-8,10-11,20H,6,9,12-13H2,(H,19,22)(H,21,23) …
default: []
items:
type: string
chemical_name:
type: array
description: |
A list of “|” separated possible chemical/common names for the small molecule, or general description if a chemical name is unavailable. Multiple names are only to demonstrate ambiguity in the identification. The number of values provided MUST match the number of entities reported under “database_identifier”, and the validation software will throw an error if the number of “|” symbols does not match. “null” values between bars are allowed.
x-mztab-example: |
SMH SML_ID … description …
SML 1 … N-(2-phenylethyl)-3-[2-(pyridine-4-carbonyl)hydrazinyl]propanamide …
default: []
items:
type: string
uri:
type: array
description: A URI pointing to the small molecule’s entry in a reference database (e.g., the small molecule’s HMDB or KEGG entry). The number of values provided MUST match the number of entities reported under “database_identifier”, and the validation software will throw an error if the number of “|” symbols does not match. “null” values between bars are allowed.
x-mztab-example: |
SMH SML_ID … uri …
SML 1 … http://www.genome.jp/dbget-bin/www_bget?cpd:C00031 …
SML 2 … http://www.hmdb.ca/metabolites/HMDB0001847 …
SML 3 … http://identifiers.org/hmdb/HMDB0001847 …
default: []
items:
type: string
format: uri
theoretical_neutral_mass:
type: array
description: |
The small molecule’s precursor’s theoretical neutral mass.
The number of values provided MUST match the number of entities reported under “database_identifier”, and the validation software will throw an error if the number of “|” symbols does not match. “null” values (in general and between bars) are allowed for molecules that have not been identified only, or for molecules where the neutral mass cannot be calculated. In these cases, the SML entry SHOULD reference features in which exp_mass_to_charge values are captured.
x-mztab-example: |
SMH SML_ID … theoretical_neutral_mass …
SML 1 … 1234.5 …
default: []
items:
type: number
format: double
adduct_ions:
type: array
description: |
A “|” separated list of detected adducts for this this molecule, following the general style in the 2013 IUPAC recommendations on terms relating to MS e.g. [M+H]1+, [M+Na]1+, [M+NH4]1+, [M-H]1-, [M+Cl]1-, [M+H]1+. If the adduct classification is ambiguous with regards to identification evidence it MAY be null.
x-mztab-example: |
SMH SML_ID … adduct_ions …
SML 1 … [M+H]1+ | [M+Na]1+ …
default: []
pattern: '^\[\d*M([+-][\w\d]+)*\]\d*[+-]$'
items:
type: string
reliability:
type: string
description: |
The reliability of the given small molecule identification. This must be supplied by the resource and MUST be reported as an integer between 1-4:
identified metabolite (1)
putatively annotated compound (2)
putatively characterized compound class (3)
unknown compound (4)
These MAY be replaced using a suitable CV term in the metadata section e.g. to use MSI recommendation levels (see Section 6.2.57 for details).
The following CV terms are already available within the PSI MS CV. Future schemes may be implemented by extending the PSI MS CV with new terms and associated levels.
The MSI has recently discussed an extension of the original four level scheme into a five level scheme MS:1002896 (compound identification confidence level) with levels
isolated, pure compound, full stereochemistry (0)
reference standard match or full 2D structure (1)
unambiguous diagnostic evidence (literature, database) (2)
most likely structure, including isomers, substance class or substructure match (3)
unknown compound (4)
For high-resolution MS, the following term and its levels may be used: MS:1002955 (hr-ms compound identification confidence level) with levels
confirmed structure (1)
probable structure (2)
unambiguous ms library match (2a)
diagnostic evidence (2b)
tentative candidates (3)
unequivocal molecular formula (4)
exact mass (5)
A String data type is set to allow for different systems to be specified in the metadata section.
x-mztab-example: |
SMH identifier … reliability …
SML 1 … 3 …
or
MTD small_molecule-identification_reliability [MS, MS:1002896, compound identification confidence level,]
…
SMH identifier … reliability …
SML 1 … 0 …
or
MTD small_molecule-identification_reliability [MS, MS:1002955, hr-ms compound identification confidence level,]
…
SMH identifier … reliability …
SML 1 … 2a …
best_id_confidence_measure:
$ref: '#/definitions/Parameter'
description: The approach or database search that identified this small molecule with highest confidence.
x-mztab-example: |
SMH SML_ID … best_id_confidence_measure …
SML 1 … [MS, MS:1001477, SpectraST,] …
best_id_confidence_value:
type: number
description: The best confidence measure in identification (for this type of score) for the given small molecule across all assays. The type of score MUST be defined in the metadata section. If the small molecule was not identified by the specified search engine, “null” MUST be reported. If the confidence measure does not report a numerical confidence value, “null” SHOULD be reported.
x-mztab-example: |
SMH SML_ID … best_id_confidence_value …
SML 1 … 0.7 …
format: double
abundance_assay:
type: array
description: The small molecule’s abundance in every assay described in the metadata section MUST be reported. Null or zero values may be reported as appropriate. "null" SHOULD be used to report missing quantities, while zero SHOULD be used to indicate a present but not reliably quantifiable value (e.g. below a minimum noise threshold).
x-mztab-example: |
SMH SML_ID … abundance_assay[1] …
SML 1 … 0.3 …
default: []
items:
type: number
format: double
abundance_study_variable:
type: array
description: The small molecule’s abundance in all the study variables described in the metadata section (study_variable[1-n]_average_function), calculated using the method as described in the Metadata section (default = arithmetic mean across assays). Null or zero values may be reported as appropriate. "null" SHOULD be used to report missing quantities, while zero SHOULD be used to indicate a present but not reliably quantifiable value (e.g. below a minimum noise threshold).
x-mztab-example: |
SMH SML_ID … abundance_study_variable[1] …
SML 1 … 0.3 …
default: []
items:
type: number
format: double
abundance_variation_study_variable:
type: array
description: A measure of the variability of the study variable abundance measurement, calculated using the method as described in the metadata section (study_variable[1-n]_average_function), with a default = arithmethic co-efficient of variation of the small molecule’s abundance in the given study variable.
x-mztab-example: |
SMH SML_ID … abundance_study_variable[1] abundance_variation_study_variable[1] …
SML 1 … 0.3 0.04 …
default: []
items:
type: number
format: double
opt:
type: array
description: |
Additional columns can be added to the end of the small molecule table. These column headers MUST start with the prefix “opt_” followed by the {identifier} of the object they reference: assay, study variable, MS run or “global” (if the value relates to all replicates). Column names MUST only contain the following characters: ‘A’-‘Z’, ‘a’-‘z’, ‘0’-‘9’, ‘’, ‘-’, ‘[’, ‘]’, and ‘:’. CV parameter accessions MAY be used for optional columns following the format: opt{identifier}_cv_{accession}_\{parameter name}. Spaces within the parameter’s name MUST be replaced by ‘_’.
x-mztab-example: |
SMH SML_ID … opt_assay[1]_my_value … opt_global_another_value
SML 1 … My value … some other value
default: []
items:
$ref: '#/definitions/OptColumnMapping'
comment:
type: array
default: []
items:
$ref: '#/definitions/Comment'
SmallMoleculeFeature:
type: object
description: |
The small molecule feature section is table-based, representing individual MS regions (generally considered to be the elution profile for all isotopomers formed from a single charge state of a molecule), that have been measured/quantified. However, for approaches that quantify individual isotopomers e.g. stable isotope labelling/flux studies, then each SMF row SHOULD represent a single isotopomer.
Different adducts or derivatives and different charge states of individual molecules should be reported as separate SMF rows.
The small molecule feature section MUST always come after the Small Molecule Table. All table columns MUST be Tab separated. There MUST NOT be any empty cells. Missing values MUST be reported using “null”.
The order of columns MUST follow the order specified below.
All columns are MANDATORY except for “opt_” columns.
required:
- smf_id
- exp_mass_to_charge
- charge
properties:
prefix:
type: string
description: The small molecule feature table row prefix. SMF MUST be used for rows of the small molecule feature table.
x-mztab-example: |
SMF 1 …
enum:
- SMF
default: SMF
readOnly: true
header_prefix:
type: string
description: The small molecule feature table header prefix. SFH MUST be used for the small molecule feature table header line (the column labels).
x-mztab-example: |
SFH SMF_ID …
enum:
- SFH
default: SFH
readOnly: true
smf_id:
type: integer
description: A within file unique identifier for the small molecule feature.
x-mztab-example: |
SFH SMF_ID …
SMF 1 …
SMF 2 …
format: int32