REST APIs

These REST APIs provide programmatic access to read and write data to GEO2Enrichr. You may analyze a GEO or custom SOFT file or fetch results from a previous analysis. Requests are made to the base URL:

https://amp.pharm.mssm.edu/g2e/api

Responses are in JSON.

GET /g2e/api/extract/:id

Returns a JSON blob of data associated with a single user extraction, based on the id parameter. The returned data has stable links to the SOFT file; up, down, and combined gene lists; and metadata from both the experiment and analysis.

Resource URL

https://amp.pharm.mssm.edu/g2e/api/extract

Parameters

id The ID of the extraction for which to return results.

Example request

https://amp.pharm.mssm.edu/g2e/api/extract/e29766a757

Example JSON response

{
  "extraction_id": "e29766a757",
  "gene_lists": [
    {
      "direction": 0,
      "target_apps": {
        "enrichr": "https://amp.pharm.mssm.edu/Enrichr/enrich?dataset=a61"
      },
      "ranked_genes": [
        [
          "TOMM70A",
          0.499472
        ],
        [
          "SUN1",
          0.00838146
        ],
        [
          "DPP10",
          0.0105129
        ],
        ...
      ]
    },
    ...
  ],
  "required_metadata": {
    "cutoff": 500,
    "method": "chdir",
    "threshold": null,
    "ttest_correction_method": null
  },
  "optional_metadata": {
    "cell": null,
    "disease": null,
    "gene": null,
    "perturbation": null
  },
  "soft_file": {
    "is_geo": true,
    "accession": "GDS5077",
    "normalize": true,
    "platform": "GPL10558",
    "text_file": "static/softfile/clean/GDS5077.txt"
  }
}

POST /g2e/api/extract/geo

Performs differential expression analysis on a GEO SOFT file based on the GEO accession number, platform, and selected samples.

Resource URL

https://amp.pharm.mssm.edu/g2e/api/extract/geo

Parameters

dataset A valid GEO accession number identifying the dataset.
platform The GPL number (platform) associated with the GEO accession number.
A_cols An array of GSM numbers to be used as in the control group.
B_cols An array of GSM numbers to be used as in the treatment or condition group.

Example request using cURL

curl -v https://amp.pharm.mssm.edu/g2e/api/extract/geo --data \
  'dataset=GDS5077&\
  platform=GPL10558&\
  A_cols[]=GSM1071454&A_cols[]=GSM1071455&\
  B_cols[]=GSM1071457&B_cols[]=GSM1071455'

< POST /g2e/api/extract/geo HTTP/1.1
< User-Agent: curl/7.37.1
< Host: https://amp.pharm.mssm.edu/
< Accept: */*
< Content-Length: 91
< Content-Type: application/x-www-form-urlencoded

Example response

< HTTP/1.0 200 OK
{
  'extraction_id': 38
}

POST /g2e/api/extract/upload_soft_list

Performs differential expression analysis on an uploaded SOFT file. The SOFT file can eithe

Parameters

file The file to be processed.
name A description of your data.

Example request using cURL

$ curl -v https://amp.pharm.mssm.edu/g2e/api/extract/upload_soft_file \
--form 'file=@input.txt' name=SyntheticData

> POST /g2e/api/extract/upload_soft_file HTTP/1.1
> User-Agent: curl/7.37.1
> Host: https://amp.pharm.mssm.edu/
> Accept: */*
> Content-Length: 187810
> Expect: 100-continue
> Content-Type: multipart/form-data; boundary=------------------------1dcefa53b8e0b8ed

Example response

< HTTP/1.0 200 OK
{
  'extraction_id': 38
}

POST /g2e/api/extract/upload_gene_list

Uploads complete gene signature to GEO2Enrichr's database. Does not perform any cleanup or analysis.

Parameters

ranked_genes A list of ranked genes represented as an array of arrays. For each inner array, the first element is the gene symbol and the second element is gene's weight or value.
diffexp_method Differential expression method. Default is chdir. Alternative value is ttest
cutoff Optional parameter indicating the maximum number of genes in the resultant gene list. Defaults to 500.
correction_method Only applicable if diffexp_method is ttest. Defaults to BH for Benjamini Hochberg.
threshold Only applicable if diffexp_method is ttest. Defaults to 0.01.
Gene Optional. Name or symbol for relevant gene.
Cell Optional. Name of relevant cell type or tissue.
Perturbation Optional. Name of relevant perturbation.
Disease Optional. Name of relevant disease.

Example request using requests

import json
import requests

payload = {
    'ranked_genes': [
        [
            'CPSF3',
            0.000631847
        ],
        [
            'CLEC18B',
            0.00876892
        ],
        [
            'RTDR1',
            0.0000692485
        ],
        [
            'MYLPF',
            0.00218427
        ],
        [
            'KIF2B',
            0.0000457653
        ],
        [
            'SMPDL3A',
            0.00876879
        ],
        [
            'FAM171A2',
            0.00442025
        ],
        [
            'RASGRF2',
            0.0145588
        ],
        [
            'ROCK2',
            0.00218436
        ]
    ],
    'diffexp_method': 'chdir',
    'tags': ['test_tag'],
    'gene': 'STAT3',
    'cell': None,
    'perturbation': None,
    'disease': None

    # Only if diffexp_method := "chdir", which is the default.
    # 'cutoff': 500,

    # Only if diffexp_method := "ttest"
    # 'correction_method': 'BH',
    # 'threshold': 0.05
}
resp = requests.post('https://amp.pharm.mssm.edu/g2e/api/extract/upload_gene_list',
                     data=json.dumps(payload))

Example JSON response

{
  "extraction_id": "8ebf6a9688",
  "link": "https://amp.pharm.mssm.edu/g2e/results/8ebf6a9688"
}