Metapub

https://metapub.readthedocs.io/en/latest
Admin
Metapub is a Python library for accessing biomedical literature and databases, providing clean...
Tokens:210,157
Snippets:1,514
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install Metapub via pip

Source: https://metapub.readthedocs.io/en/latest/_sources/installation.rst.txt

Standard installation command for the Metapub library.

```bash
pip install metapub
```

--------------------------------

### Install Metapub with test dependencies

Source: https://metapub.readthedocs.io/en/latest/_sources/installation.rst.txt

Installs the library along with additional packages required for running tests.

```bash
pip install metapub[test]
```

--------------------------------

### Integration Example

Source: https://metapub.readthedocs.io/en/latest/api_models.html

An example demonstrating how to integrate different Metapub fetchers for a research workflow.

```APIDOC
## Integration Example

### Description
Demonstrates a research workflow integrating PubMedFetcher, MedGenFetcher, and ClinVarFetcher to find variants and literature related to a gene.

### Workflow
1. Find genetic variants associated with a gene using `ClinVarFetcher`.
2. Get MedGen concepts for the gene using `MedGenFetcher`.
3. Collect all related literature (PMIDs) from variants using `ClinVarFetcher`.

### Example Usage
```python
from metapub import PubMedFetcher, MedGenFetcher, ClinVarFetcher

# Initialize fetchers
fetch = PubMedFetcher()
mg = MedGenFetcher()
cv = ClinVarFetcher()

gene = 'BRCA1'

# 1. Find genetic variants
variant_ids = cv.ids_by_gene(gene, single_gene=True)

# 2. Get MedGen concepts for the gene
concepts = mg.concepts_for_term(f"{gene}[gene]")

# 3. Collect all related literature
all_pmids = set()

# From variants
for var_id in variant_ids[:5]:  # Limit for demo
    pmids = cv.pmids_for_id(var_id)
    all_pmids.update(pmids)

# Further processing could involve using PubMedFetcher with all_pmids
# articles = fetch.articles(all_pmids)
```
```

--------------------------------

### Quick Start: Search and Analyze Literature

Source: https://metapub.readthedocs.io/en/latest/index.html

A basic example demonstrating how to initialize PubMedFetcher, search for literature on a given topic, and retrieve a list of PMIDs.

```python
from metapub import PubMedFetcher, FindIt

# Search and analyze literature
fetch = PubMedFetcher()
pmids = fetch.pmids_for_query('machine learning genomics', retmax=10)


```

--------------------------------

### Initialize FindIt instance

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/findit/findit.html

Example of instantiating the FindIt class with a PMID.

```python
FindIt(pmid=1234567)
```

--------------------------------

### Handle Conversion Errors

Source: https://metapub.readthedocs.io/en/latest/_sources/error_handling.rst.txt

Example of iterating through actionable suggestions when a conversion error occurs.

```python
from metapub.convert import pmid2doi
from metapub.ncbi_errors import NCBIServiceError

try:
    doi = pmid2doi(12345)
    print(f"DOI: {doi}")
    
except NCBIServiceError as e:
    print("NCBI service issue detected:")
    for suggestion in e.suggestions:
        print(f"  • {suggestion}")
        
except Exception as e:
    print(f"Other error: {e}")
```

--------------------------------

### PubMed Article Fetcher Examples

Source: https://metapub.readthedocs.io/en/latest/command_line_tools.html

Common usage patterns for fetching article information.

```bash
# Fetch basic article information
pubmed_article 33157158

# Include abstract
pubmed_article -a 33157158

# Full article (experimental)
pubmed_article -f 33157158
```

--------------------------------

### Quick Start Literature Analysis

Source: https://metapub.readthedocs.io/en/latest/_sources/index.rst.txt

Perform a basic search and check for PDF availability for the retrieved articles.

```python
from metapub import PubMedFetcher, FindIt

# Search and analyze literature
fetch = PubMedFetcher()
pmids = fetch.pmids_for_query('machine learning genomics', retmax=10)

# Check PDF availability
accessible_papers = []
for pmid in pmids:
    article = fetch.article_by_pmid(pmid)
    src = FindIt(pmid)
    
    if src.url:
        accessible_papers.append({
            'title': article.title,
            'journal': article.journal,
```

--------------------------------

### NCBI Health Check Output Examples

Source: https://metapub.readthedocs.io/en/latest/command_line_tools.html

Sample console output for normal operation and service outage scenarios.

```text
🏥 NCBI SERVICE HEALTH CHECK REPORT
================================================================================

📊 SUMMARY: 5 services checked (quick mode)
   ✅ UP: 5

📋 DETAILED RESULTS:
--------------------------------------------------------------------------------
✅ EFetch (PubMed Articles)
   URL: eutils:efetch
   Status: UP
   HTTP: 200
   Response Time: 0.26s
   Details: Response time: 0.26s (with API key)
```

```text
🚨 CRITICAL: Core PubMed services are down. Tests will likely fail.
   Consider using FORCE_NETWORK_TESTS=1 only if you need to debug specific issues.
```

--------------------------------

### Initialize UrlReverse class

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/urlreverse.html

The constructor for the UrlReverse class, which ensures the URL starts with a protocol and initializes necessary fetcher engines.

```python
def __init__(self, url, skip_cache=False, **kwargs):
    if not url.lower().startswith('http'):
        url = 'http://' + url

    _start_engines()
```

--------------------------------

### Basic PDF Discovery with FindIt

