.. image:: https://raw.githubusercontent.com/cokelaer/bioservices/main/doc/_static/bioservices2_logo_256.png :target: https://raw.githubusercontent.com/cokelaer/bioservices/main/doc/_static/bioservices2_logo_256.png ################################################################################# BIOSERVICES: access to biological web services programmatically ################################################################################# .. image:: https://badge.fury.io/py/bioservices.svg :target: https://pypi.python.org/pypi/bioservices .. image:: https://github.com/cokelaer/bioservices/actions/workflows/ci.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/ci.yml .. image:: http://readthedocs.org/projects/bioservices/badge/?version=main :target: http://bioservices.readthedocs.org/en/main/?badge=main :alt: Documentation Status .. image:: https://static.pepy.tech/personalized-badge/bioservices?period=month&units=international_system&left_color=black&right_color=orange&left_text=Downloads :target: https://pepy.tech/project/bioservices .. image:: https://anaconda.org/conda-forge/bioservices/badges/version.svg :target: https://anaconda.org/conda-forge/bioservices |Codacy-Grade| :Python_version_available: BioServices is tested for Python 3.9, 3.10, 3.11, 3.12 :Contributions: Please join https://github.com/cokelaer/bioservices :Issues: Please use https://github.com/cokelaer/bioservices/issues :How to cite: Cokelaer et al. *BioServices: a common Python package to access biological Web Services programmatically* `Bioinformatics `_ (2013) 29 (24): 3241-3242 :Documentation: `RTD documentation `_. **Bioservices** is a Python package that provides access to many Bioinformatics Web Services (e.g., UniProt) and a framework to easily implement Web Services wrappers (based on WSDL/SOAP or REST protocols). The primary goal of **BioServices** is to use Python as a glue language to provide a programmatic access to several Bioinformatics Web Services. By doing so, elaboration of new applications that combine several of the wrapped Web Services is fostered. One of the main philosophies of **BioServices** is to make use of the existing biological databases (not to re-invent new databases) and to alleviate the need for expertise in Web Services for developers and users. BioServices provides access to about 40 Web Services. Installation ============ Install the latest stable release from `PyPI `__:: pip install bioservices or from `conda-forge `_:: conda install conda-forge::bioservices Contributors ============ Maintaining BioServices would not have been possible without users and contributors. Each contribution has been an encouragement to pursue this project. Thanks to all: .. image:: https://contrib.rocks/image?repo=cokelaer/bioservices :target: https://github.com/cokelaer/bioservices/graphs/contributors Quick example ============= Here is a small example using the UniProt Web Service to search for the zap70 specy in human organism:: >>> from bioservices import UniProt >>> u = UniProt(verbose=False) >>> data = u.search("zap70+and+taxonomy_id:9606", frmt="tsv", limit=3, ... columns="id,length,accession, gene_names") >>> print(data) Entry name Length Entry Gene names ZAP70_HUMAN 619 P43403 ZAP70 SRK B4E0E2_HUMAN 185 B4E0E2 RHOH_HUMAN 191 Q15669 RHOH ARHH TTF .. note:: major changes of UniProt API changed all columns names in June 2022. The code above is valid for bioservices versions >1.10. Earlier version used:: >>> data = u.search("zap70+and+taxonomy:9606", frmt="tab", limit=3, ... columns="entry name,length,id, genes") Note that columns names have changed, the frmt was changed from tab to tsv and taxonomy is now taxonomy_id. Names correspondences can be found in:: u._legacy_names More examples and tutorials are available in the `On-line documentation `_ Command-Line Interface ====================== BioServices also ships a ``bioservices`` command-line tool for quick lookups without writing any Python code:: $ bioservices --help Four top-level commands are available: * **gene** — query gene data (info, name, ontology, expression, pathway, ortholog, id mapping) * **protein** — query protein data (search, sequence, structure, annotation, interaction, id mapping) * **taxonomy** — retrieve taxonomic information for a taxon ID * **download-accession** — download FASTA (and optionally GFF3/GenBank) for a sequence accession Examples:: $ bioservices gene info --gene-id 1017 $ bioservices gene name --symbol BRAF $ bioservices protein search --query ZAP70 --organism human $ bioservices protein structure --uniprot-id P43403 $ bioservices taxonomy --id 9606 $ bioservices download-accession --accession FN433596.1 Full CLI reference: `CLI documentation `_ Notebooks ========= The following Jupyter notebooks provide worked examples for many of the services. They can be viewed directly on `nbviewer `_ or downloaded and run locally. .. list-table:: :header-rows: 1 :widths: 30 70 * - Notebook - Description * - `Overview `_ - Introduction and overview of BioServices * - `UniProt `_ - Searching and retrieving data from UniProt * - `BioModels `_ - Accessing BioModels database * - `ChEMBL `_ - Drug and compound data from ChEMBL * - `Entrez/EUtils `_ - NCBI Entrez utilities cookbook (ESearch, EFetch, EPost, ELink) * - `EUtils `_ - EUtils quick example (ESummary and ESearch) * - `KEGG `_ - KEGG pathways and databases * - `MUSCLE `_ - Multiple sequence alignment with MUSCLE * - `NCBIBlast `_ - Running BLAST searches via NCBI * - `WikiPathway `_ - WikiPathways data access * - `Gene Mapping `_ - Mapping gene identifiers across databases * - `BioMart `_ - Querying BioMart data warehouses * - `Ensembl `_ - Ensembl genome browser REST API * - `InterPro `_ - Protein families and domains from InterPro * - `ENA `_ - European Nucleotide Archive * - `Drug Discovery Pipeline `_ - Integrated multi-service drug discovery workflow Current services ================ Here is the list of services available and their testing status. ==================== ================================================================================================ Service CI testing ==================== ================================================================================================ arrayexpress .. image:: https://github.com/cokelaer/bioservices/actions/workflows/arrayexpress.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/arrayexpress.yml bigg .. image:: https://github.com/cokelaer/bioservices/actions/workflows/bigg.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/bigg.yml biocontainers .. image:: https://github.com/cokelaer/bioservices/actions/workflows/biocontainers.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/biocontainers.yml biodbnet .. image:: https://github.com/cokelaer/bioservices/actions/workflows/biodbnet.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/biodbnet.yml biomart .. image:: https://github.com/cokelaer/bioservices/actions/workflows/biomart.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/biomart.yml biomodels .. image:: https://github.com/cokelaer/bioservices/actions/workflows/biomodels.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/biomodels.yml chebi .. image:: https://github.com/cokelaer/bioservices/actions/workflows/chebi.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/chebi.yml chembl .. image:: https://github.com/cokelaer/bioservices/actions/workflows/chembl.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/chembl.yml cog .. image:: https://github.com/cokelaer/bioservices/actions/workflows/cog.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/cog.yml dbfetch .. image:: https://github.com/cokelaer/bioservices/actions/workflows/dbfetch.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/dbfetch.yml ena .. image:: https://github.com/cokelaer/bioservices/actions/workflows/ena.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/ena.yml ensembl .. image:: https://github.com/cokelaer/bioservices/actions/workflows/ensembl.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/ensembl.yml eutils .. image:: https://github.com/cokelaer/bioservices/actions/workflows/eutils.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/eutils.yml eva .. image:: https://github.com/cokelaer/bioservices/actions/workflows/eva.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/eva.yml hgnc .. image:: https://github.com/cokelaer/bioservices/actions/workflows/hgnc.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/hgnc.yml intact_complex .. image:: https://github.com/cokelaer/bioservices/actions/workflows/intact_complex.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/intact_complex.yml kegg .. image:: https://github.com/cokelaer/bioservices/actions/workflows/kegg.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/kegg.yml muscle .. image:: https://github.com/cokelaer/bioservices/actions/workflows/muscle.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/muscle.yml mygeneinfo .. image:: https://github.com/cokelaer/bioservices/actions/workflows/mygeneinfo.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/mygeneinfo.yml ncbiblast .. image:: https://github.com/cokelaer/bioservices/actions/workflows/ncbiblast.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/ncbiblast.yml ncbiblastapi .. image:: https://github.com/cokelaer/bioservices/actions/workflows/ncbiblastapi.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/ncbiblastapi.yml omicsdi .. image:: https://github.com/cokelaer/bioservices/actions/workflows/omicsdi.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/omicsdi.yml omnipath .. image:: https://github.com/cokelaer/bioservices/actions/workflows/omnipath.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/omnipath.yml panther .. image:: https://github.com/cokelaer/bioservices/actions/workflows/panther.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/panther.yml pathwaycommons .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pathwaycommons.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pathwaycommons.yml pdb .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pdb.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pdb.yml pdbe .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pdbe.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pdbe.yml pfam .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pfam.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pfam.yml pride .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pride.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pride.yml pubchem .. image:: https://github.com/cokelaer/bioservices/actions/workflows/pubchem.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/pubchem.yml quickgo .. image:: https://github.com/cokelaer/bioservices/actions/workflows/quickgo.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/quickgo.yml reactome .. image:: https://github.com/cokelaer/bioservices/actions/workflows/reactome.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/reactome.yml rhea .. image:: https://github.com/cokelaer/bioservices/actions/workflows/rhea.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/rhea.yml seqret .. image:: https://github.com/cokelaer/bioservices/actions/workflows/seqret.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/seqret.yml unichem .. image:: https://github.com/cokelaer/bioservices/actions/workflows/unichem.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/unichem.yml uniprot .. image:: https://github.com/cokelaer/bioservices/actions/workflows/uniprot.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/uniprot.yml wikipathway .. image:: https://github.com/cokelaer/bioservices/actions/workflows/wikipathway.yml/badge.svg :target: https://github.com/cokelaer/bioservices/actions/workflows/wikipathway.yml ==================== ================================================================================================ .. note:: Contributions to implement new wrappers are more than welcome. See `BioServices github page `_ to join the development, and the Developer guide on how to implement new wrappers. Bioservices command ==================== In version 1.8.2, we included a bioservices command. For now it has only one subcommand to download a NCBI accession number and possibly it genbank or GFF file (if available):: bioservices download-accession --accession K01711.1 --with-gbk Changelog ========= ========= ==================================================================== Version Description ========= ==================================================================== 1.16.0 * **New** ``ncbiblastapi`` module: wraps NCBI's own BLAST URL API, submitting jobs directly to NCBI (``blastn``, ``blastp``, ``blastx``, ``tblastn``, ``tblastx``) with support for NCBI databases (``nt``, ``nr``, ``refseq_genomic``, …) and optional API key for higher rate limits 1.15.0 * **Drop WSDL support**: ``WSDLService`` class and ``suds-community`` dependency removed — all active services now use REST exclusively * **New** ``HTTPResponseError`` type: HTTP errors are now returned as a rich object that behaves like ``int`` for backwards compatibility but raises a descriptive ``BioServicesError`` when mistakenly used as a dict or sequence (replaces silent ``TypeError`` crashes) * **New** ``BioServicesError`` exception exported from ``bioservices.services`` and usable directly: ``from bioservices import BioServicesError`` * Remove obsolete ``_compat`` module (Python 2 shims); replace ``pkg_resources`` with ``importlib.metadata`` * Code quality: replaced ``assert`` statements in production code with ``ValueError``/``TypeError``; fixed bare ``except:`` clauses, unused imports, and undefined name bugs across 15+ modules * Test quality: replaced ``try/assert False/except/assert True`` anti-patterns with ``pytest.raises``; intermittent tests marked ``flaky`` or ``xfail``; slow tests given per-test timeout overrides * Bug fixes: ``reactome.py`` SVG save path, ``pathwaycommons.py`` ``isinstance`` typo, ``settings.py`` loop variable, ``ensembl.py`` ``NotImplementedError`` typo, ``wikipathway.py`` API response handling * Documentation overhauled: new Quick Start, merged changelog, contributors folded into Help & Credits, ChangeLog page removed 1.14.0 * New ``proteins`` module (EBI Proteins API) * New ``string`` module (STRING protein interaction database) * New ``geo`` module (NCBI Gene Expression Omnibus) * PubChem: update to current PUG REST API * Remove deprecated BioGRID and PSICQUIC services 1.13.0 * ChEBI: new REST API (replacing SOAP) 1.12.2 * Add ``taxonomy`` CLI subcommand (via EUtils) 1.11.0 * Remove ReactomeOld, ReactomeAnalysis, rnaseq_ebi (deprecated) 1.10.3 * PDB: update to v2 API; remove biocarta (website no longer accessible) 1.10.1 * PRIDE: update to new API (July 2022) 1.10.0 * UniProt: update to new API (June 2022) 1.9.0 * UniChem: update to new API 1.8.3 * New ``biocontainers`` module 1.8.0 * Remove chemspider, clinvitae, picr (deprecated) * Add standalone ``bioservices`` CLI application 1.7.12 * New ``cog`` module * Deprecate PICR and TCGA modules * PDB, ChEMBL, QuickGO, BioDBNet: new API 1.7.5 * New ``mygeneinfo``, ``pdbe`` modules 1.7.4 * New ``bigg`` module (BiGG models) * BioModels: new REST API (replacing WSDL) * Move miriam to attic (deprecated) 1.7.0 * New ``panther`` module 1.6.0 * ChEMBL: fully rewritten to new API 1.5.2 * Reactome: new API 1.5.0 * BioDBNet, WikiPathways: migrate from WSDL to REST * QuickGO, DBFetch: new API * Rename ``readseq`` to ``seqret`` (new API) 1.4.8 * New ``omnipath`` module 1.4.6 * New ``rnaseq_ebi`` module 1.4.4 * New ``ena`` module 1.4.1 * HGNC: replaced deprecated module with genenames.org service 1.4.0 * EUtils: migrate from WSDL to REST * Remove apps/taxonomy (moved to biokit) 1.3.5 * New ``intact`` module (Intact Complex) 1.3.4 * New ``pride`` module 1.3.3 * New ``ensembl``, ``clinvitae`` modules 1.3.1 * New ``readseq`` module 1.3.0 * New REST class using ``requests`` (replacing urllib2) * New ``eutils`` module * Rename ``chembldb`` to ``chembl``; rename ``WikiPathway`` to ``WikiPathways`` 1.2.3 * New ``biodbnet``, ``pathwaycommons`` modules 1.2.0 * New ``muscle``, ``geneprof`` modules 1.1.2 * New ``biocarta``, ``pfam`` modules 1.1.1 * New ``hgnc`` module 1.1.0 * New ``chebi``, ``unichem`` modules 1.0.4 * New ``pdb`` module (draft) 1.0.0 * First stable release 0.9.0 * Initial services: BioModels, KEGG, Reactome, ChEMBL, PICR, QuickGO, Rhea, UniProt, WSDbfetch, NCBIblast, PSICQUIC, WikiPathways ========= ==================================================================== .. |Codacy-Grade| image:: https://app.codacy.com/project/badge/Grade/9b8355ff642f4de9acd4b270f8d14d10 :target: https://app.codacy.com/gh/cokelaer/bioservices/dashboard