omnilab / ncbi

1.x-dev 2026-10-15 01:38 UTC

Requires

• php: >=8.2
• glitchr/omnilab: ^1.0@dev
• symfony/http-client: ^6.4|^7.0|^8.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• Marco Meyer

• taxonomy
• science
• ncbi
• biology
• gene
• omnilab
• entrez

Published on Packagist.org on 2026-10-15 01:55 UTC

README

NCBI Gene and NCBI Taxonomy for glitchr/omnilab: a gene by its GeneID - its symbol, name, type, organism, chromosome, cytogenetic and genomic locations, summary, and its UniProt and Ensembl ids for the Collector to follow - and a taxon by its id or a name - its scientific name, rank, common name, basionym, lineage by rank, and its GBIF key; Entrez's search of either. Through NCBI Datasets v2 for the records and E-utilities for the search, no key (an API key for ten calls a second).

$ncbi = (new NcbiSourceFactory($http))->create(['mailto' => '[e-mail]']);
$hbb = $ncbi->entity('3043');                    // or 'gene:3043', Identifier::of(Scheme::NCBI_GENE, '3043')
$hbb->label;                                     // HBB
$hbb->value('gene_name');                        // hemoglobin subunit beta
$hbb->value('map_location');                     // 11p15.4
$hbb->identifier(Scheme::UNIPROT);               // P68871
$lion = $ncbi->entity('txid9689');               // or 'taxonomy:9689', 'Panthera leo', 'lion'
$lion->value('lineage');                         // Eukaryota > Metazoa > Chordata > Mammalia > Carnivora > Felidae > Panthera
$lion->identifier(Scheme::GBIF);                 // 5219404
$ncbi->search(new Query('HBB AND human[orgn]', limit: 10));
$ncbi->search(new Query('Panthera[subtree]', Domain::TAXONOMY));

omnilab:
    sources:
        ncbi:
            factory: ncbi
            options:
                mailto: '[e-mail]'   # E-utilities' "email" and the User-Agent: whom NCBI writes to before it blocks a caller
                api_key: '%env(NCBI_API_KEY)%' # optional: ten calls a second instead of three
                links: true                    # read a taxon's external links (one call more): its GBIF key

With UniProt and Wikidata configured too, the Collector follows a protein to its gene, and NCBI's gene gives the UniProt accession back; with GBIF, a species reaches NCBI Taxonomy by the NCBI id GBIF keeps for it.

Terms of use

NCBI asks every client of E-utilities to send tool and email (the source sends omnilab and the mailto option) and allows three calls a second without a key, ten with one; NCBI Datasets allows five, ten with a key (its answers say so in X-RateLimit-Limit). The source leaves 0.34 s between two calls without a key, 0.1 s with one (throttle: auto). An address that calls faster is refused, and an address NCBI blocks is served again once its tool and email are registered with NCBI. NCBI places no restriction on the use of its data, though submitters may hold rights on theirs: see NCBI's policies.

See docs/ for what is read, how it maps, and what NCBI does not give here.

License: MIT.