sms-api: Simulating Microbial Systems

• Github repository: https://github.com/vivarium-collective/sms-api/
• Documentation https://sms-api.readthedocs.io/en/latest/
• REST API Documentation: View Docs

SMS API (otherwise known as Atlantis API):

Design, run, and analyze reproducible simulations of dynamic cellular processes in Escherichia coli. SMS API uses the vEcoli model. Please refer to the vEcoli documentation for more details.

Getting Started

The SMS API uniquely acts as both a server and client:

This project uses FastAPI, Uvicorn, and Marimo to serve a REST API as well as host Marimo user interfaces. For more information on Marimo, please refer to their documentation.

Server:

A kubernetes cluster containing an ASGI application (FastAPI) is hosted and available at https://sms.cam.uchc.edu/ An API router of endpoints is assigned for each API in this project's scope and available by name in the request url. For example the primary single-cell API ("core") endpoints are hosted at https://sms.cam.uchc.edu/core. Other APIs include the Antibiotic and Biomanufacturing.

Client:

This project uses the Marimo web app functionality to act as a client to the aforementioned server. There is a client for each API router (or simply, API). This ui is accessible by navigating to https://sms.cam.uchc.edu/. Please contact our organization for authentication, if needed.

REST API Overview (Analyses):

Running a new Analysis:

Analyses can be run using <POST> https://sms.cam.uchc.edu/v1/ecoli/analyses A request to this url for an analysis run focused exclusively on the tsv outputs generated by multigen/multiseed analysis modules might look like:

{
  "experiment_id": "sms_multigeneration",
  "analysis_name": "ptools_analysis_multigeneration",
  "single": {},
  "multidaughter": {},
  "multigeneration": {
    "ptools_rxns": {
      "n_tp": 8
    },
    "ptools_rna": {
      "n_tp": 8
    },
    "ptools_proteins": {
      "n_tp": 8
    }
  },
  "multiseed": {
    "ptools_rxns": {
      "n_tp": 8
    },
    "ptools_rna": {
      "n_tp": 8
    },
    "ptools_proteins": {
      "n_tp": 8
    }
  },
  "multivariant": {},
  "multiexperiment": {}
}

You will notice from the documentation that there are several other possible analyses that can be run, so merging the aforementioned JSON with the documentation example will give you the full set of available analyses. NOTE: The field "analysis_name" is the name you wish to assign the analysis run. The corresponding response will be a JSON object.

Getting the status of an analysis run:

<GET> https://sms.cam.uchc.edu/v1/ecoli/analyses/{id}/status where {id} is retrieved from the object generated by the aforemented POST request's database_id attribute.

Getting the tsv file outputs:

In the interest of providing flexible data ingestion options, there are several endpoints each of which allow you to take in the data in your preferred way. As in the aforementioned status information, you will use the generated analysis DTO's database_id to parameterize this request. Each of the following endpoints will give you the full set of tsv outputs, labeled by filename:

• <GET> https://sms.cam.uchc.edu/v1/ecoli/analyses/{id}/ptools : Get an array of objects which have the schema {"name": , "content": }, where "content" is the actual tsv text. The client must reconstruct the new line breaks of the tsv if needed.

• <GET> https://sms.cam.uchc.edu/v1/ecoli/analyses/{id}/ptools/formatted : Get tsv file contents as in the aforementioned endpoint, but new-line-formatted and ingested as a StreamingResponse. The client can use this text in memory or manually write it to disk.

• <GET> https://sms.cam.uchc.edu/v1/ecoli/analyses/{id}/ptools/download: Get the same output tsv files from the previous two endpoints, but as actual text files in a .zip archive. This requires the client to download and unzip/ingest the actual zip blob, but may be preferable as new lines are already parsed and written to disk.

Recap:

So to recap, a useful "roundtrip" analysis workflow typescript pseudo-code might look like:

const analysisDTO = <POST>https://sms.cam.uchc.edu/v1/ecoli/analyses
const analysisStatus = <GET>https://sms.cam.uchc.edu/v1/ecoli/analyses/{analysisDTO.database_id}/status
if (analysisStatus.status == "completed") {
   tsvOutputs: Record<str, str>[] = <GET>https://sms.cam.uchc.edu/v1/ecoli/analyses/{analysisDTO.database_id}/ptools

   // OR

   // download zip archive of the same tsv files:
   <GET>https://sms.cam.uchc.edu/v1/ecoli/analyses/{analysisDTO.database_id}/ptools/download

}