Metadata-Version: 2.1
Name: figaro
Version: 1.4.4
Summary: FIGARO: Fast Inference for GW Astronomy, Research & Observations
Author-email: Stefano Rinaldi <stefano.rinaldi@uni-heidelberg.de>, Walter Del Pozzo <walter.delpozzo@unipi.it>, Daniele Sanfratello <daniele.sanfratello@studenti.unipi.it>
License: MIT License
        
        Copyright (c) 2022 Stefano Rinaldi
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Documentation, https://figaro.readthedocs.io
Project-URL: Repository, https://github.com/sterinaldi/FIGARO.git
Project-URL: Issues, https://github.com/sterinaldi/FIGARO/issues
Keywords: DPGMM,figaro,hierarchical,inference,HDPGMM
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>1.22
Requires-Dist: scipy
Requires-Dist: matplotlib!=3.6.3
Requires-Dist: dill
Requires-Dist: corner
Requires-Dist: numba
Requires-Dist: h5py
Requires-Dist: tqdm
Requires-Dist: lalsuite
Requires-Dist: myst-parser
Requires-Dist: ray

# [FIGARO - Fast Inference for GW Astronomy, Research & Observations](https://www.youtube.com/watch?v=uJeJ4YiVFz8)

FIGARO is an inference code designed to estimate multivariate probability densities given samples from an unknown distribution using a Dirichlet Process Gaussian Mixture Model (DPGMM) as nonparameteric model.
It is also possible to perform hierarchical inferences: in this case, the model used is (H)DPGMM, described in [Rinaldi & Del Pozzo (2022a)](https://ui.adsabs.harvard.edu/abs/2022MNRAS.509.5454R/abstract).
Differently from other DPGMM implementations relying on variational algorithms, FIGARO does not require the user to specify a priori the maximum allowed number of mixture components. The required number of Gaussian distributions to be included in the mixture is inferred from the data.
Please cite [Rinaldi & Del Pozzo (2022b)](https://ui.adsabs.harvard.edu/abs/2022arXiv220507252R/abstract) if you use FIGARO in your research. The documentation and user guide for FIGARO is available at https://figaro.readthedocs.io .

## Getting started

You can install FIGARO either via pip (`pip install figaro`, stable release) or from source (clone this repository and then `pip install .`, possibily unstable).

FIGARO comes with two plug-and-play console scripts:
* `figaro-density` reconstructs a probability density given a set of samples;
* `figaro-hierarchical` reconstructs a probability density given a set of single-event samples, each of them drawn around a sample from the initial probability density.

In addition to these, the parallelized version of the inference scripts (`figaro-par-density` and `figaro-par-hierarchical`) are available (see below for a note on them). 
The basic usage for the serial scripts is:
* `figaro-density -i path/to/samples.txt -b "[[xmin,xmax]]`;
* `figaro-hierarchical -i path/to/folder -b "[[xmin,xmax]]` where `folder` stores the single-event samples files `samples_1.txt`, `samples_2.txt`, and so on. 

In order to see all the available options, run `console_script_name -h`.

If you only wish to reconstruct some probability density or run a vanilla hierarchical analysis, we strongly recommend using these scripts, which are already tested and optimised.
However, if you wish to include FIGARO in your own scripts, an introductive guide can be found in the `introductive_guide.ipynb` notebook, where we show how to to reconstruct a probability density with FIGARO and how to use its products. We strongly encourage the interested user to go through the whole notebook, since it provides a (hopefully detailed) tutorial on how to properly set and use FIGARO.