Source: https://metapub.readthedocs.io/en/latest/_sources/api_findit.rst.txt

This example demonstrates basic PDF discovery using the FindIt class. It takes a PMID, attempts to find a PDF, and prints the URL if successful or the reason for failure. It also shows how to access backup URLs.

```python
from metapub import FindIt
   
   # Find PDF by PMID
   src = FindIt('33157158')
   
   if src.url:
       print(f"✓ PDF available: {src.url}")
       print(f"Journal: {src.pma.journal}")
   else:
       print(f"✗ No access: {src.reason}")
       if src.backup_url:
           print(f"Backup URL: {src.backup_url}")
```

--------------------------------

### NCBI Service Error Output Example

Source: https://metapub.readthedocs.io/en/latest/error_handling.html

An example of the user-friendly, formatted error message displayed when NCBI services are experiencing issues.

```text
╔══════════════════════════════════════════════════════════════════════════════╗
║                            NCBI SERVICE ISSUE                               ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  NCBI servers are experiencing issues.                                      ║
║                                                                              ║
║  Suggested actions:
║  • NCBI servers are temporarily unavailable                                 ║
║  • This is not an issue with your code or data                              ║
║  • Try again in a few minutes                                               ║
║  • Check NCBI status: https://www.ncbi.nlm.nih.gov/                         ║
║                                                                              ║
║  This is likely a temporary issue with NCBI's servers, not your code.       ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

```

--------------------------------

### Initialize Logging and Constants

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/config.html

Sets up logging, defines package name, default email, temporary directory, and cache directory. It checks for write permissions for the default cache directory and falls back to the system's temporary directory if necessary. It also checks for the NCBI_API_KEY environment variable.

```python
import os
import coloredlogs
import logging
import tempfile

log = logging.getLogger('metapub.config')
coloredlogs.install(logger=logging.getLogger('metapub'))

PKGNAME = 'metapub'

# email address of this package's maintainer, included with certain NCBI calls.
# you can change this to another email address if you would prefer to be contacted.
DEFAULT_EMAIL = 'naomi@nthmost.com'

# where to place XML (temporarily) when downloaded.
TMPDIR = '/tmp'

# default cache directory for SQLite cache engines
DEFAULT_CACHE_DIR = os.path.join(os.path.expanduser('~'), '.cache')
if not os.access(DEFAULT_CACHE_DIR, os.W_OK):
    # default cache dir is not writeable
    # therefore ask the os for a temp directory
    DEFAULT_CACHE_DIR = tempfile.gettempdir()

API_KEY = os.getenv('NCBI_API_KEY', None)
if API_KEY:
    log.debug('NCBI_API_KEY found.')
else:
    log.warning('NCBI_API_KEY was not set.')
```

--------------------------------

### BibTeX Book Citation Output Example

Source: https://metapub.readthedocs.io/en/latest/_sources/citation_formatting.rst.txt

Example output of the BibTeX citation format for a book, including author, title, and year fields.

```bibtex
@book{Tranebjærg2002,
author = {Tranebjærg, L and Samson, RA and Green, GE},
title = {Jervell and Lange-Nielsen syndrome},
year = {2002},
}
```

--------------------------------

### Get Formatted Book Citation

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

Access the `citation` property to get a formatted citation string for a PubMedBookArticle. This includes authors, title, publisher, and publication details.

```text
Tranebjarg L, et al. Jervell and Lange-Nielsen syndrome. 2002 Jul 29 (Updated 2014 Nov 20). In: Pagon RA, et al., editors. GeneReviews (Internet). Seattle (WA): University of Washington, Seattle; 1993-2015. Available from: https://www.ncbi.nlm.nih.gov/books/NBK1405/.
```

--------------------------------

### Setup Process Logger

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/config.html

Configures and returns a file-based logger for process logging. It sets the log level, formatter, and handler for the specified file path.

```python
def get_process_log(filepath, loglevel=logging.INFO, name=PKGNAME+'.process'):
    """Sets up a file-based logger for process logging and returns its log object."""
    log = logging.getLogger(name)
    log.setLevel(loglevel)
    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
    fh = logging.FileHandler(filepath)
    fh.setFormatter(formatter)
    fh.setLevel(loglevel)
    log.addHandler(fh)
    return log
```

--------------------------------

### Get Species

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/clinvarvariant.html

Retrieves the species associated with the variation. Handles VCV format by searching within 'Species' element, otherwise uses a general get method.

```python
def _get_species(self):
        if self._is_vcv_format:
            species_elem = self.variation_archive.find('Species')
            return species_elem.text if species_elem is not None else None
        else:
            return self._get('Species')
```

--------------------------------

### Initialize NCBIErrorDetector

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/ncbi_errors.html

Sets up the detector with a default cache duration of 300 seconds.

```python
class NCBIErrorDetector:
    """Detects and categorizes NCBI service errors."""

    def __init__(self):
        self._status_cache = {}
        self._last_check = 0
        self._cache_duration = 300  # 5 minutes
```

--------------------------------

### Initialize and Use MedGenFetcher

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/medgenfetcher.html

Demonstrates basic instantiation and common retrieval methods for MedGen concepts and UIDs.

```python
fetch = MedGenFetcher()

To specify a service method (more coming soon):

fetch = MedGenFetcher('eutils')

To return a MedGenConcept from a known UID:

concept = fetch.concept_by_uid(known_UID)

To return a list of UIDs relevant to a given term known in medgen:

uids = fetch.uids_by_term(some_term)

To get a medgen UID given a known Concept ID (cui):

uid = fetch.uid_for_cui(known_cui)
```

