Hawkes

Estimate parameters for a hawkes model over spatial positions.

For multiple sets of points called processes, which each point being a spatial position (for example, mark on a chromosome). Assume they have been generated by a hawkes process, modelised with a function base phi(k). Then estimate the weights of the hawkes process from actual points.

Usage

Hawkes must be compiled before use, see the How to build section. There are no runtime library dependencies.

General use

Use ./hawkes -h to access the list of command line options with a small description.

Example of use: ./hawkes -f process_a.bed -f process_b.bed -histogram 10 10000 -kernel homogeneous_interval > output_file.

• -f filename loads the process from filename. Use once for each process to be loaded.
• -b filename loads the process but reverses the dimension (x -> -x on the positions).
• -histogram K delta specifies the function base. Required. Haar base is also supported.
• -kernel config what kernel configuration to use, defaults to none if not specified.

The matrix of estimated weights is printed on the standard output, in a tab-separated text format. Redirect the standard output using <cmd> > file to store the output in a file. General information and progress is printed on the standard error output, and will not be redirected.

The verbose mode adds a header to the output with the parameters used to generate the weights (process files, base, kernel setup). This header is prefixed with # so that programs like R can ignore it and load the matrix without problems.

Input

The computations is splitted along regions, which represent independent spaces where marks can exists. For each region, the computation step will only consider marks from the region (for each process), and ignore others. Results are summed between regions afterwards, before the final LASSO step. The region of a point is determined by the text in the first column of bed files:

# region start end ; example with 2 regions (chr1, chr2)
chr1 1 42
chr1 78 102
chr2 0 34

This program requires all points of a region to be in sequence (no interleaving of regions). Regions missing in some of the processes will be considered empty. A ratio of missing regions is printed; if too high, this may indicate a mismatch between region names accross processes.

Further information

See the BRP18 paper for the global model. See the pdf documentation in doc/shapes for computation details.

How to build

A C++ compiler supporting C++14 is required:

• g++ >= 5.0
• clang++ >= 3.4
• for any other compiler, check that it supports the -std=c++14 flag

Simple compilation:

• make will compile the program with the default C++ compiler of your distribution, using a copy of Eigen 3.3.9 (matrix library).
• make CXX=<name_or_path_to_compiler_binary> will use the specified compiler if the default is not valid.
• make EIGEN_INCLUDE_PATH=/path/to/eigen/include will use the indicated Eigen files instead of downloading a copy. Use if Eigen is already installed.

Advanced compilation:

• make CXX_FLAGS_EXTRA='-static' to generate a self-contained compiled version of Hawkes which should work on any machine with the same architecture and operating system.

Developer corner

make hawkes_debug will compile the program in debug mode, with assertions enabled and debug informations generated.

make test will compile and run a file with a lot of small tests of parts of the code.

make format will try to format the format the source code using the clang-format tool.

Hawkes uses 3 header-only libraries which are included in the current code:

• fmtlib formatting library to generate output text
• doctest as a test framework for unit tests

License

MIT

Todo

• better error reporting / handling of bad values
• replace CLI parser with external dep ?
• investigate lassoshooting convergence failures