Introduction

mirUtils provides quantitation of aligned miRNA sequences based on miRBase annotations. Starting from a miRBase-aligned BAM or SAM file, mirUtils reports counts and quality metrics for several taxonomy levels, including hairpins, hairpin groups and families, mature loci, mature sequences, and genomic clusters as well as providing per-hairpin base coverage and alingment start position details.

Prerequisites

mirUtils requires Perl version 5.8.1 or later in a Linux-like environment. It has not been tested on Windows. In addition, the samtools program is required for reading BAM files.

Installation

mirUtils is a Perl program with two helper modules. The mirUtils bundle also includes all artifacts from miRBase releases v19, v20 and v21 in its mirbase subdirectory.

To install:

  cd /directory/containing/bundle
  gunzip mirUtils-version.tar.gz
  tar -xvf mirUtils-version.tar

This should create an installation directory named mirUtils-version with the mirUtils executable at top level. This installation directory can be moved to any desired location.

Note: The main mirUtils executable should not be moved from its installation directory, as it uses relative paths to access its miRBase aritifacts in the mirbase sub-directory. For easier access, the installation directory can be added to your PATH, or mirUtils can be invoked from a symbolic link.

Quick Start

This section assumes the mirUtils installation directory is named mirUtils-version.

To validate the basic installation and see available mirUtils functions, invoke the executable with no arguments:

  cd /path/to/mirUtils-version
  ./mirUtils

To run mirUtils on a small test data set and see the files produced:

  cd /path/to/mirUtils-version/test
  ../mirUtils mbaseMirStats ./data/mb_test_small.sort.bam

FAQ
How can I incorporate miRBase changes or data from new releases?
There are a couple of possibilities here. One way is to obtain a mirUtils bundle that incorporates the data. Another way is to add newly released data (or replace existing release files) in your current mirUtils installation's mirbase sub-directory, described here.
Can I use a custom GFF annotation file with mirUtils?
Yes. You can create a custom <org>_prefix.gff3 file and add it to an existing (or custom) version directory in the mirUtils installation's mirbase sub-directory, described here. For example: 
 mirbase/
   vCustom21/       (custom version directory)
     miFam.dat      (customized or copied)
     hairpin.dat    (copied)
     mature.dat     (copied)
     genomes/     
       my_hsa.gff3  (customized hsa annotations)
Note that the customized org_prefix.gff3 file must follow miRBase GFF3 conventions. Once the custom file is in place, running the mirUtils mbaseMirInfo function on the file can help identify inconsistencies. For example: 
 /path/to/mirUtils mbaseMirStats --version=vCustom21 my_hsa
Can I run mirUtils on a BAM/SAM file aligned to a genomic reference such as hg19?
No, not in the current version of mirUtils, which requires a miRBase-aligned BAM/SAM. Using mirUtils with a genome-aligned BAM/SAM may be supported in a future release.