--------------------------------

### BibTeX Article Citation Output Example

Source: https://metapub.readthedocs.io/en/latest/_sources/citation_formatting.rst.txt

Example output of the BibTeX citation format for an article, showing structured fields like author, title, journal, and year.

```bibtex
@article{Ruvolo2013,
author = {Ruvolo, G and Roccheri, MC and Brucculeri, AM and Longobardi, S and Cittadini, E and Bosco, L},
doi = {10.1007/s10815-013-9951-y},
title = {Lower sperm DNA fragmentation after r-FSH administration in functional hypogonadotropic hypogonadism},
journal = {J Assist Reprod Genet},
year = {2013},
volume = {30},
pages = {497-503},
}
```

--------------------------------

### Use Metapub command line tools

Source: https://metapub.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Execute common tasks like ID conversion and health checks via the command line.

```bash
# Convert between IDs
convert pmid2doi 12345678
convert doi2pmid 10.1038/nature12373

# Get article information
pubmed_article 12345678

# Check NCBI health
ncbi_health_check
```

--------------------------------

### Get Current Stack Frame

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Provides a way to get the current frame object for the caller's stack frame. This is used internally for determining the source of log messages.

```python
if hasattr(sys, "_getframe"):
    currentframe = lambda: sys._getframe(1)
else: #pragma: no cover
    def currentframe():
        """Return the frame object for the caller's stack frame."""
        try:
            raise Exception
        except Exception:
            return sys.exc_info()[2].tb_frame.f_back
```

--------------------------------

### Get Formatted HTML Book Citation

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

Access the `citation_html` property to get a formatted citation string with HTML tags for a book. This is useful for rendering citations in web contexts.

```text
Tranebjarg L, <i>et al</i>. <i>Jervell and Lange-Nielsen syndrome</i>. 2002 Jul 29 (Updated 2014 Nov 20). In: Pagon RA, <i>et al</i>., editors. GeneReviews (Internet). Seattle (WA): University of Washington, Seattle; 1993-2015. Available from: https://www.ncbi.nlm.nih.gov/books/NBK1405/.
```

--------------------------------

### Initialize metapub.crossref module

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/crossref.html

Contains the necessary imports and logger initialization for the crossref module.

```python
# -*- coding: utf-8 -*-

import datetime 
import logging

from habanero import Crossref as CREngine
import Levenshtein

from .base import Borg
from .config import DEFAULT_EMAIL
from . import cite
from .ncbi_errors import NCBIServiceError

log = logging.getLogger('metapub.crossref')
```

--------------------------------

### Get Formatted HTML Article Citation

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

Access the `citation_html` property to get a formatted citation string with HTML tags for an article. This is useful for rendering citations in web contexts.

```text
McNally EM, <i>et al</i>. Genetic mutations and mechanisms in dilated cardiomyopathy. <i>Journal of Clinical Investigation</i>. 2013; <b>123</b>:19-26. doi: 10.1172/JCI62862.
```

--------------------------------

### Initialize DXDOI Instance

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/methods.html

Singleton pattern to manage the DXDOI lookup engine instance.

```python
DXDOI_INSTANCE = None



[docs]
def DXDOI():
    global DXDOI_INSTANCE
    if not DXDOI_INSTANCE:
        DXDOI_INSTANCE = DxDOI()
    return DXDOI_INSTANCE
```

--------------------------------

### Get Formatted Article Citation

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

Access the `citation` property to get a formatted citation string for a PubMedArticle. This includes authors, title, journal, year, volume, pages, and DOI for articles.

```text
McNally EM, et al. Genetic mutations and mechanisms in dilated cardiomyopathy. Journal of Clinical Investigation. 2013; 123:19-26. doi: 10.1172/JCI62862.
```

--------------------------------

### Full ClinVar Fetcher Example

Source: https://metapub.readthedocs.io/en/latest/api_fetchers.html

Demonstrates initializing the ClinVarFetcher, finding variants for a gene, retrieving detailed variant information, and obtaining supporting literature.

```python
from metapub import ClinVarFetcher

# Initialize fetcher
cv = ClinVarFetcher()

# Find variants for a gene
variant_ids = cv.ids_by_gene('BRCA1', single_gene=True)

# Get detailed variant information
for var_id in variant_ids[:5]:  # First 5 variants
    variant = cv.variant(var_id)
    print(f"Accession: {variant.accession}")
    print(f"HGVS: {variant.hgvs_c}")
    print(f"Clinical significance: {variant.clinical_significance}")
    print(f"Molecular consequences: {variant.molecular_consequences}")

    # Get supporting literature
    pmids = cv.pmids_for_id(var_id)
    print(f"Supporting papers: {len(pmids)}")
```

--------------------------------

### GET /bookid2pmid

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

Resolve a PubMed ID from a book ID.

```APIDOC
## GET /bookid2pmid

### Description
Convenience interface to fetch a PMID for a given book ID.

### Method
GET

### Parameters
#### Query Parameters
- **book_id** (str) - Required - The book ID to resolve.
```

--------------------------------

### Initialize Eutils Client

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedfetcher.html

Initializes the Eutils client, setting up the cache path and client instance. Raises NotImplementedError for unsupported methods.

