--- name: literature-search-europepmc description: > Search Europe PMC for scientific literature and download open-access full texts and PDFs. Retrieve full-text XML/plain text by PMCID, get citation lists and bibliography. --- # Europe PMC Database A skill for searching, downloading, and exploring open-access papers from [Europe PMC](https://europepmc.org/) — a comprehensive, free life-science literature database with over 43 million abstracts and 9 million full-text articles. ## Prerequisites 1. **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure `uv` is installed and on PATH. 2. **User Notification**: If .licenses/literature_search_europepmc_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://europepmc.org/ and to always check the license of the papers retrieved by the skill for any restrictions, then (2) create the file recording the notification text and timestamp. ## Core Rules - **Open Access Only**: This skill exclusively searches open-access content. The script automatically appends `OPEN_ACCESS:y` to every search query. Do NOT remove or override this filter. - **NEVER run python3 or python3 -c directly**: the system Python does not necessarily have all key dependencies. Do not attempt to pip install or create new venvs. - **Use the Wrapper**: ALWAYS use the provided script rather than calling the API directly. The script handles rate limiting (1 req/s) and errors. - **Output Files**: All subcommands require `--output` to write results to a file. Read the output file separately to avoid context overflow. - **List Sources.** If this skill is used, ensure this is mentioned in the output AND list the URLs of all papers that were used in producing the output. ## Utility Scripts All commands are subcommands of `scripts/europepmc_api.py`. Rate limiting and retries are handled automatically. ### 1. Search (`search`) Search Europe PMC by query. Supports DOI lookup, keyword search, author search, PMID lookup, and the full [Europe PMC search syntax](https://europepmc.org/searchsyntax). ```bash # Look up a paper by DOI uv run scripts/europepmc_api.py search "DOI:10.1038/s41586-021-03819-2" --output result.json # Keyword search uv run scripts/europepmc_api.py search "CRISPR cancer" --max_results 5 --output results.json # Author search uv run scripts/europepmc_api.py search "AUTH:Jumper J" --max_results 10 --output results.json # PMID lookup uv run scripts/europepmc_api.py search "EXT_ID:34265844 AND SRC:MED" --output result.json # Sorted by citations uv run scripts/europepmc_api.py search "machine learning" \ --sort "CITED desc" --max_results 20 --output results.json ``` **Arguments:** - `query` (str, required) — search query using Europe PMC syntax - `--output` (str, required) — output JSON file path - `--max_results` (int, default 10) — maximum results per page (max 1000) - `--result_type` (str, default `core`) — `core` (full metadata) or `lite` - `--cursor` (str, default `*`) — cursor mark for pagination; pass the `nextCursorMark` value from a previous response to get the next page - `--sort` (str) — sort order, e.g. `CITED desc`, `P_PDATE_D desc` (publication date descending), `P_PDATE_D asc` **Output:** JSON file with three fields: - `hitCount` (int) — total number of matching articles - `nextCursorMark` (str) — cursor for next page; empty string if no more pages - `results` (list) — array of article metadata objects **Search Syntax Quick Reference:** - `DOI:10.xxxx/yyyy` — look up by DOI - `EXT_ID:12345678 AND SRC:MED` — look up by PMID - `AUTH:surname initials` — author search - `TITLE:keyword` — search in title only - `JOURNAL:name` — search by journal - `PUB_YEAR:2024` or `(FIRST_PDATE:[2023-01-01 TO 2023-12-31])` — date filter - `HAS_FT:y` — restrict to articles with full text in Europe PMC - Boolean operators: `AND`, `OR`, `NOT` > **Note**: `OPEN_ACCESS:y` is automatically appended to all queries. You do not > need to add it manually. ### 2. Download PDF (`download_pdf`) Download an open-access PDF from Europe PMC by PMCID. ```bash uv run scripts/europepmc_api.py download_pdf PMC8371605 --output alphafold.pdf ``` **Arguments:** - `pmcid` (str, required) — PubMed Central ID (e.g., `PMC8371605`) - `--output` (str, required) — filepath to save the PDF **Output:** Saves the PDF to the specified file. Exits with an error if the PMCID is not found or the response is not a valid PDF. Whenever you download a PDF, check the pdf downloaded is not empty or corrupted. ### 3. Get Full Text (`get_fulltext`) Retrieve the full text of an open-access article and save to a file. Returns plain text (XML tags stripped) by default, or raw XML with `--format xml`. ```bash # Get plain text (default) uv run scripts/europepmc_api.py get_fulltext PMC8371605 --output fulltext.txt # Get raw XML uv run scripts/europepmc_api.py get_fulltext PMC8371605 --format xml --output fulltext.xml ``` **Arguments:** - `pmcid` (str, required) — PubMed Central ID - `--output` (str, required) — output file path - `--format` (str, default `text`) — `text` (plain text) or `xml` (raw JATS XML) **Output:** Full text written to the specified file. Exits with an error if the article is not in the Europe PMC open-access subset. > **Important**: Only articles in the PMC Open Access Subset have full text > available. If retrieval fails, use `search` to check the `isOpenAccess` field > and fall back to the abstract. ### 4. Get Citations (`get_citations`) Retrieve articles that cite a given paper. ```bash # Get citations for the AlphaFold paper (PMID 34265844) uv run scripts/europepmc_api.py get_citations MED 34265844 \ --page_size 25 --output citations.json ``` **Arguments:** - `source` (str, required) — source database: `MED` (PubMed), `PMC`, `PPR` (preprints), `PAT` (patents) - `article_id` (str, required) — article ID in the source database - `--output` (str, required) — output JSON file path - `--page` (int, default 1) — page number - `--page_size` (int, default 25) — results per page **Output:** JSON file with `hitCount` and `citations` array. ### 5. Get References (`get_references`) Retrieve the reference list (bibliography) of a given paper. ```bash # Get references from the AlphaFold paper uv run scripts/europepmc_api.py get_references MED 34265844 \ --page_size 100 --output references.json ``` **Arguments:** - `source` (str, required) — source database: `MED`, `PMC`, `PPR`, `PAT` - `article_id` (str, required) — article ID in the source database - `--output` (str, required) — output JSON file path - `--page` (int, default 1) — page number - `--page_size` (int, default 25) — results per page **Output:** JSON file with `hitCount` and `references` array. ## Common Workflows ### DOI to PDF ```bash # Step 1: Search for the PMCID uv run scripts/europepmc_api.py search "DOI:10.1038/s41586-021-03819-2" --output result.json PMCID=$(jq -r '.results[0].pmcid // empty' result.json) # Step 2: Download the PDF uv run scripts/europepmc_api.py download_pdf "$PMCID" --output paper.pdf ``` ### PMID to Full Text ```bash # Step 1: Find the PMCID from a PMID uv run scripts/europepmc_api.py search "EXT_ID:34265844 AND SRC:MED" --output result.json PMCID=$(jq -r '.results[0].pmcid // empty' result.json) # Step 2: Get the full text uv run scripts/europepmc_api.py get_fulltext "$PMCID" --output fulltext.txt ``` ### Citation Graph Traversal ```bash # Find what papers cite a landmark study, then check their references uv run scripts/europepmc_api.py get_citations MED 34265844 --page_size 50 --output citing.json # Parse a cited paper's PMID and explore its references uv run scripts/europepmc_api.py get_references MED --output refs.json ``` ### Search with Pagination ```bash # First page uv run scripts/europepmc_api.py search "CRISPR" --max_results 100 --output page1.json # Extract cursor for next page CURSOR=$(jq -r '.nextCursorMark // empty' page1.json) # Next page uv run scripts/europepmc_api.py search "CRISPR" --max_results 100 --cursor "$CURSOR" --output page2.json ```