IPSS-M API and CLI

[!important] You may use IPSS-M API, the underlying content, and any output therefrom for personal for academic and research and noncommercial purposes only. See LICENSE for more details.

API and CLI of the Molecular International Prognostic Scoring System (IPSS-M) for Myelodysplastic Syndromes.

⚡️ API Reference Available at: https://api.mds-risk-model.com

• For the R package, see https://github.com/papaemmelab/ipssm.
• For the Online Web Calculator, visit https://mds-risk-model.com.

Table of contents

• 📖 IPSS-M Publication
• 🗒️ Input Variables Definition
• 🚀 API Usage
  • 🧬 IPSS-M API Endpoint
  • 🆎 IPSS-R API Endpoint
• 🤖 CLI Usage
  • 🔥 Using it as a node/javascript package
  • 💥 IPSS-M
  • ⚡️ IPSS-R and IPSS-R (Age adjusted)
  • 🎯 Annotating batch from CSV/Excel file
• 👨🏻‍💻 Development
• ❓ Question

:page_with_curl: IPSS-M Publication

Bernard E, Tuechler H, Greenberg PL, Hasserjian RP, Arango Ossa JE et al. Molecular International Prognostic Scoring System for Myelodysplastic Syndromes, NEJM Evidence 2022.

https://evidence.nejm.org/doi/full/10.1056/EVIDoa2200008

:spiral_notepad: Input Variables Definition

Note: Values for mutations:

• 0 means wild-type (non-mutated)
• 1 means mutated, and
• NA means 'Not Asssesed'.

:rocket: API Usage

The API is available at: https://api.mds-risk-model.com

:dna: IPSS-M API Endpoint

Endpoint: POST /ipssm

curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"HB": 10, "PLT":150, "BM_BLAST":2, "CYTO_IPSSR": "Poor"}' \
    https://api.mds-risk-model.com/ipssm