```python
if method=='eutils':
            self._cache_path = get_cache_path(cachedir, self._cache_filename)
            self.qs = get_eutils_client(self._cache_path)
            self.article_by_pmid = self._eutils_article_by_pmid
            self.article_by_pmcid = self._eutils_article_by_pmcid
            self.article_by_doi = self._eutils_article_by_doi
            self.pmids_for_query = self._eutils_pmids_for_query
        else:
            raise NotImplementedError('Planned future options: "mysql", "cache-only"')
```

--------------------------------

### Network Timeout and Redirect Configuration for FindIt

Source: https://metapub.readthedocs.io/en/latest/_sources/api_findit.rst.txt

This example configures network behavior for FindIt, setting a custom request timeout and maximum number of redirects. It also shows how to configure for faster processing with tighter limits.

```python
# Configure network behavior
   src = FindIt(
       pmid='12345678',
       request_timeout=20,     # Wait up to 20 seconds for responses
       max_redirects=2         # Follow max 2 redirects
   )
   
   # For faster processing with tighter limits
   src = FindIt(
       pmid='12345678', 
       request_timeout=5,      # Quick timeout for batch processing
       max_redirects=1         # Minimal redirects
   )
```

--------------------------------

### GET /LogRecord/message

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Retrieves the formatted message for a specific LogRecord instance.

```APIDOC
## GET /LogRecord/message

### Description
Returns the message for this LogRecord after merging any user-supplied arguments with the message.

### Response
#### Success Response (200)
- **message** (string) - The final formatted log message.
```

--------------------------------

### Initialize ClinVarFetcher

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/clinvarfetcher.html

Instantiate the ClinVarFetcher, which is a Borg singleton. You can specify a custom cache directory. All instances share the same state.

```python
clinvar = ClinVarFetcher()

clinvar = ClinVarFetcher(cachedir='/path/to/cachedir')
```

--------------------------------

### GET /article_by_title

Source: https://metapub.readthedocs.io/en/latest/api_fetchers.html

Finds a work by its title using the CrossRef API.

```APIDOC
## GET /article_by_title

### Description
Uses CrossRef to find a work by its title. Returns the first item in the result list.

### Method
GET

### Parameters
#### Query Parameters
- **title** (str) - Required - The title of the work to search for.

### Response
#### Success Response (200)
- **CrossRefWork** (object) - The first matching publication metadata or None if no results found.
```

--------------------------------

### FindIt Initialization

Source: https://metapub.readthedocs.io/en/latest/api/metapub.findit.html

Initializes the FindIt object with article identifiers and configuration settings.

```APIDOC
## __init__(pmid=None, cachedir='/home/docs/.cache', **kwargs)

### Description
Initialize FindIt to locate full-text PDFs for academic papers.

### Parameters
- **pmid** (str or int) - Optional - PubMed ID of the article.
- **cachedir** (str) - Optional - Directory for caching results. Defaults to '/home/docs/.cache'.
- **kwargs** (dict) - Optional - Additional arguments: doi (str), url (str), use_nih (bool), use_crossref (bool), doi_min_score (int), verify (bool), retry_errors (bool), debug (bool), tmpdir (str), request_timeout (int), max_redirects (int).

### Errors
- **MetaPubError**: Raised if neither pmid nor doi is provided.
```

--------------------------------

### GET /pmids_for_citation

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedfetcher.html

Retrieves PubMed IDs based on citation metadata.

```APIDOC
## GET /pmids_for_citation

### Description
Returns a list of PubMed IDs for a given citation. Requires at least 3 of the 5 specified parameters.

### Parameters
#### Query Parameters
- **jtitle/journal** (string) - Optional - Journal title.
- **year/date** (string) - Optional - Publication year.
- **volume** (string) - Optional - Journal volume.
- **spage/first_page** (string) - Optional - Starting page.
- **aulast/author1_first_lastfm** (string) - Optional - First author's last name.

### Response
- **List** (array) - A list of PubMed IDs.
```

--------------------------------

### Get Logger Class

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Retrieves the currently set class for logger instantiation.

```python
def getLoggerClass():
    """
    Return the class to be used when instantiating a logger.
    """
    return _loggerClass
```

--------------------------------

### Metapub Conversion with Error Handling

Source: https://metapub.readthedocs.io/en/latest/error_handling.html

Demonstrates error handling for Metapub's conversion functions, catching NCBIServiceError and iterating through suggestions.

```python
from metapub.convert import pmid2doi
from metapub.ncbi_errors import NCBIServiceError

try:
    doi = pmid2doi(12345)
    print(f"DOI: {doi}")

except NCBIServiceError as e:
    print("NCBI service issue detected:")
    for suggestion in e.suggestions:
        print(f"  • {suggestion}")

except Exception as e:
    print(f"Other error: {e}")

```

--------------------------------

### GET /try_pmid_methods

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/methods.html

Attempts to extract a PubMed Identifier (PMID) directly from a URL.

```APIDOC
## GET /try_pmid_methods

### Description
Uses regex patterns to identify and extract the PMID from common PubMed and journal-specific lookup URLs.

### Parameters
#### Query Parameters
- **url** (str) - Required - The URL containing the PMID.

### Response
#### Success Response (200)
- **pmid** (str) - The extracted PMID.

#### Response Example
{
  "pmid": "22253870"
}
```

--------------------------------

### Formatter Initialization

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Explains the initialization of the Formatter class, including format strings, date formatting, and style options.

