Dart Scheme Functions

From Biowiki
Jump to: navigation, search

Functions of the DART Scheme interpreter

Natively implemented functions of the Dart Scheme interpreter, darts.

These functions are only available from within Scheme, so they require that dart was compiled on a system with GNU Guile (see Building Dart).

Small objects (smobs)

Certain commonly-encountered bioinformatics objects, serializable via standard file formats and implemented as C++ classes within XRATE, are exposed using Guile's "small object" (smob) mechanism. Currently, these types include Newick format trees and Stockholm format alignments. API calls are provided to construct these "smobs" by parsing strings (or files) in the appropriate format. The smobs may then be passed directly as parameters to XRATE API calls, or may be "unpacked" into Scheme data structures for individual element access. Guile encourages sparing use of smobs; consequently, smobs are used exclusively to implement bioinformatic objects that already have a broadly-used file format (Stockholm format alignments and Newick format trees). In contrast, formats that are newly-introduced by dart (xrate format grammars, alphabets and so forth) are all based on S-expressions, and so may be represented directly as native Scheme data structures.

Built-in functions

Logging and miscellaneous

(dart-log x)

Logging directive; equivalent to -log x at the command line

Newick trees

(newick-from-string x)

Create a tree-smob from a Newick format string x

(newick-from-file x)

Create a tree-smob from a file x

(newick-from-stockholm x)

Create a tree-smob from the tree encoded within alignment-smob x

(newick-to-file x y)

Write tree-smob x to file y in Newick format

(newick-ancestor-list x)

List of all ancestors in the tree-smob x

(newick-leaf-list x)

List of all leaves in the tree-smob x

(newick-branch-list x)

List of all branches in the tree-smob x

(newick-unpack x)

Converts a tree-smob x into a Scheme data structure

(write x)

Converts a tree-smob x into a Newick format string

Stockholm alignments

(stockholm-from-string x)

Create an alignment-smob from a Stockholm format string x

(stockholm-from-file x)

Create an alignment-smob from a Stockholm format file x

(stockholm-to-file x y)

Write alignment-smob x to Stockholm format alignment file y

(stockholm-column-count x)

Return the number of columns in alignment-smob x

(stockholm-unpack x)

Converts an alignment-smob x into a Scheme data structure

(write x)

Converts an alignment-smob x into a Stockholm format string

Mathematical functions

(ln-gamma k)

Calculates the gamma function, \Gamma(k) = \int_0^\infty e^{-x} x^{k-1} dx

(gamma-density x alpha beta)

Calculates the gamma probability density, \beta^\alpha \frac{1}{\Gamma(\alpha)} x^{\alpha-1} e^{-\beta x}

(incomplete-gamma x alpha beta)

Calculates the incomplete gamma function, i.e. the integral of the gamma density up to x

(incomplete-gamma-inverse p alpha beta)

Calculates the inverse of the incomplete gamma function

(discrete-gamma-medians alpha beta K)

Returns the median rates of K equal-probability bins of the gamma distribution, as per Fig 1 of Yang &: Maximum likelihood phylogenetic estimation from DNA sequences with variable rates over sites: approximate methods. J. Mol. Evol. 1994;39:306-14.

(discrete-gamma-means alpha beta K)

Returns the mean rates of K equal-probability bins of the gamma distribution, as per Fig 1 of Yang &: Maximum likelihood phylogenetic estimation from DNA sequences with variable rates over sites: approximate methods. J. Mol. Evol. 1994;39:306-14.

Individual programs in dart

XRATE

(xrate-validate-grammar x)

Validate the syntax of xrate format grammar x

(xrate-validate-grammar-with-alignment x y)

Validate the syntax of xrate format grammar x, using alignment-smob y to expand macro constructs

(xrate-estimate-tree x y)

Use xrate format grammar y to estimate a tree for alignment-smob x

(xrate-annotate-alignment x y)

Use xrate format grammar y to annotate alignments-smob x

(xrate-train-grammar x y)

Train xrate format grammar y on the list of alignment-smobs y

The standard library

How to include the standard library

Include the file xrate-stdlib.scm e.g. with the following

(&scheme
 (load-from-path "xrate-stdlib.scm"))

Alphabets

xrate-dna-alphabet

xrate format DNA alphabet specification. (Note: a simple define'd symbol, rather than a function.)

Models

(xrate-NY-grammar)

Uses the current definition of codon-translation-table to generate an xrate format grammar implementing the Nielsen Yang model of codon selection: Nielsen & Yang: Likelihood models for detecting positively selected amino acid sites and applications to the HIV-1 envelope gene. Genetics 1998;148:929-36.

(xrate-NY-alphgram)

Wrapper for xrate-NY-grammar that also generates an xrate-dna-alphabet.

Other definitions

codon-translation-table

An association list mapping codons to amino acids. For example, (a a a) maps to K.

-- Ian Holmes - 26 Jan 2012