distromax

Empirically estimating the distribution of the loudest candidate from a gravitational-wave search

This package implements the methods described in Tenorio, Modafferi, Keitel, Sintes (2021) to estimate the distribution of the loudest candidate from a search.

The actual implementation includes:

• fit.py:
  • BatchMaxGumbel: Basic distromax method. Construct the batchmax distribution of a set of samples and return the corresponding Gumbel fit. Max. propagation is included as a method.
  • BatchMaxGumbelNotchingOutlier: Thin wrapper around BatchMaxGumbel to notch narrow-band outliers before computing the batchmax distribution. The specifics of this implementation are discussed on appendix B of the accompanying publication.
• analytical.py:
  • AnalyticalGammaToGumbel: Compute the Gumbel distribution associated to the maximum of a set of independent Gamma random variables using the formulas derived in Gasull, López-Salcedo, Utzet (2015).

See the examples for concrete applications of these classes.

Citing this work

If distromax was useful for your work, we would appreciate if you cite both the software version DOI under Zenodo and one or more of the following scientific papers:

• Introduction of distromax and description of the method: Tenorio, Modafferi, Keitel, Sintes, (2021) (inspire / nasa)
• Analytical limit of a Gamma random variable to a Gumbel distribution: A. Gasull, J. López-Salcedo, F. Utzet TEST volume 24, pages 714–733 (2015)

Here is a better-formatted bibtex entry for the version-independent Zenodo:

@misc{distromax,
  author       = {Tenorio, Rodrigo and
                  Modafferi, Luana M. and
                  Keitel, David and
                  Sintes, Alicia M.},
  title        = {distromax: Empirically estimating the distribution of the loudest candidate from a gravitational-wave search},
  month        = dec,
  year         = 2021,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.5763765},
  url          = {https://doi.org/10.5281/zenodo.5763765},
  note         = {\url{https://doi.org/10.5281/zenodo.5763765}}
}

For individual version DOIs, see the right sidebar at Zenodo

How to install

Please, make sure you are running on a virtual environment to avoid any conflicts with system libraries.

The simplest way is to install distromax from PyPI using pip:

pip install distromax

distromax can also be installed using conda from the conda-forge channle as follows:

conda install -c conda-forge distromax

See the official documentation to learn about conda environments.

To install directly from source, clone this repo with git clone and install using pip

git clone https://github.com/Rodrigo-Tenorio/distromax.git
cd distromax
pip install .

Troubleshooting

In some conservative systems the default setuptools may not be the latest version and installing from source may produce an erorr message such as

ERROR: setuptools==44.1.1 is used in combination with setuptools_scm>=6.x

Your build configuration is incomplete and previously worked by accident!


This happens as setuptools is unable to replace itself when a activated build dependency
requires a more recent setuptools version
(it does not respect "setuptools>X" in setup_requires).


setuptools>=31 is required for setup.cfg metadata support
setuptools>=42 is required for pyproject.toml configuration support

Suggested workarounds if applicable:
 - preinstalling build dependencies like setuptools_scm before running setup.py
 - installing setuptools_scm using the system package manager to ensure consistency
 - migrating from the deprecated setup_requires mechanism to pep517/518
   and using a pyproject.toml to declare build dependencies
   which are reliably pre-installed before running the build tools

A simple workaround in that case is to update the pip and setuptools packages

pip install --upgrade pip setuptools