BioPerl

BioPerl is an open-source collection of Perl tools designed for computational molecular biology. It provides core biological data structures and interfaces, including:

• Biological Sequence Classes: Objects representing sequences.
• Format Readers: Tools to read multiple biological file formats.
• Sequence Alignments: Support for alignment data.
• Database Searching: Objects for interacting with biological databases.
• Program Interfaces: Wrappers for external tools like EMBOSS, ClustalW, and BLAST.

Note that this repository contains the core BioPerl distribution only. Other specialized BioPerl distributions reside in separate repositories.

The bioperl-live repository is organized into the following functional directories:

• lib/: Contains the core BioPerl modules.
• examples/: Scripts demonstrating various BioPerl use cases.
• scripts/: Production-quality scripts accompanied by POD documentation.
• t/: Perl built-in tests, organized into subdirectories by the classes they test.
• t/data/: Data files used for running tests.
• travis_scripts/: Scripts used for Travis CI customization.

BioPerl follows semantic versioning (MAJOR.MINOR.PATCH):

• MAJOR: Incompatible API changes.
• MINOR: New backwards-compatible functionality.
• PATCH: Backwards-compatible bug fixes.

Release History Context

• 1.7+ releases: The project transitioned from a single large distribution to multiple specialized distributions.
• Pre-1.7 releases:
  • Even numbers (e.g., 1.4) were stable, well-tested releases.
  • Odd numbers (e.g., 1.3) were development releases for testing new features.
  • Point/Patch releases (e.g., 1.2.1) indicate bug fixes.

BioPerl uses Dist::Zilla for release authoring. To work with development sources, you must have Dist::Zilla and Dist::Zilla::PluginBundle::BioPerl (along with its dependencies) installed. You can run tests and install the development version using the following commands:

dzil test
dzil install

You can find documentation and usage examples for BioPerl through several channels:

• Module Documentation: Individual module documentation is written in POD (Perl Documentation) and is available online via metacpan.
• Code Examples: Practical usage examples are located within the examples/ and bin/ directories of the repository.
• Project Website: General information is available at bioperl.org.

BioPerl is composed of many individual modules. Instead of installing a single monolithic package, you should identify the specific modules your code requires (the modules you use in your scripts) and install them individually.

To install a specific module using cpanm, use the following command pattern:

cpanm Bio::DB::EUtilities

While the --msa flag can be used explicitly, bp_sreformat attempts to automatically detect if the data is a Multiple Sequence Alignment (MSA) if the input or output format matches standard MSA names.

Detected MSA formats include: nexus, phylip, clustal, maf, stockholm, bl2seq, and msf.

When using bp_find-blast-matches.pl, observe the following logic constraints to avoid errors:

• Match Selection: You cannot use -n (number of hits) and -o (exact match index) at the same time.
• 5' Region Extraction: You cannot use -p (5' region included with sequence) and -5 (5' region only) at the same time.
• Flanking Regions: You cannot use -3 (3' region only) in conjunction with either -p or -5.
• Value Types: All numeric arguments (e.g., -e, -p, -n, -o, -5, -3) must be positive numbers.

Adding New Databases

bp_fetch.pl is a wrapper around BioPerl modules implementing the Bio::DB::BioSeqI interface. To add a new database type, implement a module that adheres to this interface. For flat file indexers, it is recommended to extend Bio::Index::Abstract (similar to Bio::Index::Fasta).

Adding New Output Formats

To support a new output format, implement a new SeqIO module. A good starting point is to extend Bio::SeqIO::Fasta.

BioPerl uses two primary base classes to manage interfaces and concrete objects:

1. Bio::Root::RootI: Use this as the base class for any module specifying an interface. It provides the throw_not_implemented() method, which throws a Bio::Root::NotImplemented exception. This is useful for enforcing that implementing classes provide required methods.
2. Bio::Root::Root: Use this as the base class for any module specifying a concrete object. It implements RootI and provides integration with Error.pm if available.

The tool applies different ID naming logic based on the type of feature being extracted:

• For gene or CDS features: The tool attempts to use the gene tag or the label tag to set the sequence ID. If neither is present, it uses the default spliced sequence ID.
• For all other feature types: The ID is constructed using the pattern {parent_sequence_id}_{feature_type}_{incrementing_count} (e.g., Seq1_exon_1).