# example response
{
  "patient": {
    "HB": 10,
    "PLT": 150,
    "BM_BLAST": 2,
    "CYTO_IPSSR": "Poor",
    "del5q": 0,
    "del7_7q": 0,
    "del17_17p": 0,
    "complex": 0,
    "TP53mut": "0",
    "TP53maxvaf": 0,
    "TP53loh": 0,
    "MLL_PTD": 0,
    "FLT3": 0,
    "ASXL1": 0,
    "CBL": 0,
    "DNMT3A": 0,
    "ETV6": 0,
    "EZH2": 0,
    "IDH2": 0,
    "KRAS": 0,
    "NPM1": 0,
    "NRAS": 0,
    "RUNX1": 0,
    "SF3B1": 0,
    "SRSF2": 0,
    "U2AF1": 0,
    "BCOR": 0,
    "BCORL1": 0,
    "CEBPA": 0,
    "ETNK1": 0,
    "GATA2": 0,
    "GNB1": 0,
    "IDH1": 0,
    "NF1": 0,
    "PHF6": 0,
    "PPM1D": 0,
    "PRPF8": 0,
    "PTPN11": 0,
    "SETBP1": 0,
    "STAG2": 0,
    "WT1": 0
  },
  "ipssm": {
    "means": {
      "riskScore": -0.35,
      "riskCat": "Moderate Low"
    },
    "worst": {
      "riskScore": -0.35,
      "riskCat": "Moderate Low"
    },
    "best": {
      "riskScore": -0.35,
      "riskCat": "Moderate Low"
    }
 }

:ab: IPSS-R API Endpoint

Endpoint: POST /ipssr

$ curl \
    -X POST \
    -H "Content-Type: application/json" \
    -d '{"HB": 10, "ANC": 1.8, "PLT": 150, "BM_BLAST": 2, "CYTO_IPSSR": "Poor", "AGE": 28}' \
    https://api.mds-risk-model.com/ipssr

# example response
{
  "patient": {
    "HB": 10,
    "ANC": 1.8,
    "PLT": 150,
    "BM_BLAST": 2,
    "CYTO_IPSSR": "Poor",
    "AGE": 28
  },
  "ipssr": {
    "IPSSR_SCORE": 3,
    "IPSSR_CAT": "Low",
    "IPSSRA_SCORE": 1.53,
    "IPSSRA_CAT": "Low"
  }
}

:robot: CLI Usage

You can use the command line interface to annotate a file with patients, where each row is a patient and each column is a variable.

# Without installing it using npx
npx ipssm --help

# With local installation using npm
npm install ipssm
ipssm --help

$  ipssm --help

Annotate a file of patients with IPSS-M and IPSS-R risk scores and categories.
It supports .csv, .tsv, .xlsx files.

Usage: ipssm <inputFile> <outputFile>

Positionals:
  inputFile   File to be annotated (rows: patients, columns: variables).[string]
  outputFile  Path for the annotated output file.                       [string]

Options:
      --version  Show version number                                   [boolean]
  -h, --help     Show help                                             [boolean]

:fire: Using it as a node/javascript package

:boom: IPSS-M

Having a patient's data in a dictionary, you can compute the IPSS-M.

const { ipssm } from 'ipssm'

// Add patient data to an object with the following fields
const patientFields = {
  // Clinical Data
  BM_BLAST: 0,
  HB: 8.2,
  PLT: 239,
  // Optional IPSS-R fields
  ANC: 0.72,
  AGE: 63.5,
  // Cytogenetic Data 
  del5q: 0,
  del7_7q: 0,
  del17_17p: 0,
  complex: 0, 
  CYTO_IPSSR: 'Good',
  // Molecular Data
  TP53mut: 0,
  TP53maxvaf: 0,
  TP53loh: 0,
  MLL_PTD: 0,
  FLT3: 0,
  ASXL1: 1,
  CBL: 0,
  DNMT3A: 0,
  ETV6: 0,
  EZH2: 1,
  IDH2: 0,
  KRAS: 0,
  NPM1: 0,
  NRAS: 0,
  RUNX1: 1,
  SF3B1: 0,
  SRSF2: 0,
  U2AF1: 0,
  BCOR: 0,
  BCORL1: 0,
  CEBPA: 0,
  ETNK1: 0,
  GATA2: 0,
  GNB1: 0,
  IDH1: 0,
  NF1: 0,
  PHF6: 0,
  PPM1D: 0,
  PRPF8: 0,
  PTPN11: 0,
  SETBP1: 0,
  STAG2: 0,
  WT1: 0,
}

const ipssmResult = ipssm(patientFields)
console.log(ipssmResult)

// Result
{
  means: {
    riskScore: 0.09,
    riskCat: 'Moderate High',
    contributions: {...}
  },
  best: {
    riskScore: 0.09,
    riskCat: 'Moderate High',
    contributions: {...}
  },
  worst: {
    riskScore: 0.09,
    riskCat: 'Moderate High',
    contributions: {...}
  },
}

:zap: IPSS-R and IPSS-R (Age adjusted)

Additionally, you may find an implementation to compute the IPPS-R and IPSS-R (Age adjusted) in this module:

import { ipssr } from 'ipssm'

// using the same patient data
patientFields = {
  HB: 8.2,
  ANC: 0.72,
  PLT: 239,
  BM_BLAST: 0,
  CYTOVEC: 1,
  AGE: 63.5,
  ...
}

const ipssrResult = ipssr({
  hb: patientFields.HB,
  anc: patientFields.ANC,
  plt: patientFields.PLT,
  bmblast: patientFields.BM_BLAST,
  cytovec: patientFields.CYTOVEC,
  age: patientFields.AGE,
})

console.log(ipssrResult)

Which outputs a risk score (means), with a best and worst scenario risk score to account for missing genetic data.

// Result
{
    IPSSR_SCORE: 2.5,
    IPSSR: 'Low',
    IPSSRA_SCORE: 2.2563,
    IPSSRA: 'Low',
}

:dart: Annotating batch from CSV/Excel file

The following code will annotate a CSV file with the IPSS-M and IPSS-M Risks.

import { annotateFile } from 'ipssm'

const inputFile = './test/data/IPSSMexample.csv'
const outputFile = 'IPSSMexample.annotated.csv'

await annotateFile(inputFile, outputFile)

or with an excel file:

import { annotateFile } from 'ipssm'

const inputFile = './test/data/IPSSMexample.xlsx'
const outputFile = 'IPSSMexample.annotated.xlsx'

await annotateFile(inputFile, outputFile)

:question: Question

Any questions feel free to add an issue to this repo or to contact ElsaB.

👨🏻‍💻 Development

# Install dependencies
npm install

# Run the development server
npm run serve

# Run tests
npm test