```APIDOC
## Formatter Initialization

### Description
Initializes the formatter with a specified format string, optional date format, and a style for formatting.

### Method
`__init__(self, fmt=None, datefmt=None, style='%', validate=True, *, defaults=None)`

### Parameters
- **fmt** (string) - Optional - The format string.
- **datefmt** (string) - Optional - The date format string.
- **style** (string) - Optional - The style of formatting ('%', '{', or '$'). Defaults to '%'.
- **validate** (boolean) - Optional - Whether to validate the format string. Defaults to True.
- **defaults** (dict) - Optional - Default values for the format string.

### Request Body
(Not applicable for initialization)

### Response
(Not applicable for initialization)
```

--------------------------------

### PubMed Article Sample Output

Source: https://metapub.readthedocs.io/en/latest/command_line_tools.html

Example output format for a successful article fetch.

```text
Title: CRISPR-Cas9 gene editing for sickle cell disease and β-thalassemia
Authors: Frangoul H, Altshuler D, Cappellini MD, Chen YS, Domm J, Eustace BK, ...
Journal: New England Journal of Medicine
Year: 2021
DOI: 10.1056/NEJMoa2031054
PMID: 33157158
```

--------------------------------

### Initialize NCBIClient (Modern Cache)

Source: https://metapub.readthedocs.io/en/latest/advanced.html

Initializes the NCBIClient, recommended for new code, using URL-based caching with parameter normalization and JSON serialization. It offers better thread safety and error handling.

```python
from metapub.ncbi_client import NCBIClient
client = NCBIClient(cache_path='/path/to/cache.db')
response = client.efetch(db='pubmed', id='12345678')
```

--------------------------------

### Run Metapub Tools as Python Modules

Source: https://metapub.readthedocs.io/en/latest/command_line_tools.html

Shows alternative ways to execute metapub command-line tools by invoking them as Python modules using `python -m`. This is useful for troubleshooting or when direct executables are not in the PATH.

```python
# Alternative ways to run the tools
python -m metapub.ncbi_health_check --quick
python -m metapub.pubmedfetcher_cli 33157158
python -m metapub.convert --to-doi 33157158

```

--------------------------------

### Configure logging with basicConfig

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

This function initializes the root logger with a StreamHandler or FileHandler based on provided keyword arguments.

```python
def basicConfig(**kwargs):
    """
    Do basic configuration for the logging system.

    This function does nothing if the root logger already has handlers
    configured, unless the keyword argument *force* is set to ``True``.
    It is a convenience method intended for use by simple scripts
    to do one-shot configuration of the logging package.

    The default behaviour is to create a StreamHandler which writes to
    sys.stderr, set a formatter using the BASIC_FORMAT format string, and
    add the handler to the root logger.

    A number of optional keyword arguments may be specified, which can alter
    the default behaviour.

    filename  Specifies that a FileHandler be created, using the specified
              filename, rather than a StreamHandler.
    filemode  Specifies the mode to open the file, if filename is specified
              (if filemode is unspecified, it defaults to 'a').
    format    Use the specified format string for the handler.
    datefmt   Use the specified date/time format.
    style     If a format string is specified, use this to specify the
              type of format string (possible values '%', '{', '$', for
              %-formatting, :meth:`str.format` and :class:`string.Template`
              - defaults to '%').
    level     Set the root logger level to the specified level.
    stream    Use the specified stream to initialize the StreamHandler. Note
              that this argument is incompatible with 'filename' - if both
              are present, 'stream' is ignored.
    handlers  If specified, this should be an iterable of already created
              handlers, which will be added to the root logger. Any handler
              in the list which does not have a formatter assigned will be
              assigned the formatter created in this function.
    force     If this keyword  is specified as true, any existing handlers
              attached to the root logger are removed and closed, before
              carrying out the configuration as specified by the other
              arguments.
    encoding  If specified together with a filename, this encoding is passed to
              the created FileHandler, causing it to be used when the file is
              opened.
    errors    If specified together with a filename, this value is passed to the
              created FileHandler, causing it to be used when the file is
              opened in text mode. If not specified, the default value is
              `backslashreplace`.

    Note that you could specify a stream created using open(filename, mode)
    rather than passing the filename and mode in. However, it should be
    remembered that StreamHandler does not close its stream (since it may be
    using sys.stdout or sys.stderr), whereas FileHandler closes its stream
    when the handler is closed.

    .. versionchanged:: 3.2
       Added the ``style`` parameter.

    .. versionchanged:: 3.3
       Added the ``handlers`` parameter. A ``ValueError`` is now thrown for
       incompatible arguments (e.g. ``handlers`` specified together with
       ``filename``/``filemode``, or ``filename``/``filemode`` specified
       together with ``stream``, or ``handlers`` specified together with
       ``stream``.

    .. versionchanged:: 3.8
       Added the ``force`` parameter.

    .. versionchanged:: 3.9
       Added the ``encoding`` and ``errors`` parameters.
    """
    # Add thread safety in case someone mistakenly calls
    # basicConfig() from multiple threads
    _acquireLock()
    try:
        force = kwargs.pop('force', False)
        encoding = kwargs.pop('encoding', None)
        errors = kwargs.pop('errors', 'backslashreplace')
        if force:
            for h in root.handlers[:]:
                root.removeHandler(h)
                h.close()
        if len(root.handlers) == 0:
            handlers = kwargs.pop("handlers", None)
            if handlers is None:
                if "stream" in kwargs and "filename" in kwargs:
                    raise ValueError("'stream' and 'filename' should not be "
                                     "specified together")
            else:
                if "stream" in kwargs or "filename" in kwargs:
                    raise ValueError("'stream' or 'filename' should not be "
                                     "specified together with 'handlers'")
            if handlers is None:
                filename = kwargs.pop("filename", None)
                mode = kwargs.pop("filemode", 'a')
                if filename:
                    if 'b' in mode:
                        errors = None
                    else:
                        encoding = io.text_encoding(encoding)
                    h = FileHandler(filename, mode,
                                    encoding=encoding, errors=errors)
                else:
```

