biocode: a shared shelf of bioinformatics scripts and modules

Why a shared collection of small scripts exists

biocode is a collection of bioinformatics scripts that its author and colleagues found useful, together with code modules that make writing new ones faster. The primary language is Python, and the licence is MIT.

The readme explains the motivation with a complaint most working bioinformaticians will recognise. Over the years most bioinformatics people amass a collection of small utility scripts that make their lives easier, and too often they are kept either in private repositories or as part of a public collection to which nobody else can contribute. biocode is the curated repository of general use utility scripts, shared on the assumption that other people will want the same thing.

The scope is deliberately open. The author says he wants to include anything that developers find generally useful, and there are no limitations on language choice, though the majority are Python. What is grouped where is left to judgement, with the instruction that the general directory should be used selectively and that a new directory should be created when one is warranted.

That makes the repository a working reference implementation of how a small group runs bioinformatics, rather than a product with a specification. The directory names are the taxonomy of the field, and they are the fastest way to see what is there.

The script directories, and the sandbox for half finished work

The initial groupings are listed with a one line rule each, and the rules are more useful than the names.

Anything that uses, massages or reformats BLAST output goes in blast. Scripts tied into the chado schema from gmod.org go in chado. fasta holds filtering, converting and size distribution plots, and fastq holds the utilities for fasta's newer sister format. genbank is for the GenBank flat file format. gff covers extractions, conversions and manipulations of files in the Generic Feature Format, and gtf is focused on the GTF format as it comes from Ensembl and WashU. hmm is for merging, manipulating or reading HMM libraries, sam_bam for analysis and parsing of SAM and BAM files, and taxonomy for anything related to taxonomic analysis.

Two of the directories are about the project rather than about biology. The general directory holds utility scripts that fit nowhere else, and the readme says the collection should be selective about what goes there. The sandbox gives each committer their own personal directory to add anything they want while testing or waiting for it to be moved into the production directories.

That sandbox is a good design decision, and it is also a signal about how the project works. A contribution does not arrive ready: it lives in a per-contributor directory until somebody moves it. The sysadmin directory is an admission that this is a working environment, since the readme says the work tends to happen on Unix machines and utility scripts are often needed to support it, from file system manipulation to database backup scripts.

So the repository is a mixture of genomics code and the operational scripts that keep a genomics group's machines running, and both are indexed in the same tree.

biocode.things models genes the way biologists talk about them

The three primary Python modules are where the real reuse is, and the readme is clear that some of it duplicates functionality in other libraries while offering something different in exchange.

biocode.things contains classes that represent biological things, as defined by the Sequence Ontology, in a way that makes more sense biologically while hiding some of the computer science abstraction. The example the readme gives is a comparison of two styles of access to the same data.

    # This way is typical of other libraries
    genes = assembly.get_subfeatures_by_type( 'type': 'genes' )
    mRNAs = assembly.get_subfeatures_by_type( 'type': 'mRNA' )

    # And instead, in biothings:
    genes = assembly.genes()
    for gene in genes:
        mRNAs = gene.mRNAs()

The difference is that the second version names the thing you want rather than a type string, and the objects returned know what they are. The readme says this more direct approach is held throughout the libraries.

The second half of the module is about coordinates, which is where the abstraction usually leaks. You can ask whether one gene is before another on a molecule with a plain comparison, and in the background biocode checks whether the two gene objects are located on the same molecule and, if so, compares their coordinates. The same class of operation is offered in several forms: one thing overlapping another on the five prime end, one contained within another, one overlapping another, and an overlap size with another.

The readme also points at the source code for what it calls readable and detailed documentation within, which is a fair way to describe a module whose API is expressed as methods on biological objects rather than as a documented function list.

biocode.gff and biocode.annotation: reading and writing the formats

The gff module is the practical entry point, and the readme is candid that much of biocode was written while working with genomic data and annotation.

GFF3 is one of the common formats for storing that, and the module parses a GFF3 file of annotations into a set of biothings with a single line of code.

    import biocode.gff

    (assemblies, features) = biocode.gff.get_gff3_features( input_file_path )

That is the whole call, and what comes back is a pair: the assemblies, which you can iterate over along with their children, and a features dictionary keyed on each feature's identifier. The second element matters more than it looks, because a keyed dictionary is what you want the moment the file is larger than you can hold in your head, and it means the same identifier can be resolved later without rescanning the file.

The annotation module covers the other direction. It provides classes for the formal definition of functional annotation, which can be attached to the biothings from the other modules, and the things it covers are gene product names, gene symbols, EC numbers and GO terms among others. Once a thing is annotated, the biothings can be written out in common formats such as GFF3, GenBank and NCBI tbl.

