Edit on GitHub

starplast.structures

Structures on demand: metadata ships, coordinates do not.

The app is standalone for data — every measurement is in the committed cache. Coordinates are the one exception, deliberately: 6,538 AlphaFold models plus 12,265 crosslink complex CIFs are gigabytes, git is the wrong place for them, and you do not need any of them until you click a gene.

So this module resolves a structure only when asked, in a fixed order of preference:

  1. a local path already on this machine (the crosslink CIFs, or an AlphaFold mirror if one exists),
  2. the AlphaFold Database, fetched over the network and cached under ~/.cache/starplast/structures.

Everything is best-effort. find_structure returns None rather than raising when a machine is offline or a model does not exist, because a missing structure is a normal state — AlphaFold DB skips the largest proteins, which in this proteome are disproportionately the secreted effectors people care about.

CACHE = '/home/runner/.cache/starplast/structures'
LOCAL_DIRS = ['/home/carruthers/foldseek/proteome_struct/tgon', '/mnt/wd4tb/af3/af_output', '/mnt/wd4tb/af3_home/af3_structures']
AFDB_API = 'https://alphafold.ebi.ac.uk/api/prediction/{acc}'
AFDB_URL = 'https://alphafold.ebi.ac.uk/files/AF-{acc}-F1-model_v{v}.cif'
AFDB_VERSIONS = (6, 5, 4)
def local_structure(gene_id: str, uniprot: str | None = None) -> str | None:

A model already on this machine, or None.

def fetch_alphafold(uniprot: str, timeout: int = 30) -> str | None:

Download one AlphaFold DB model into the cache; return its path, or None if unavailable.

The version is resolved rather than assumed, because the file endpoint serves only the current release. A pinned version turns every fetch into a 404, and a 404 here is indistinguishable from the ordinary case of a protein AlphaFold has no model for -- so the failure is completely silent.

def find_structure(gene_id: str, uniprot: str | None = None, allow_network: bool = True):

Return (path, origin) for a gene's structure, or (None, reason).