libv3.md

HBL libv3

This document is intended to help developers and super-users who need to extend or write new scripts in the HyPhy batch language. The HyPhy batch language (HBL) library libv3 is a collection of utility functions that are commonly used in a variety of analyses.

Version 3 introduces a large number of necessary changes in the HBL. One of the major changes was the implementation of namespaces in the HBL. Before, all variables were automatically and irrevocably declared at a global scope, which meant that declaring or modifying a variable i in one HBL script could affect the result in another script being run concurrently. This was a really bad thing! Namespaces are a standard solution to this problem, where different variables can share the same name, e.g., i, but belong to different namespaces so that modifications to one instance does not affect the others.

The second major change that is facilitated by namespaces is the refactoring and standardization of the template batch files.

Namespaces

Namespace in the HBL are implmemented by prefixes on varaible names. For example, slac.pvalue is a variable that is distinct from pvalue simply because its name includes the substring slac.. Unlike programming languages like JavaScript or Python, the . character is not a reserved symbol for accessing the property of an object - it's just another character. When combined with some utility functions such as namespace, this simple approach serves well enough.

• lfunction - a modified version of HBL function declaration such that any variables declared within the function are at local scope. Otherwise, all variables are at global scope, e.g., declaring with function.

• namespace - a convenience function that propagates a given namespace prefix to all nested variables. Usage:

  namespace *prefix* {
    a = 1;
    b = "ACGT":
  } // yields the variables *prefix*.a and *prefix*.b
  

Function libraries

The function library files are located in the directory res/TemplateBatchFiles/libv3.

Standard libv3 libraries

/libv3

• stats.bf - A collection of functions for generating descriptive statistics on inputs.
• all-terms.bf - Defines a terms namespace for global variables.