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.

Clojure CLI/deps.edn:

cljam {:mvn/version "0.8.5"}

Leiningen/Boot:

[cljam "0.8.5"]

Breaking changes in 0.8.0

• cljam.io.tabix is rewritten. #180
• cljam.io.bam-index.writer/pos->lidx-offset is moved to cljam.io.util.bin/pos->lidx-offset. #180
• cljam.io.sam.util/reg->bin is moved to cljam.io.util.bin/reg->bin. Also, a coordinate system of its argument is changed from 0-based half-open to 1-based fully-closed. #190

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.

NOTICE The command-line tool functionality will be removed from cljam on the next release. The functionality has been already integrated into Gnife, which is a pure command-line tool.

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)
• Shogo Ohta (@athos)
• Shunya Kawabata (@r6eve)
• Yuji Ito (@yito88)
• Akira Inoue (@niyarin)
• Atsushi Kitahara (@xckitahara)
• Kei Komazaki (@k-kom)
• Tomoki Matsuda (@matsutomo81)
• Ryutaro Nagata (@nuggetoriniku)

License

Copyright 2013-2024 Xcoo, Inc.

Licensed under the Apache License, Version 2.0.