sssom-js

Simple Standard for Sharing Ontology Mappings (SSOM) JavaScript library

This Node package provides methods and a command line client to process mappings in SSSOM format.

It implements parsing SSSOM (TSV and JSON) with validation and transformation to other SSSOM serializations and to JSKOS format.

Propagation of mapping set slots is not supported yet.

Table of Contents

• Install
• Usage
  • Command line
  • API
• Maintainers
• Contribute
• License

Install

npm install sssom-js

Requires Node.js >= 20.19.

Usage

Command line

The package includes the command line client sssom:

Usage: sssom [options] [<mappings-file> [<metadata-file>]] 

Parse and convert SSSOM

Options:
  -f, --from FORMAT    input format (tsv, json)
  -t, --to FORMAT      output format (json, ndjson, jskos, ndjskos)
  -p, --prefixes FILE  additional CURIE prefixes (JSON file)
  -v, --verbose        verbose error messages
  -h, --help           output usage information
  -V, --version        output the version number

The following formats are supported:

format	description	support
tsv	SSSOM/TSV	from
json	SSSOM/JSON	from & to
ndjson	metadata and mappings on individual lines (SSSOM/JSON)	to
jskos	JSKOS	to
ndjskos	metadata and mappings on individual lines (JSKOS)	to

If not specified, formats are guessed from file name with fallback to tsv (from) and ndjson (to).

Formats json and jskos require to fully load the input into memory for processing, the other formats support streaming processing.

If you want to allow all CURIE prefixes from Bioregistry without explicitly defining them in curie_map you can download and convert the current list for instance with command line tools curl and jq this way (requires local copy of file bioregistry.jq) and then reference result file bioregistry.json with option --prefixes:

curl -sL https://w3id.org/biopragmatics/bioregistry.epm.json | \
jq -Sf bioregistry.jq > bioregistry.json

API

import { parseSSSOM, TSVReader, toJskosRegistry, toJskosMapping } from "sssom-js"

parseSSSOM (input, options)

This asynchronous function parses SSSOM in format options.from (json, or tsv as default) from a stream or file and returns a mapping set on success. The result should directly be serializable as SSSOM/JSON.

Note that SSSOM/JSON has not been specified officially yet, so details may change!

import { parseSSSOM } from "sssom-js"
const { mappings, ...metadata } = await parseSSSOM(process.stdin)

Option prefixes can be used to extend curie_map with additional prefixes.

To parse from a string use Readable.from:

import { Readable } from "stream"
const input = Readable.from("# mapping_set_id: ...")
const { mappings, ...metadata } = await parseSSSOM(input)

TSVReader

This event emitter parses SSSOM/TSV from a stream and emits metadata and mapping events:

import fs from "fs"
import { TSVReader } from "sssom-js"

const input = fs.createReadStream("test/valid/minimal.sssom.tsv")
new TSVReader(input)
  .on("metadata", console.log)
  .on("mapping", console.log)
  .on("error", console.error)
  .on("end", console.log)

toJskosRegistry

Convert a parsed MappingSet to a JSKOS Registry object.

toJskosMapping

Convert a parsed Mapping to a JSKOS Concept Mapping object.

Maintainers

• @nichtich (Jakob Voß)

Contribute

Contributions are welcome! Best use the issue tracker for questions, bug reports, and/or feature requests!

License

MIT license