/literature

name: literature
description: Load when extracting GEO accessions, dataset metadata, and downloadable references from a
  scientific paper (PDF / URL / DOI / PubMed ID / raw text) for downstream omics analysis. Skip when the
  dataset is already in hand; the paper names no dataset to fetch.
trigger: parse paper, literature, GEO accession, download dataset, PDF extract, PubMed, DOI
tags:
- literature
- pdf
- doi
- pubmed
- geo
- metadata

literature

When to use

Extract GEO accessions and heuristic study metadata from paper text. Read local papers explicitly with read_document or fetch remote papers with fetch_text. Skip when the dataset is already in hand.

Use from a step

import pandas as pd
from skills._sdk.notebook import load_skill, read_input, write_output
library = load_skill('literature')
text = read_input('paper.txt', reader=library.read_document)
result = library.extract(text)
write_output(result, 'tables/result.csv')

[examples/example_step.py](examples/example_step.py) runs offline and supports fresh-kernel replay. Pure computations return objects; CLI and steps own writes.

API

<!-- api:begin generated from _api.py; regenerate with run.py api <skill dir> --write -->

`extract(data)`

Extract GEO accessions and heuristic study metadata from text.

:param data: Local paper text; URLs and paths are treated as text, never fetched. :returns: A DataFrame of kind/accession pairs, with metadata in attrs['run_info']. :raises ValueError: data is empty or not a string.

`methodology(data)`

Extract stated numeric method parameters with exact source spans.

:param data: Paper text containing supported parameter names and numeric values. :returns: A DataFrame with param, operator, value, quote, start and end columns. :raises TypeError: data is not text.

`read_document(data)`

Read a local PDF or UTF-8 text file; use as reader= in read_input.

:param data: Local Path or path string; no network requests are made. :returns: Extracted text with empty PDF pages omitted. :raises ImportError: Install pypdf with install_skill_deps for PDFs. :raises OSError: The file cannot be read.

`fetch_text(data, *, input_type='url')`

Fetch article text explicitly from a URL, DOI or PubMed reference.

:param data: Reference sent to the remote service; results may change between requests. :param input_type: Default url; doi and pubmed resolve their respective endpoints. :returns: HTML/XML with tags removed and whitespace collapsed, as in the CLI. :raises ImportError: Install requests with install_skill_deps if unavailable. :raises ValueError: The reference type or URL scheme is unsupported. :raises Exception: HTTP and network errors propagate instead of becoming article text.

`run_info(data, *, keep=True)`

Read heuristic metadata and the accession lists extracted from text.

:param data: Accession table returned by extract. :param keep: Default True; use False to remove metadata from the table. :returns: An independent metadata dictionary. :raises KeyError: The table has no extraction diagnostics.

`accession_figure(data)`

Plot accession counts by GEO accession kind.

:param data: Accession table returned by extract. :returns: A matplotlib Figure, including zero counts for missing kinds. :raises KeyError: kind is absent.

<!-- api:end -->

Methods and parameters

extract performs local regex/keyword extraction only. methodology returns exact quotes and character spans for stated numeric parameters. read_document reads UTF-8 text or PDF, and fetch_text explicitly requests URL/DOI/PubMed text. Neither function downloads datasets; the CLI retains its optional GEO download workflow.

Gotchas

• `extract` returns uppercase, deduplicated and sorted GEO identifiers. `methodology` never fills absent parameter defaults. `read_document` raises when pypdf is missing or input cannot be read. `fetch_text` propagates failures rather than treating an error message as paper text. Metadata labels remain heuristics, not validated study annotations.

Inputs and outputs

`extracted_metadata.json`, `source.txt`, `report.md` and `result.json` at the output root. The CLI creates data/ and optionally downloads into per-GSE directories; --data-dir chooses another destination. The original source.txt write remains best-effort. The function library writes no files.

CLI

python skills/literature/literature_parse.py --demo --output /tmp/literature

See also

• [Parameters](references/parameters.md)
• [Methodology](references/methodology.md)
• [Output contract](references/output_contract.md)

Dependencies

`pandas`, `matplotlib`, `pypdf`, `requests`