So the two modules are halves of one workflow. The gff module reads an annotation file into objects, the annotation module attaches meaning to those objects, and the write out functions serialise the result into the formats other tools expect. That round trip is the thing that is tedious to write for yourself, and it is what the modules are for.

Installing: system packages, a Docker image, pip, or a checkout

There are four documented ways to get the code, and the readme covers the dependency situation in each case.

On Debian based systems the readme says you can be sure to get all the dependencies like this.

   apt-get install -y python3 python3-pip zlib1g-dev libblas-dev liblapack-dev libxml2-dev

The list shows what the modules reach for: zlib for compression, BLAS and LAPACK for the linear algebra that the numeric libraries need, and libxml2 for XML parsing, which is what reading GFF3 and writing GenBank requires.

Each release is also available as a Docker image on Docker Hub, at the jorvis/biocode repository. That is the shortest route to a reproducible environment, and it is the one that avoids the system library problem entirely.

For the latest release, pip3 is enough.

    pip3 install biocode

And for the current trunk, the repository is cloned, and then there is an important extra step.

    cd /opt
    git clone https://github.com/jorvis/biocode.git

    # You probably want to add this line to your $HOME/.bashrc file
    export PYTHONPATH=/opt/biocode/lib:$PYTHONPATH

The readme marks this as important, and explains why. Many of the scripts use the modules in the biocode/lib directory, so you need to point Python at them, and the suggested line prepends the lib directory to the PYTHONPATH, with the comment that you probably want to add it to your shell profile.

That step is the price of running from a checkout, and it is why the pip or Docker routes are the ones to prefer for anything you intend to keep.

Where biocode is the wrong tool

Four limits, and the first is the one the project itself admits.

The readme says plainly that there is some duplicate functionality you will find in modules like Biopython, and explains the reason it exists: these were written to add features the author always wanted, with a more biologically focused API. That is a reasonable reason for a module to exist, and it is also an admission that you are choosing between two implementations of overlapping ideas, and the ecosystem one is better maintained.

The second is the shape of the collection. This is a directory of scripts with a shared library underneath, not a package with a stable public API. The scripts are grouped by format, there is a per-contributor sandbox for work in progress, and the top level includes a script template in both Python and Perl along with a requirements and convention guide, which is what a curated collection looks like and not what a library looks like. There is no per-script version, no dependency pinning and no guarantee that a script you rely on today still runs next year.

The third is the system dependency footprint. The Debian install pulls in BLAS, LAPACK, zlib and libxml2, and the pip install of the latest release assumes those are present. A team that wants a container for everything has to build one, and a team that wants a minimal environment has to work out which of the numeric libraries its particular use actually needs.

The fourth is the release rhythm. The versions are v0.11.0 in November 2023, v0.12.0 in October 2024 and v0.12.1 in July 2025, and the last push to the repository was on 2026-07-10. The code is being worked on, but the published versions move rarely, so a deployment pinned to a release is pinned to code that is over a year old.

Conventions, templates and the state of the repository

The top level of the repository is a good summary of what this project is.

There is a lib directory holding the Python modules, and one directory per format for the scripts. There is a build directory, a data directory and a tests directory, and there are script templates in both Python and Perl, which tell you that a script is expected to arrive in a particular shape. There is a RequirementsAndConventionGuide.md, and a CHANGELOG.rst, and a LICENSE.

The convention guide is the file to read first if you intend to contribute or to rely on a script. A collection like this only works if the entries look alike, and the existence of a guide plus two template files says the author was trying to hold that line without enforcing it through tooling.

The licence is MIT, so the code can be used, modified and redistributed with the notice kept, and this is not legal advice. The author is Joshua Orvis, and the repository has no separate homepage, so the readme and the issue tracker are the documentation.

For maintenance, the position is mixed in a way that is easy to misread. Commits continue, with the last push on 2026-07-10, and the repository is not archived, so the project is not dead. But the published versions are sparse, one release in 2023, one in 2024 and one in 2025, and each of them is a zero minor version of a zero major version. For a project whose value is the scripts, the practical question is which ones still work against current versions of BLAST, samtools and the rest, and the honest answer is that the readme does not tell you and the issue tracker is where you find out.

Editorial conclusion

biocode is the right place to look for a BLAST output reformatting script, a GFF3 parser that returns biological objects rather than rows, or a starting point for the format handling that every genomics group rewrites for itself, and the Python modules are the more valuable half of the collection. It is the wrong choice for a modern project that would rather depend on maintained packages, since some of its functionality overlaps with Biopython and its installation from source depends on a PYTHONPATH pointing at the lib directory. Before using it, check whether a released version covers what you need, read the RequirementsAndConventionGuide.md for the conventions the scripts assume, and confirm that the system libraries the dependency install asks for are present on your machines.

Frequently asked questions

Official sources

1. Issues
2. jorvis/biocode on GitHub
3. License: MIT
4. README
5. Releases