--------------------------------

### GET /article_by_doi

Source: https://metapub.readthedocs.io/en/latest/api_fetchers.html

Retrieves a CrossRefWork object by querying the Crossref works/DOI REST endpoint.

```APIDOC
## GET /article_by_doi

### Description
Returns a CrossRefWork object loaded by querying the Crossref works/DOI REST endpoint.

### Method
GET

### Parameters
#### Query Parameters
- **doi** (str) - Required - The DOI of the article to retrieve.

### Response
#### Success Response (200)
- **CrossRefWork** (object) - The retrieved publication metadata.

#### Error Handling
- **404** - DOI not found.
- **Exception** - Network or service issues.
```

--------------------------------

### Metapub Convert Main Function

Source: https://metapub.readthedocs.io/en/latest/api/metapub.html

The main entry point for the metapub.convert module's command-line interface.

```python
metapub.convert.main()
```

--------------------------------

### GET /pmids_for_medical_genetics_query

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedfetcher.html

Retrieves a list of PubMed IDs filtered by medical genetics categories.

```APIDOC
## GET /pmids_for_medical_genetics_query

### Description
Takes a query and a medical genetics category to return a list of PubMed IDs.

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query string.
- **category** (string) - Optional - Genetics category (all, diagnosis, differential_diagnosis, clinical_description, management, genetic_counseling, genetic_testing). Default: all.
- **retstart** (int) - Optional - Starting index for results.
- **retmax** (int) - Optional - Maximum number of results. Default: 250.

### Response
- **List** (array) - A list of PubMed IDs.
```

--------------------------------

### Initialize PubMedFetcher and NCBIClient

Source: https://metapub.readthedocs.io/en/latest/_sources/advanced.rst.txt

Instantiates both the traditional PubMedFetcher and the modern NCBIClient, highlighting their different caching approaches.

```python
# Traditional style (still supported)
from metapub import PubMedFetcher
fetch = PubMedFetcher()  # Uses traditional caching

# Modern style (recommended for new code)
from metapub.ncbi_client import NCBIClient
client = NCBIClient(cache_path='/path/to/cache.db')
response = client.efetch(db='pubmed', id='12345678')
```

--------------------------------

### GET /pmids_for_query

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedfetcher.html

Performs a search query against PubMed and returns a list of matching PMIDs.

```APIDOC
## GET /pmids_for_query

### Description
Returns a list of PMIDs for a given freeform query string, supporting pagination and advanced query tokens.

### Method
GET

### Parameters
#### Query Parameters
- **query** (string) - Optional - The freeform search query string.
- **retstart** (integer) - Optional - The index of the first record to retrieve (default: 0).
- **retmax** (integer) - Optional - The maximum number of records to retrieve (default: 250).
- **since** (string) - Optional - Start date for the query.
- **until** (string) - Optional - End date for the query.
- **pmc_only** (boolean) - Optional - If true, restricts results to PubMedCentral articles.

### Response
#### Success Response (200)
- **pmids** (array) - A list of PMIDs matching the query.

#### Response Example
{
  "pmids": ["123456", "789012"]
}
```

--------------------------------

### Configure Custom Cache Directory

Source: https://metapub.readthedocs.io/en/latest/_sources/api_fetchers.rst.txt

Shows how to set a custom directory for caching metadata by using an environment variable or specifying it directly when initializing a fetcher.

```python
import os
   
   # Set custom cache directory
   os.environ['METAPUB_CACHE_DIR'] = '/path/to/large/cache'
   
   # Or specify per-fetcher
   fetch = PubMedFetcher(cachedir='/custom/cache/path')
```

--------------------------------

### Initialize UrlReverse and retrieve identifiers

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/urlreverse.html

Demonstrates how to instantiate the UrlReverse class with a URL and access the resulting DOI and PMID properties.

```python
urlrev = UrlReverse('http://jmg.bmj.com/content/43/2/97.full.pdf')
print(urlrev.doi)       # 10.1136/jmg.2005.030833
print(urlrev.pmid)      # 15879500
```

--------------------------------

### Retrieve PMID and URL

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedarticle.html

Methods to get the PubMed ID and generate the corresponding URL.

```python
def _get_pmid(self):
        return self._get(self._root+'/PMID')

    def _get_url(self):
        return 'https://ncbi.nlm.nih.gov/pubmed/'+str(self.pmid)
```

--------------------------------

### Initialize UrlReverse

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/urlreverse.html

Constructor for the UrlReverse class, setting up logging, caching, and initial state.

```python
        self.url = url
        self.steps = []

        self.pmid = None
        self.doi = None
        self.info = None

        self.expiry_date = kwargs.get('expiry_date', None)

        cachedir = kwargs.get('cachedir', DEFAULT_CACHE_DIR)
        self._cache = None if cachedir is None else _get_urlreverse_cache(cachedir)

        self._log = logging.getLogger('metapub.UrlReverse')
        if kwargs.get('debug', False):
            self._log.setLevel(logging.DEBUG)
        else:
            self._log.setLevel(logging.INFO)

        if self._cache:
            self._load_from_cache()
        else:
            self._urlreverse()
```

