Jsms

JSMS (the JSON MS file format) is a proposed JSON Lines format alternative to the commonly used MGF file format to exchange MS/MS information in proteomics. JSMS uses the widely supported Java Script Object Notation to simplify parsing of the MS/MS information. It also provides for straightforward extensions of the file format without requiring changes in parsers that are only interested in the data.

Contents 1 Introduction 2 Purpose 3 Design 3.1 1. "format" object 3.2 2. "lv" object 3.3 3. "validation" object 4 Demonstration code 5 Participation and contact information

Introduction

The MGF file format (Mascot Generic Format) was introduced by Matrix Science Inc. in the 1990's are an alternative to the then widely-used DTA format. DTA files each contain data from a single LC-MS/MS scan, so an MS/MS run would result in many DTA files. MGF allowed for the inclusion of any number of scans into a single file, making it a simpler alternative for sending all of the data from an LC-MS/MS run across a network for analysis. Both DTA and MGF file formats resulted in simple, structured text ASCII files that could be easily read using a text editor.

An example of a simple MGF file for a single MS/MS spectrum is shown here:

BEGIN IONS
PEPMASS=413.2661
CHARGE=1+
TITLE=MS/MS scan
189.48956 1.9
283.62076 3.4
301.22977 66.3
311.08008 1.3
399.99106 2.3
END IONS

The simplicity of this format has led to its widespread use in proteomics informatics projects.

Purpose

The purpose of JSMS is to modernize this format and introduce the benefits of using JSON for simplified parser and generator development. Extending the language is a simple matter of either adding application-specific objects or additional keys to the three types of JSMS-specific objects, taking care not to redefine or reuse the language's reserved key names.

JSMS is:

1. UTF-8 compatible, by definition. There are no problems associated with using non-ASCII characters, which can be useful when recording scientific symbols or non-English information.
2. Easily extensible. Additional lines of JSON objects can be used to record application-specific information and additional keys can be added to each spectrum object, i.e., spectrum-specific data handling directives.
3. Easy to validate on-the-fly. JSMS files are required to contain a hash value that can be used to determine if the file has been correctly transmitted across a network, prior to use.
4. Easy to parse. Most programming languages provide simple mechanisms to unpack the data in a JSON object: no file-specific code is required.

JSMS is NOT:

1. A replacement for existing XML file formats. mzXML and mzML are both commonly used to archive the MS/MS information from vendor-specific raw data files. Files in these formats serve as a source of information for the creation of a JSMS file.
2. An archival file format. JSMS is for rapid, simple-to-do data exchange between software APIs.

Design

A JSMS example that records the information present in the MGF presented above is shown below. It contains the three types of objects defined in JSMS:

1. object containing the key "format" (one per file);
2. object containing the key "lv" (spectrum information, any number allowed);
3. object containing the key "validation" (file validation information, one per file).

{"format": "jsms 1.0", "source": "test.mgf", "created": "2019-02-24 13:16:33.306856"}
{"lv": 2, "pm": 413.2661, "pz": 1, "ti": "MS/MS scan", "sc": 1, "np": 5, "ms": [189.48956, 283.62076, 301.22977, 311.08008, 399.99106], "is": [1.9, 3.4, 66.3, 1.3, 2.3]}
{"validation": "sha256", "value": "42c2b93928c7d4306aa2f4fc6c817efcdb3cbdc4b308b73985bbf28a9cf7604f"}

Each line is a separate JSON object, which can be parsed without reference to the other lines. This feature of JSON Lines is important practically, because MS/MS data can be composed of millions of individual spectra. Such large objects can cause problems with some JSON parsers and the resulting data objects can be cumbersome.

The order of objects/lines in a file has no meaning. Any ordering information must be contained within the objects.

1. "format" object

The following single key /value pair is required for this type of object. Only one "format" object can be present in a file. In the following tables, a key can either be required (R) or optional (O). Both types of keys are reserved for use by JSMS only: extensions to the language may not use those keys for any purpose.

key name	type	R/O	value	description
"format"	string	R	"jsms v 1.0"	identifies the version of JSMS used for the file

2. "lv" object

This type of object contains the MS/MS data equivalent to an MGF file. Any number of these objects may be present in a valid JSMS file.

key name	type	R/O	value	description
"lv"	float	R	MS/MS level	MS/MS data = 2, MS/MS/MS = 3, MS/MS/MS/MS = 4, etc.
"pm"	float	R	PEPMASS	parent ion m/z
"pz"	float	R	CHARGE	parent ion z
"ti"	string	O	TITLE	description of spectrum
"sc"	float	O	scan number	the instrument's scan number for the spectrum
"np"	float	R	array dimension	the length of the "ms", "is" and "zs" arrays
"ms"	floats	R	m/z	array of measured fragment ion m/z values
"is"	floats	R	intensity	array of measured fragment ion intensity
"zs"	floats	O	charge	array of measured fragment ion charges

3. "validation" object

This type of object contains overall file validation information. Only one of these objects may be present in a valid JSMS file.

key name	type	R/O	value	description
"validation"	string	R	hash type	currently only SHA-256
"value"	string	R	hash	hexadecimal representation of the file's hash

The hash value for a file is calculated as follows:

1. the object containing the "validation" key is removed;
2. all whitespace between objects is removed; and
3. the SHA-256 hash value is calculated for the remaining object string.

Demonstration code

An FTP site containing Python 3 scripts that demonstrate how to create and validate JSMS files along with some demonstration files is located at ftp://ftp.thegpm.org/projects/jsms.

Participation and contact information

If you are interested in helping with the development and use of JSMS, please contact the project coordinator Ron Beavis.