JSON Format Conversion

json-format-conversion

Summary

Convert R list objects extracted from Thermo Fisher Scientific binary raw files into JSON format for serialization and storage. This skill enables portable exchange and downstream parsing of structured proteomics metadata and spectral summaries.

When to use

When you have extracted file metadata or scan summaries as R list objects from .raw files using readFileHeader(), readIndex(), or readSpectrum(), and need to persist them to disk, share them across systems, or feed them into downstream tools that consume JSON (e.g., JSON-schema validators, web services, or non-R analysis pipelines).

When NOT to use

• Input is already in JSON format or another exchange format (mzML, mzXML) — deserialize and parse directly instead.
• Raw spectral m/z and intensity arrays are very large (>10⁶ data points per scan) — JSON text serialization may be inefficient; consider binary formats (HDF5, Parquet, msgpack) or streaming protocols instead.
• Downstream tool expects a specific schema or dialect of JSON not guaranteed by rjson::toJSON() — validate or post-process JSON output against schema.

Inputs

• R list object returned by rawrr reader functions (readFileHeader, readSpectrum, readIndex, readChromatogram, etc.)
• File path for output (character string with .json extension)

Outputs

• .json file on disk containing serialized R list as JSON
• JSON text string (if writing to string rather than file)

How to apply

After calling readFileHeader() or similar rawrr reader functions to produce an R list object containing instrument metadata, chromatogram data, or scan indices, pass the R list to rjson::toJSON() to serialize it to JSON text. Write the JSON string to a file with .json extension using base R file I/O (e.g., writeLines() or write()). Verify the output file exists and contains valid JSON structure by parsing it back (e.g., rjson::fromJSON()) to confirm round-trip fidelity. The JSON representation will dynamically include all data items returned by the reader function, which vary by instrument model and control software version.

Related tools

• rjson (R package that serializes R list objects to JSON text using toJSON() function) — https://cran.r-project.org/package=rjson
• rawrr (R package providing reader functions (readFileHeader, readSpectrum, etc.) that produce list objects suitable for JSON conversion) — https://github.com/fgcz/rawrr
• RawFileReader (.NET assembly wrapped by rawrr; provides underlying C# API for accessing binary raw file data) — https://github.com/thermofisherlsms/RawFileReader

Examples

H <- readFileHeader(rawfile); json_str <- toJSON(H); writeLines(json_str, 'metadata.json')

Evaluation signals

• Output .json file exists on disk at specified path and is readable by the file system.
• Round-trip parsing succeeds: rjson::fromJSON(readLines(output_file)) returns an R list with identical structure and values as the input list (exact equality or checksums match).
• JSON structure is valid: json linting tools (e.g., Python json.tool, online validators) accept the file without syntax errors.
• All metadata fields from the original R list are preserved in the JSON output (no missing keys or truncated values).
• Field names and data types in JSON match the instrument model and software version (e.g., 'Time range', 'Number of scans', 'Instrument model' are present for a given instrument).

Limitations

• rjson::toJSON() may not handle all R object types equally (e.g., factors, S3/S4 classes); convert complex objects to vectors/lists before serialization.
• JSON text is larger than binary formats; for high-volume spectral data, consider compression (.json.gz) or binary alternatives (HDF5, msgpack).
• No built-in schema validation: JSON output conforms to rjson's serialization rules but may not match a specific downstream tool's JSON schema; post-validate against schema if required.
• Floating-point precision loss possible during serialization/deserialization; round-trip values may differ at machine epsilon scale.
• Large spectral data (millions of scans, high m/z resolution) can produce JSON files too large for in-memory parsing in some environments.

Evidence

• [other] readFileHeader() retrieves metadata from binary raw files including instrument model, file name, time range of data acquisition, and number of scans, returning these items as a list object containing dynamically-generated data items that vary by instrument model and control software version.: "readFileHeader() retrieves metadata from binary raw files including instrument model, file name, time range of data acquisition, and number of scans, returning these items as a list object containing"
• [other] Call readFileHeader() to extract the file header as an R list object. 3. Serialize the list to JSON format using rjson::toJSON. 4. Write the serialized JSON to an output file with .json extension. 5. Verify that the JSON file exists and contains valid JSON structure.: "Serialize the list to JSON format using rjson::toJSON. 4. Write the serialized JSON to an output file with .json extension. 5. Verify that the JSON file exists and contains valid JSON structure"
• [readme] rawrr wraps the functionality of the RawFileReader .NET assembly: "rawrr wraps the functionality of the RawFileReader .NET assembly"
• [methods] R functions requesting access to data stored in binary raw files (reader family functions listed in Table 1) invoke compiled C# wrapper methods using a system call. In order to return extracted data back to the R layer we use file I/O. More specifically, the extracted information is written to a temporary location on the harddrive, read back into memory and: "R functions requesting access to data stored in binary raw files invoke compiled C# wrapper methods using a system call. extracted information is written to a temporary location on the harddrive,"