--------------------------------

### GET /article/pubdate

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/pubmedarticle.html

Retrieves the normalized publication date for a PubMed article as a datetime object.

```APIDOC
## GET /article/pubdate

### Description
Returns the best available publication date from PubMed XML. The logic prioritizes Article PubDate, followed by book contribution dates, and finally history dates (pubmed, entrez, etc.).

### Method
GET

### Response
#### Success Response (200)
- **pubdate** (datetime) - The normalized publication date object or null if no date is found.

### Response Example
{
  "pubdate": "2023-10-27T00:00:00"
}
```

--------------------------------

### Get Variation Type

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/clinvarvariant.html

Retrieves the Variation Type, handling both VCV and non-VCV formats.

```python
def _get_variation_type(self):
        if self._is_vcv_format:
            return self.variation_archive.get('VariationType')
        else:
            return self.content.get('VariationType')
```

--------------------------------

### Setup Data Logger

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/config.html

Configures and returns a file-based logger for data logging. It sets the log level to DEBUG, disables propagation, and uses a formatter that produces empty strings.

```python
def get_data_log(filepath, name=PKGNAME+'.data'):
    """Sets up a file-based logger for data logging and returns its log object."""
    datalog = logging.getLogger(name)
    datalog.setLevel(logging.DEBUG)
    datalog.propagate = False
    formatter = logging.Formatter('')
    fh = logging.FileHandler(filepath)
    fh.setFormatter(formatter)
    datalog.addHandler(fh)
    return datalog
```

--------------------------------

### Get Variation Name

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/clinvarvariant.html

Retrieves the Variation Name, handling both VCV and non-VCV formats.

```python
def _get_variation_name(self):
        if self._is_vcv_format:
            return self.variation_archive.get('VariationName')
        else:
            return self.content.get('VariationName')
```

--------------------------------

### Initialize PubMedFetcher and Define Search Parameters

Source: https://metapub.readthedocs.io/en/latest/_sources/tutorials.rst.txt

Initializes the PubMedFetcher and sets up search terms and a date range for querying PubMed. Ensure you have the 'metapub' and 'pandas' libraries installed.

```python
from metapub import PubMedFetcher
import pandas as pd
from datetime import datetime

fetch = PubMedFetcher()

# Define search parameters
search_terms = [
    'machine learning AND genomics',
    'artificial intelligence AND genetics',
    'deep learning AND biomarker'
]

date_range = {
    'since': '2020/01/01',
    'until': '2024/12/31'
}
```

--------------------------------

### Get Variation ID

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/clinvarvariant.html

Retrieves the Variation ID, handling both VCV and non-VCV formats.

```python
def _get_variation_id(self):
        if self._is_vcv_format:
            return self.variation_archive.get('VariationID')
        else:
            return self.content.get('VariationID')
```

--------------------------------

### FindIt Initialization

Source: https://metapub.readthedocs.io/en/latest/_sources/api_findit.rst.txt

Initializes the FindIt object to begin the PDF discovery process for a specific article.

```APIDOC
## FindIt.__init__

### Description
Initializes the FindIt instance for a given identifier (e.g., DOI or PubMed ID). Configures network behavior for discovery.

### Parameters
#### Request Body
- **identifier** (str) - Required - The DOI or PubMed ID of the article.
- **request_timeout** (int) - Optional - Maximum time in seconds to wait for HTTP responses (default: 10).
- **max_redirects** (int) - Optional - Maximum number of HTTP redirects to follow (default: 3).

### Response
#### Success Response (200)
- **url** (str) - Direct link to downloadable PDF if found.
- **backup_url** (str) - Alternative URL if primary fails.
- **pma** (PubMedArticle) - Associated article metadata.
- **doi_score** (int) - Confidence score for DOI match (0-100).
```

--------------------------------

### GET /entrez/eutils/elink.fcgi

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/medgenfetcher.html

Retrieves a list of PubMed IDs linked to a specific MedGen UID.

```APIDOC
## GET /entrez/eutils/elink.fcgi

### Description
Retrieves linked PubMed article IDs for a given MedGen UID.

### Method
GET

### Endpoint
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/elink.fcgi

### Parameters
#### Query Parameters
- **dbfrom** (string) - Required - The source database (e.g., 'medgen')
- **id** (string) - Required - The MedGen UID
- **db** (string) - Required - The target database (e.g., 'pubmed')

### Response
#### Success Response (200)
- **ids** (list) - A list of PubMed article IDs associated with the provided UID.
```

--------------------------------

### Initialize Formatter

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Initializes the formatter with a format string, date format, and style. The style parameter supports '%', '{', or '$' formatting.

```python
def __init__(self, fmt=None, datefmt=None, style='%', validate=True, *,
             defaults=None):
    """
    Initialize the formatter with specified format strings.

    Initialize the formatter either with the specified format string, or a
    default as described above. Allow for specialized date formatting with
    the optional datefmt argument. If datefmt is omitted, you get an
    ISO8601-like (or RFC 3339-like) format.

    Use a style parameter of '%', '{' or '$' to specify that you want to
    use one of %-formatting, :meth:`str.format` (``{}``) formatting or
    :class:`string.Template` formatting in your format string.

    .. versionchanged:: 3.2
       Added the ``style`` parameter.
    """
    if style not in _STYLES:
        raise ValueError('Style must be one of: %s' % ','.join(
                         _STYLES.keys()))
    self._style = _STYLES[style][0](fmt, defaults=defaults)
    if validate:
        self._style.validate()

    self._fmt = self._style._fmt
    self.datefmt = datefmt
```

