LatAnalyze/Readme.md

# LatAnalyze 

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) [![DOI](https://zenodo.org/badge/10201777.svg)](https://zenodo.org/badge/latestdoi/10201777) [![Build Ubuntu](https://github.com/aportelli/LatAnalyze/actions/workflows/build-ubuntu.yml/badge.svg)](https://github.com/aportelli/LatAnalyze/actions/workflows/build-ubuntu.yml) [![Build macOS](https://github.com/aportelli/LatAnalyze/actions/workflows/build-macos.yml/badge.svg)](https://github.com/aportelli/LatAnalyze/actions/workflows/build-macos.yml)

## Description
LatAnalyze is a C++14 library for statistical data analysis based on bootstrap
resampling. It has been written with lattice QCD data analysis in mind (hence
the name), but its features are not lattice specific and can be used more general statistical context.

Sadly a proper documentation was never written, but some comprehensive examples covering several key features can be found in the `examples` directory.

The main features are the following:

* Array and matrix types with fast arithmetic operations based on [Eigen](http://eigen.tuxfamily.org).
* High-level types for bootstrap sample manipulation (including various statistical estimators and histogramming).
* Mathematical expression parser for runtime defined functions.
* Data I/O in ASCII, XML, and HDF5.
* High-level wrappers to minimisation routines from the [GSL](http://www.gnu.org/software/gsl/), [Minuit 2](https://github.com/root-project/root/tree/master/math/minuit2) (optional) and [NLopt](http://ab-initio.mit.edu/wiki/index.php/NLopt).
* Non-linear regression with error on independent variables (through total least squares).
* High-level wrappers to numerical integrator and non-linear solver from the [GSL](http://www.gnu.org/software/gsl/).
* High-level functional types for function of model. General functions can be defined from C pointers, C++ objects, strings of mathematical expressions or tabulated data.
* High-level plotting functions based on [gnuplot](http://www.gnuplot.info), with the possibility of generating and saving plot scripts.

## Installation
The head of the `master` branch always points to the latest stable release. The `develop` branch is the main unstable branch of LatAnalyze.

LatAnalyze is written in C++14. It has been successfully built on various Unix platform using reasonably recent versions of Clang or GCC.
The only strict dependencies are the [GSL](http://www.gnu.org/software/gsl/) and [HDF5](https://www.hdfgroup.org/HDF5/) (built with C++ support).
Additionally, cmake (from 3.11), bison (from 3.0) and flex are necessary to build the library. Unless you use a very exotic system, these tools are standard on any Unix platform and should be already present or easy to install through a package manager.
Optional dependencies are [Minuit 2](https://github.com/root-project/root/tree/master/math/minuit2) and [NLopt](http://ab-initio.mit.edu/wiki/index.php/NLopt).

LatAnalyze is built through CMake. Below are example instructions for compiling and installing LatAnalyze. 

### Portable quick installation
For a quick installation with all possible extensions execute: 
```
./install-latan.sh <prefix>
``` 
in the `ci-scripts` directory where `<prefix>` is where you want LatAnalyze (and its dependencies) to be installed. This script will automatically download, build and install GSL, HDF5, Minuit, and NLopt.

### Quick installation on macOS with dependencies through Homebrew
All the dependencies of LatAnalyze can be installed through the [Homebrew](https://brew.sh) package manager.
```
brew install automake autoconf libtool bison flex gsl minuit2 nlopt hdf5
```
Then build the library with `cmake`
```
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_BUILD_TYPE=Release ..
make -j <n>
make install
```
where `<prefix>` should be replaced by the desired prefix for LatAnalyze installation, and `<n>` is the number of parallel build processes.

### Dependencies through Homebrew/Linuxbrew
If you use Homebrew/Linuxbrew to manage packages, the following command can install all the dependencies of LatAnalyze (including optional ones)

## Using LatAnalyze in CMake projects
When LatAnalyze is installed, the necessary CMake module configuration files to link against the library are available in the installation prefix.

To link against LatAnalyze in a downstream CMake project, simply use
```cmake
find_package(LatAnalyze)
target_link_libraries(<my_app> LatAnalyze::LatAnalyze)
```
where `<my_app>` is a CMake target. If LatAnalyze was installed in a non-standard prefix, you might have to set `CMAKE_PREFIX_PATH` accordingly for `find_package` to be successful.

You can additionally modify the `find_package` to ensure specific components are supported
```cmake
find_package(LatAnalyze REQUIRED COMPONENTS <...>)
```
where `<...>` is a space separated list of components. Currently available components are
- `MINUIT2`: Minuit 2 minimisers
- `NLOPT`: NLopt minimisers

## History
#### v3.6
Build system:
* automake build discontinued, now using CMake
* CI through GitHub Actions

Additions:
* Discrete wavelet transform
* Thread pools
* Correlation dynamic range (CDR) calculation
* Data filtering and CDR optimisation

Changes:
* Significant optimisation of covariance matrix calculation
* Covariance matrix available for any `StatArray` (not only resampled arrays)

#### v3.5.1
Various fixes and cleaning of outdated code.

#### v3.5
Additions:
* 'Impulse' & line type plots
* Plot line width & dash modifiers
* Plot palettes (`category10` by default)
* Multivariate Gaussian RNG
* 2-pt fitter 'scan' mode over all possible fit ranges
* Command line utility for plotting data

Changes:
* Complete overhaul of the header structure
* Integration of LatCore in LatAnalyze
* p-value is now a 2-sided chi^2 test, 1-sided value kept as 'chi^2 CCDF'

Fixes:
* Matrix plot data now saving correctly
* Many compatibility fixes

#### v3.4
Additions:
* `latan-config` utility to easily compile LatAnalyze-based programs
* Linear and constant models to the 2-point fitter

Changes:
* HDF5 is now a compulsory dependency

Fixes:
* Variance matrix computation fix.

#### v3.3
Additions:
* Sample plot CL utility.
* Infinity as a math constant.
* Option to dump bootstrap sequence while resampling.
* FFT through the GSL.

Changes:
* GSL integrator accepts infinite bounds.
* `latan-sample-combine` accepts mixes of `DSample` and `DMatSample`.
* More general `latan-sample-element` command.

#### v3.2.2
Additions:
* The math interpreter supports `inf` for infinity.

Changes:
* Vector version of `setUnidimData`.

Fixes:
* Variance matrix computation fix.

#### v3.2.1
Fixes:
* Wrong argument number check in `latan-resample`

#### v3.2 (needs LatCore 1.1)
Additions:
* 2-pt function fitter `latan-2pt-fit`
* Tool to extract one element of a matrix sample `latan-sample-element`
* Band plotting

Changes:
* Sample utilities renamed `latan-sample-*`
* Resample utility renamed `latan-resample`

#### v3.1.2
Fixes:
* HDF5 archive URL update in build scripts

#### v3.1.1 (needs LatCore 1.0)
Fixes:
* Minuit precision fixed
* Minor fit interface fixes

#### v3.1
Additions:
* Wrappers to NLopt and GSL minimisers.
* Command-line tool to plot the correlation heatmap of a boostrap sample file.
* I/O functions for `DSample` type.

Changes:
* Internal random generator removed (obsolete because of C++11 pseudo-random generators).
* Fit interface and `XY*Data` classes rewritten from scratch for improved flexibility and performance.

Fixes:
* **Loads** of portability and compatibility fixes and [CI with Travis](https://travis-ci.org/aportelli/LatAnalyze).

#### v3.0
Commit `7b4f2884a5e99bbfab4d4bd7623f609a55403c39`.  
First 'stable' version of LatAnalyze in C++. The v2.0 refers to the [C version](https://github.com/aportelli/LatAnalyze-legacy) and v1.0 to an old undistributed version.  
**This version compiles fine on OS X with clang but does have many portability issues to other platforms/compilers, v3.1 is the first real release.**