Medical-research-skills singlecell-portal

Source: https://github.com/aipoch/medical-research-skills

When to Use

• You need to discover relevant public single-cell studies by filtering on organism (e.g., human/mouse) and tissue (e.g., lung/brain).
• You want to quickly retrieve study-level metadata (e.g., study name, accession, cell counts) for downstream curation or reporting.
• You are building a script or tool that needs no authentication and should work reliably on Windows with minimal setup.
• You want to inspect available filter facets (what tissues/diseases/cell types exist in the index) before constructing queries.
• You need a lightweight way to validate that a study exists and fetch its details by accession.

Key Features

• Direct REST access to the official Single Cell Portal API (

  /single_cell/api/v1/*

  )
• No API key required (public endpoints)
• Faceted search for studies (organism, tissue, disease, cell type, etc.)
• Retrieve facet dictionaries to build valid filters
• Retrieve study details by accession
• Minimal dependency footprint (only

  requests

  )
• Windows-friendly behavior (optional SSL verification disablement for certificate issues)

Dependencies

• requests==2.31.0

Example Usage

import requests

BASE_URL = "https://singlecell.broadinstitute.org/single_cell/api/v1"

def scp_get(path: str, params=None, verify_ssl: bool = True, timeout: int = 30):
    """
    Minimal helper for Single Cell Portal API calls.

    Security note:
    - Only call official endpoints under:
      https://singlecell.broadinstitute.org/single_cell/api/v1/*
    - If you encounter Windows certificate issues, set verify_ssl=False.
    """
    url = f"{BASE_URL}{path}"
    resp = requests.get(url, params=params or {}, timeout=timeout, verify=verify_ssl)
    resp.raise_for_status()
    return resp.json()

def search_studies(facets: str, size: int = 5):
    return scp_get("/search", params={"facets": facets, "size": size})

def get_facets():
    return scp_get("/search/facets")

def get_study(accession: str):
    return scp_get(f"/studies/{accession}")

if __name__ == "__main__":
    # 1) Search: human lung studies
    results = search_studies("organism:human,tissue:lung", size=5)
    studies = results.get("studies", [])
    print("Top matches:")
    for s in studies:
        print(f"- {s.get('name')} | accession={s.get('accession')} | cells={s.get('cell_count')}")

    # 2) Inspect available facet values (useful to build valid filters)
    facet_info = get_facets()
    print("\nFacet keys available:", ", ".join(sorted(facet_info.keys())))

    # 3) Fetch details for the first returned study (if any)
    if studies and studies[0].get("accession"):
        acc = studies[0]["accession"]
        detail = get_study(acc)
        print(f"\nStudy detail for {acc}:")
        print("Name:", detail.get("name"))
        print("Description:", detail.get("description"))

Implementation Details

• Base endpoint constraint: All network requests must target
  

  https://singlecell.broadinstitute.org/single_cell/api/v1/*

  
  (no third-party URLs).
• Core endpoints:

  • GET /search

    : returns study search results (metadata)

  • GET /search/facets

    : returns available facet keys/values for filtering

  • GET /studies/{accession}

    : returns details for a specific study
• Facet filtering (

  facets

  parameter):
  • Format: comma-separated

    key:value

    pairs, e.g.

    organism:human,tissue:lung

  • Common facet keys include:

    organism

    ,

    tissue

    ,

    disease

    ,

    cell_type

  • Some values may be multi-word (e.g.,

    T cell

    ); pass them as-is in the string.
• Pagination / result size:

  • size

    controls the number of returned studies (default behavior depends on the API; set explicitly for deterministic results).
• SSL handling on Windows:
  • If certificate verification fails in certain environments, you may set

    verify=False

    in

    requests.get(...)

    .
  • Prefer

    verify=True

    when possible; disabling verification reduces transport security.
• Error handling:
  • Use

    response.raise_for_status()

    to surface HTTP errors.
  • Treat missing keys defensively (

    dict.get

    ) because response shapes may evolve.
• Data scope:
  • The API primarily returns metadata; raw data downloads typically occur via the portal’s dataset pages and are not covered by these endpoints.