--------------------------------

### Main function for metapub CLI

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/convert.html

Handles command-line arguments for metapub, allowing users to convert between DOIs, PMIDs, and Book IDs, and fetch article or work details. Requires the 'docopt' library.

```python
def main():
    if docopt is None:
        raise ImportError("docopt is required to run main()")
    args = docopt(__doc__, version=__version__)

    if args['--quiet']:
        logging.getLogger('metapub.*').setLevel(logging.INFO)

    elif args['--debug']:
        logging.getLogger('metapub.*').setLevel(logging.DEBUG)

    if args['doi2pmid']:
        doi = args['<doi>']
        print('DOI: ', doi)
        pmid = doi2pmid(doi)
        print('PMID: ', pmid)
    elif args['pmid2doi']:
        pmid = args['<pmid>']
        print('PMID: ', pmid)
        doi = pmid2doi(pmid)
        print('DOI: ', doi)
    elif args['bookid2pmid']:
        book_id = args['<book_id>']
        print('BookID: ', book_id)
        pmid = bookid2pmid(book_id)
        print('PMID: ', pmid) 

    print()
    if args['--article']:
        pma = pm_fetch.article_by_pmid(pmid)
        print(pma)

    if args['--work']:
        work = cr_fetch.article_by_doi(doi)
        print(work)
```

--------------------------------

### GET /entrez/eutils/esummary.fcgi

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/medgenfetcher.html

Retrieves a MedGen concept summary based on a specific MedGen UID.

```APIDOC
## GET /entrez/eutils/esummary.fcgi

### Description
Fetches the MedGen concept details for a given unique identifier (UID).

### Method
GET

### Endpoint
https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esummary.fcgi

### Parameters
#### Query Parameters
- **db** (string) - Required - The database to query (e.g., 'medgen')
- **id** (string/int) - Required - The MedGen UID to look up

### Response
#### Success Response (200)
- **result** (MedGenConcept) - The concept object containing details for the requested UID.
```

--------------------------------

### GET doi2pmid

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/convert.html

Retrieves a PMID for a given DOI using CrossRef and PubMed eutils.

```APIDOC
## GET doi2pmid

### Description
Uses CrossRef and PubMed eutils to lookup a PMID given a known DOI. Note that no validation of the input DOI is performed.

### Method
GET

### Parameters
#### Path Parameters
- **doi** (str) - Required - The DOI to convert.

### Response
#### Success Response (200)
- **pmid** (str) - The found PMID, 'AMBIGUOUS' if multiple results are found, or None if no results.
```

--------------------------------

### Fetch Basic Article Information

Source: https://metapub.readthedocs.io/en/latest/pubmedarticle_properties.html

Demonstrates initializing the PubMedFetcher and accessing core article metadata.

```python
from metapub import PubMedFetcher

fetch = PubMedFetcher()
article = fetch.article_by_pmid('23435529')

print(f"Title: {article.title}")
print(f"Journal: {article.journal} ({article.year})")
print(f"Authors: {article.authors_str}")
print(f"DOI: {article.doi}")

# New normalized date access
if article.pubdate:
    print(f"Published: {article.pubdate.strftime('%B %d, %Y')}")

```

--------------------------------

### Configure Caching and NCBI Client

Source: https://metapub.readthedocs.io/en/latest/_sources/advanced.rst.txt

Sets up caching via environment variables or direct NCBIClient instantiation for rate-limited API access.

```python
import os
from metapub import PubMedFetcher
from metapub.ncbi_client import NCBIClient

# Method 1: Environment variables (traditional)
os.environ['METAPUB_CACHE_DIR'] = '/path/to/large/cache'
os.environ['NCBI_API_KEY'] = 'your_api_key_here'

fetch = PubMedFetcher()

# Method 2: Direct NCBIClient usage (new system)
client = NCBIClient(
    api_key='your_api_key_here',
    cache_path='/path/to/cache/ncbi_cache.db',
    requests_per_second=10,  # Will be capped to NCBI limits
    tool='my_research_tool',
    email='researcher@university.edu'
)
```

--------------------------------

### Logger Class Management

Source: https://metapub.readthedocs.io/en/latest/_modules/logging.html

Functions to set and get the logger class used by the logging system.

```APIDOC
## setLoggerClass

### Description
Set the class to be used when instantiating a logger. The class should define __init__() such that only a name argument is required, and the __init__() should call Logger.__init__().

### Method
`setLoggerClass(klass)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
None

## getLoggerClass

### Description
Return the class to be used when instantiating a logger.

### Method
`getLoggerClass()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
- **klass** (type) - The logger class.

### Response Example
None
```

--------------------------------

### GET /doi/resolve

Source: https://metapub.readthedocs.io/en/latest/_modules/metapub/urlreverse/methods.html

Extracts a DOI from a generic article URL and validates it using the DxDOI service.

```APIDOC
## GET /doi/resolve

### Description
Extracts a DOI from a provided URL string, cleans common URL addenda (like /pdf or /full), and verifies the DOI existence via the DxDOI service.

### Method
GET

### Parameters
#### Query Parameters
- **url** (string) - Required - The article URL to extract the DOI from.

### Response
#### Success Response (200)
- **doi** (string) - The resolved DOI string or null if invalid.
```
Tokens:
Raw