kg_microbe.transform_utils.lpsn_api package

Submodules

kg_microbe.transform_utils.lpsn_api.lpsn_api module

LPSN JSON API transform.

Enriches the GSS-based lpsn transform with the fields that only live in LPSN’s authenticated JSON API and not in the bulk CSV:

Publication provenance: publication_doi, publication_pmid, ijsem_list_doi → biolink:published_in edges to doi:* / PMID:* CURIEs.
Full above-genus taxonomy: lpsn_parent_id → additional biolink:subclass_of edges walking up to family / order / class / phylum / domain, which the GSS format doesn’t expose.
Nomenclatural genealogy: basonym_id → biolink:same_as edge (relation skos:exactMatch) from a comb. nov. name to its basonym.
Node-level detail: is_legitimate (boolean) and richer nomenclatural_status (free-text) rolled into the description.
16S rRNA sequence provenance: molecules → one biolink:close_match edge from each LPSN taxon to every INSDC (GenBank/EMBL/DDBJ) accession its type strain has registered, plus a biolink:NucleicAcidEntity stub node per accession. Serves as the TYGS-adjacent bridge to NCBI’s sequence records — an LPSN taxon that failed the direct name-match against NCBITaxon can still be connected via lpsn → INSDC → (NCBI sequence organism) → NCBITaxon in a downstream query.

Access model

The API is auth-gated (free registration at https://lpsn.dsmz.de/register). We look for LPSN_USERNAME + LPSN_PASSWORD in the environment (typically loaded from .env via python-dotenv, same pattern the BacDive transform uses). If either is missing, the transform raises a clear RuntimeError with the exact instructions rather than falling back to silent no-op.

Rate limits

LPSN doesn’t publish an explicit rate limit. Empirically the lpsn Python client tolerates ~1–2 requests/second, which projects to 6–10 hours for a full 34K-record pull. Every response is cached to data/raw/lpsn/api_cache/<record_no>.json (gitignored) so re-runs skip already-fetched records and a partial run resumes cleanly.

Design notes

This is a SEPARATE transform (registered as lpsn_api in DATA_SOURCES) instead of an inline step in the main lpsn transform, so the fast 16-second GSS-only path stays the default. Users who want the API enrichment run both:

poetry run kg transform -s lpsn # fast GSS-only (16 s) poetry run kg transform -s lpsn_api # slow enrichment (hours)

The merge step then combines both nodes.tsv / edges.tsv files.

class kg_microbe.transform_utils.lpsn_api.lpsn_api.LPSNAPITransform(input_dir=None, output_dir=None, client=None, page_fetch=None)

Bases: Transform

Fetch per-record LPSN JSON, emit enrichment nodes + edges.

TRANSFORM_INPUTS: tuple = ('lpsn',): Reads this transform’s output; see Transform.TRANSFORM_INPUTS (#845).

run(data_file=None, show_status=True)

Emit enrichment nodes + edges from LPSN JSON API responses.

Return type:: None

Parameters

data_file:: Optional override for the GSS-transform nodes.tsv we read to know which record_no’s to enrich.
show_status:: Accepted for compatibility with the kg transform CLI. Progress is printed in periodic batches regardless.

kg_microbe.transform_utils.lpsn_api.lpsn_api.WEB_RECORD_SOURCE_KEY = 'kgmicrobe_source': Marks a record dict assembled from the web page rather than the API.

kg_microbe.transform_utils.lpsn_api.lpsn_api.fetch_taxon_page(record_no)

Return the HTML of LPSN’s web page for record_no, or None.

Only reached for records the JSON API has no result for; the page is public and needs no credentials. Any transport or HTTP failure is reported and yields None so the caller falls back to a bare stub rather than aborting the run.

Return type:: Optional[str]

kg_microbe.transform_utils.lpsn_api.lpsn_api.parse_taxon_page(record_no, page)

Build an API-shaped record from an LPSN taxon page, or None.

The page title is <rank>: <name> (Species: Bacterium sonnei); that is the whole reason the page is worth fetching, so no title means no record. Nomenclatural and taxonomic status are taken when present. The dict carries WEB_RECORD_SOURCE_KEY so consumers can tell it from an API record; it never carries ids to link to.

Return type:: Optional[dict]

Module contents

LPSN JSON API transform (enriches the GSS transform’s output).