README.md

cljam

A DNA Sequence Alignment/Map (SAM) library for Clojure. [API Reference] [Annotated Source]

Installation

cljam is available as a Maven artifact from Clojars.

To use with Leiningen/Boot, add the following dependency.

[cljam "0.5.1"]

To use with Maven, add the following dependency.

<dependency>
  <groupId>cljam</groupId>
  <artifactId>cljam</artifactId>
  <version>0.5.1</version>
</dependency>

Breaking changes in 0.5.0

• :ignore-index option of cljam.io.sam/bam-reader and cljam.io.sequence/fasta-reader is removed.
• :depth option of cljam.io.sam/read-alignments is removed. It returns SAMAlignment only.
• SAM/BAM reading functions return Eduction instances instead of lazy sequences.

Getting started

To read a SAM/BAM format file,

(require '[cljam.io.sam :as sam])

;; Open a file
(with-open [r (sam/reader "path/to/file.bam")]
  ;; Retrieve header
  (sam/read-header r)
  ;; Retrieve alignments
  (doall (take 5 (sam/read-alignments r))))

To create a sorted file,

(require '[cljam.io.sam :as sam]
         '[cljam.algo.sorter :as sorter])

(with-open [r (sam/reader "path/to/file.bam")
            w (sam/writer "path/to/sorted.bam")]
  ;; Sort by chromosomal coordinates
  (sorter/sort-by-pos r w))

To create a BAM index file,

(require '[cljam.algo.bam-indexer :as bai])

;; Create a new BAM index file
(bai/create-index "path/to/sorted.bam" "path/to/sorted.bam.bai")

To calculate coverage depth for a BAM file,

(require '[cljam.io.sam :as sam]
         '[cljam.algo.depth :as depth])

(with-open [r (sam/reader "path/to/sorted.bam")]
  ;; Pileup "chr1" alignments
  (depth/depth r {:chr "chr1", :start 1, :end 10}))
;;=> (0 0 0 0 0 0 1 1 3 3)

If you are Clojure beginner, read Getting Started for Clojure Beginners.

Command-line tool

cljam provides a command-line tool to use the features easily.

Executable installation

lein bin creates standalone console executable into target directory.

$ lein bin
Creating standalone executable: /path/to/cljam/target/cljam

Copy the executable cljam somewhere in your $PATH.

Usage

All commands are displayed by cljam -h, and detailed help for each command are displayed by cljam [cmd] -h.

$ cljam view -h

For example, to display contents of a SAM file including the header,

$ cljam view --header path/to/file.sam

See command-line tool manual for more information.

Development

Test

To run tests,

• lein test for basic tests,
• lein test :slow for slow tests with local resources,
• lein test :remote for tests with remote resources.

To get coverage

$ lein cloverage

And open target/coverage/index.html.

Generating document

cljam uses Codox for API reference and Marginalia for annotated source code.

$ lein docs

generates these documents in target/docs and target/literate directories.

Citing cljam

T. Takeuchi, A. Yamada, T. Aoki, and K. Nishimura. cljam: a library for handling DNA sequence alignment/map (SAM) with parallel processing. Source Code for Biology and Medicine, Vol. 11, No. 1, pp. 1-4, 2016.

Contributors

Sorted by first commit.

• Toshiki Takeuchi (@totakke)
• Takashi Aoki (@federkasten)
• Atsuo Yamada (@ayamada)
• Jun Imura (@alumi)

License

Copyright 2013-2017 Xcoo, Inc.

Licensed under the Apache License, Version 2.0.