# flarestack
[](https://flarestack.readthedocs.io/en/latest/?badge=master)
[](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml)
[](https://badge.fury.io/py/flarestack)
[](https://coveralls.io/github/icecube/flarestack?branch=master)
[](https://mybinder.org/v2/gh/icecube/flarestack/master)
[](https://zenodo.org/badge/latestdoi/127512114)
Code for unbinned likelihood analysis of astroparticle physics data, created by [@robertdstein](https://github.com/robertdstein).
Both time-dependent and time-independent analyses can be performed, as well as a "flare-search" algorithm to find event clustering in time as well as space.
Performs single point source analyses, as well as the stacking of sources according to predefined weighting.
Also performs stacking analyses where the signal strength of each source is fit individually.
## Getting started
The easiest way to start using *flarestack* is to play with the introductory ipython notebooks, which can be opened with the following link:
[](https://mybinder.org/v2/gh/icecube/flarestack/master)
The notebooks themselves are found under *examples/ipython_notebooks/*.
The "Binder" provides a pre-built Docker image containing all necessary dependencies, so you can simply click and play. It avoids the need for local installation, and should provide understanding of how the code works.
## Installation instructions
### OPTION A: I only want to do an analysis, and trust the under-the-hood code
We recommend installing flarestack using [*poetry*](https://python-poetry.org)
In that case:
```shell
poetry add flarestack
```
This will resolve your environment and install all dependencies.
Another option is to use *pip*
```shell
pip install flarestack
```
### OPTION B: Actually, I want to see the backend code myself. Maybe I want to contribute to it!
First clone the `git` repository:
```shell
git clone git@github.com:icecube/flarestack.git
```
We again recommend using `poetry` to install the code in your working tree.
For this, go to the directory you cloned the repo into (i.e. `~/flarestack`) and execute:
```shell
poetry install
```
This will install all packages as documented in the `poetry.lock` file.
If you want to also build the documentation locally, you should install the respective dependencies:
```shell
poetry install --with docs
```
You can still use `pip` if you want to:
```shell
pip install -e flarestack/
```
Either way will give you the very latest copy of the code, update the installed version if you git pull or modify scripts
yourself, and still enable you to import flarestack.
If you do want to contribute to _flarestack_, you can check out some guidelines [here](https://github.com/icecube/flarestack/blob/master/CONTRIBUTING.md).
### Using KDE PDFs
If you want to use the KDE spatial PDFs you need to install `photospline` using `conda`.
`flarestack` ships with a `conda_env.yml` file that pins the correct `photospline` version.
Find your `flarestack` directory (either in your `site-packages` directory if you followed Option A or in your `git` clone if you followed Option B) and execute:
```shell
conda env create -f conda_env.yml
```
Alternatively, You can try and install the latest `photospline` version with as described [here](https://anaconda.org/conda-forge/photospline).
### Right, anyway, I've now downloaded *flarestack*. Can I use it right away?
You can get started with *flarestack* immediately using public IceCube datasets provided as part of the code. You can simply run scripts such as those under `/flarestack/analyses/`, and do your science!
You can optionally set custom directorioes for datasets, and for storing data calculated with the code.
### Setting up the dataset directory
If you are running on WIPAC or DESY, you do not need to specify a dataset directory, as IceCube data will be found automatically. Otherwise, you can add:
```shell
export FLARESTACK_DATASET_DIR=/path/to/datasets
```
to point the code to local copies of Icecube datasets.
### Setting up directory for storing data
*flarestack* will produce many files that do not need to be version-controlled. The principle is that everything within this directory can be reproduced by the code, so does not need to be backed up. By default, these files will be saved in a separate within the user home directory, but it might be preferrable to save them elsewhere, such as a scratch directory. You can specify the parent directory:
```shell
export FLARESTACK_SCRATCH_DIR=/path/to/scratch
```
A folder `flarestack__data` will be created in that directory. This is where you will find plots, pickle files and other files produced by the code.
## Building documentation
*flarestack* documentation is available at [Read the Docs](flarestack.readthedocs.io), however you may want to build it locally (especially if you are contributing to the project). To do this, run `sphinx-build` from the root directory of the repository:
```shell
sphinx-build -b html docs/source/ docs/build/html
```
## Testing *flarestack*
Is *flarestack* actually working? You can check the functionality of *flarestack* with *unit tests*. There are a suite of unit tests to cover *flarestack* functionality, which can be run from the base *flarestack* directory with:
```shell
python -m unittest discover tests/
```
*flarestack* runs with Github Actions, a Continuous Integration Service. After each commit, the suite of tests is run, to ensure that the commit did not break anything. You can see the results of these tests at:
[](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml)
If you want to contribute to *flarestack*, please remember to add new tests! The fraction of code presently covered by tests is measured using Coveralls (https://coveralls.io/). As a rule of thumb, at least 80% of the core code should be covered, but >90% would be even better. The current code coverage is:
[](https://coveralls.io/github/icecube/flarestack?branch=master)
## Using *flarestack* for IceCube analysis
*flarestack* is currently used for internal IceCube analysis using unpublished Monte Carlo simulations, as outlined in analysis READMEs. Additional analysis of public IceCube data using effective areas would be possible with this code, but this feature **has not been tested or fully developed**. Any use of this code for public data is done without the endorsement of the IceCube collaboration.
## Citing *flarestack*
If you use *flarestack* for analysis, please cite it! A DOI is provided by Zenodo, which can reference both the code repository, or specific releases of Flarestack.
[](https://zenodo.org/badge/latestdoi/127512114)
# Contributors
* Federica Bradascio [@fbradascio](https://github.com/fbradascio)
* Simone Garrappa [@simonegarrappa](https://github.com/simonegarrappa)
* Massimiliano Lincetto [@mlincett](https://github.com/mlincett)
* Jannis Necker [@JannisNe](https://github.com/jannisne)
* Robert Stein [@robertdstein](https://github.com/robertdstein)
Raw data
{
"_id": null,
"home_page": "https://github.com/icecube/flarestack",
"name": "flarestack",
"maintainer": "Robert Stein",
"docs_url": null,
"requires_python": "<3.12,>=3.9",
"maintainer_email": "rdstein@caltech.edu",
"keywords": "astroparticle physics, science, unbinned likelihood, IceCube",
"author": "Robert Stein",
"author_email": "rdstein@caltech.edu",
"download_url": "https://files.pythonhosted.org/packages/47/8c/46f161d2f95144482ead7b7a34e720454c5ff620a0ac6c2aceb19a880000/flarestack-2.4.8.tar.gz",
"platform": null,
"description": "# flarestack\n[](https://flarestack.readthedocs.io/en/latest/?badge=master) \n[](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml) \n[](https://badge.fury.io/py/flarestack) \n[](https://coveralls.io/github/icecube/flarestack?branch=master) \n[](https://mybinder.org/v2/gh/icecube/flarestack/master) \n[](https://zenodo.org/badge/latestdoi/127512114)\n\n\nCode for unbinned likelihood analysis of astroparticle physics data, created by [@robertdstein](https://github.com/robertdstein).\n\nBoth time-dependent and time-independent analyses can be performed, as well as a \"flare-search\" algorithm to find event clustering in time as well as space.\n\nPerforms single point source analyses, as well as the stacking of sources according to predefined weighting. \nAlso performs stacking analyses where the signal strength of each source is fit individually.\n\n## Getting started\n\nThe easiest way to start using *flarestack* is to play with the introductory ipython notebooks, which can be opened with the following link:\n\n[](https://mybinder.org/v2/gh/icecube/flarestack/master)\n\nThe notebooks themselves are found under *examples/ipython_notebooks/*.\n\nThe \"Binder\" provides a pre-built Docker image containing all necessary dependencies, so you can simply click and play. It avoids the need for local installation, and should provide understanding of how the code works. \n\n## Installation instructions\n\n### OPTION A: I only want to do an analysis, and trust the under-the-hood code\n\nWe recommend installing flarestack using [*poetry*](https://python-poetry.org)\n\nIn that case:\n```shell\npoetry add flarestack\n```\n\nThis will resolve your environment and install all dependencies.\n\nAnother option is to use *pip*\n```shell\npip install flarestack\n```\n\n ### OPTION B: Actually, I want to see the backend code myself. Maybe I want to contribute to it!\n \n First clone the `git` repository:\n\n```shell\ngit clone git@github.com:icecube/flarestack.git\n```\n\nWe again recommend using `poetry` to install the code in your working tree. \nFor this, go to the directory you cloned the repo into (i.e. `~/flarestack`) and execute:\n\n```shell\npoetry install\n```\nThis will install all packages as documented in the `poetry.lock` file.\n\nIf you want to also build the documentation locally, you should install the respective dependencies:\n\n```shell\npoetry install --with docs\n```\n\nYou can still use `pip` if you want to:\n\n```shell\npip install -e flarestack/\n```\n \nEither way will give you the very latest copy of the code, update the installed version if you git pull or modify scripts \nyourself, and still enable you to import flarestack.\n\nIf you do want to contribute to _flarestack_, you can check out some guidelines [here](https://github.com/icecube/flarestack/blob/master/CONTRIBUTING.md).\n\n\n### Using KDE PDFs\nIf you want to use the KDE spatial PDFs you need to install `photospline` using `conda`.\n`flarestack` ships with a `conda_env.yml` file that pins the correct `photospline` version. \nFind your `flarestack` directory (either in your `site-packages` directory if you followed Option A or in your `git` clone if you followed Option B) and execute:\n\n```shell\nconda env create -f conda_env.yml\n```\n\nAlternatively, You can try and install the latest `photospline` version with as described [here](https://anaconda.org/conda-forge/photospline).\n\n\n### Right, anyway, I've now downloaded *flarestack*. Can I use it right away?\n \nYou can get started with *flarestack* immediately using public IceCube datasets provided as part of the code. You can simply run scripts such as those under `/flarestack/analyses/`, and do your science!\n\nYou can optionally set custom directorioes for datasets, and for storing data calculated with the code.\n\n### Setting up the dataset directory\n\nIf you are running on WIPAC or DESY, you do not need to specify a dataset directory, as IceCube data will be found automatically. Otherwise, you can add:\n\n```shell\nexport FLARESTACK_DATASET_DIR=/path/to/datasets\n```\n\nto point the code to local copies of Icecube datasets.\n\n### Setting up directory for storing data\n\n*flarestack* will produce many files that do not need to be version-controlled. The principle is that everything within this directory can be reproduced by the code, so does not need to be backed up. By default, these files will be saved in a separate within the user home directory, but it might be preferrable to save them elsewhere, such as a scratch directory. You can specify the parent directory:\n\n```shell\nexport FLARESTACK_SCRATCH_DIR=/path/to/scratch\n```\n\nA folder `flarestack__data` will be created in that directory. This is where you will find plots, pickle files and other files produced by the code.\n\n## Building documentation\n*flarestack* documentation is available at [Read the Docs](flarestack.readthedocs.io), however you may want to build it locally (especially if you are contributing to the project). To do this, run `sphinx-build` from the root directory of the repository:\n\n```shell\nsphinx-build -b html docs/source/ docs/build/html\n```\n\n## Testing *flarestack*\n\nIs *flarestack* actually working? You can check the functionality of *flarestack* with *unit tests*. There are a suite of unit tests to cover *flarestack* functionality, which can be run from the base *flarestack* directory with:\n\n ```shell\n python -m unittest discover tests/\n```\n\n*flarestack* runs with Github Actions, a Continuous Integration Service. After each commit, the suite of tests is run, to ensure that the commit did not break anything. You can see the results of these tests at:\n\n[](https://github.com/icecube/flarestack/actions/workflows/continous_integration.yml) \n\nIf you want to contribute to *flarestack*, please remember to add new tests! The fraction of code presently covered by tests is measured using Coveralls (https://coveralls.io/). As a rule of thumb, at least 80% of the core code should be covered, but >90% would be even better. The current code coverage is:\n\n[](https://coveralls.io/github/icecube/flarestack?branch=master)\n\n## Using *flarestack* for IceCube analysis\n\n*flarestack* is currently used for internal IceCube analysis using unpublished Monte Carlo simulations, as outlined in analysis READMEs. Additional analysis of public IceCube data using effective areas would be possible with this code, but this feature **has not been tested or fully developed**. Any use of this code for public data is done without the endorsement of the IceCube collaboration.\n\n## Citing *flarestack*\n\nIf you use *flarestack* for analysis, please cite it! A DOI is provided by Zenodo, which can reference both the code repository, or specific releases of Flarestack.\n\n[](https://zenodo.org/badge/latestdoi/127512114)\n\n# Contributors\n\n* Federica Bradascio [@fbradascio](https://github.com/fbradascio)\n* Simone Garrappa [@simonegarrappa](https://github.com/simonegarrappa)\n* Massimiliano Lincetto [@mlincett](https://github.com/mlincett)\n* Jannis Necker [@JannisNe](https://github.com/jannisne)\n* Robert Stein [@robertdstein](https://github.com/robertdstein)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package for unbinned likelihood analysis of physics data",
"version": "2.4.8",
"project_urls": {
"Documentation": "https://flarestack.readthedocs.io/en/latest/?badge=latest",
"Homepage": "https://github.com/icecube/flarestack",
"Repository": "https://github.com/icecube/flarestack"
},
"split_keywords": [
"astroparticle physics",
" science",
" unbinned likelihood",
" icecube"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cb9c7d75f1d6993943da34f3775655e3e3996e38e310cf4cd09972e465f9f299",
"md5": "92dcfc247ea38aa3667d3a149ad47c7c",
"sha256": "afbf08c73ee82190b0a97f028d2073369a09cb951061d2cda363abd1a877fce9"
},
"downloads": -1,
"filename": "flarestack-2.4.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "92dcfc247ea38aa3667d3a149ad47c7c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.9",
"size": 29209147,
"upload_time": "2024-07-18T15:56:51",
"upload_time_iso_8601": "2024-07-18T15:56:51.564937Z",
"url": "https://files.pythonhosted.org/packages/cb/9c/7d75f1d6993943da34f3775655e3e3996e38e310cf4cd09972e465f9f299/flarestack-2.4.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "478c46f161d2f95144482ead7b7a34e720454c5ff620a0ac6c2aceb19a880000",
"md5": "c33c172dc72557f3ceb5b7c055083278",
"sha256": "136c44e6099eb19bdadd1a48953a80066663db5f41abc6fa67e1b6329cab512f"
},
"downloads": -1,
"filename": "flarestack-2.4.8.tar.gz",
"has_sig": false,
"md5_digest": "c33c172dc72557f3ceb5b7c055083278",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.9",
"size": 28474668,
"upload_time": "2024-07-18T15:56:54",
"upload_time_iso_8601": "2024-07-18T15:56:54.695912Z",
"url": "https://files.pythonhosted.org/packages/47/8c/46f161d2f95144482ead7b7a34e720454c5ff620a0ac6c2aceb19a880000/flarestack-2.4.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-18 15:56:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "icecube",
"github_project": "flarestack",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "flarestack"
}
JSON
