Merge remote-tracking branch 'origin/master' into var_bin

Author: thehrh

.github/workflows/pythonpackage.yml

@@ -18,9 +18,9 @@ jobs:
         python-version: ['3.8', '3.10']
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v1
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

EXTERNAL_ATTRIBUTION.md

@@ -2,52 +2,182 @@
 
 PISA is distributed with some software and data obtained from outside the IceCube Collaboration.
 The authors and any pertinent copyrights are listed below.
-If you identify any mistakes in the below or find any other such components being distributed with PISA that are not listed here, please [email](jll1062+pisa@phys.psu.edu) or [file an issue](http://github.com/icecubeopensource/pisa).
+If you identify any mistakes in the below or find any other such components being distributed with PISA that are not listed here,
+please [email](mailto:analysis@icecube.wisc.edu?subject=[GitHub]%20PISA%20source) or [file an issue](https://github.com/icecube/pisa/issues).
 
-Unless noted below or in the contents of an individual file, all files distributed with PISA are Copyright (c) 2014-2017, The IceCube Collaboration, and are licensed under the Apache 2.0 license.
+Unless noted below or in the contents of an individual file, all files distributed with PISA are Copyright (c) 2014-2025, The IceCube Collaboration, and are licensed under the Apache 2.0 license.
 See the LICENSE file for details.
 
+
+## daemonflux
+
+The service [`flux.daemon_flux`](/pisa/stages/flux/daemon_flux.py) does not reproduce but calls upon the daemonflux software
+> https://github.com/mceq-project/daemonflux
+
+based on the paper
+> J. P. Yanez, A. Fedynitch, Phys.Rev. D 107, 123037 (2023)
+
+The software is subject to the following copyright:
+```
+BSD 3-Clause License
+
+Copyright (c) 2023, Anatoli Fedynitch
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
 ## MCEq
 
-The service `flux.mceq` does not reproduce but does call upon the MCEq software.
-> https://github.com/afedynitch/MCEq
+Files in the directory [`pisa_examples/resources/flux`](/pisa_examples/resources/flux) containing the name *MCEq*
+have been produced with the MCEq software
+> https://github.com/mceq-project/MCEq
+
+The authors of that software / the paper that it is based upon
+> A. Fedynitch, R. Engel, T. K. Gaisser, F. Riehn, T. Stanev, EPJ Web Conf. 99 (2015) 08001, arXiv:1503.00544
+
+request that anyone who uses their work to produce results cite their work. Please do so if you make use of either of the
+[`flux.mceq_barr`](/pisa/stages/flux/mceq_barr.py) or [`flux.mceq_barr_red`](/pisa/stages/flux/mceq_barr_red.py) services or of
+the script [`create_barr_sys_tables_mceq.py`](/pisa/scripts/create_barr_sys_tables_mceq.py) which calls upon MCEq.
 
-The authors of that software / the paper that it is based upon (A. Fedynitch, R. Engel, T. K. Gaisser, F. Riehn, T. Stanev) request that anyone who uses their work to produce results cite their work, so please do so if you make use the `flux.mceq` service.
 The form of the citation that they request is found in their documentation at
 > http://mceq.readthedocs.io/en/latest/citations.html
 
-## prob3numba
+The software is subject to the following copyright:
+```
+BSD 3-Clause License
 
-Files in the directory `pisa/pisa/stages/osc/prob3numba` were adapted from the CUDA re-implementation of Prob3++ called prob3GPU
-> https://github.com/rcalland/probGPU
+Copyright (c) 2019, Anatoli Fedynitch
+All rights reserved.
 
-which is cited by the paper
-> R. G. Calland, A. C. Kaboth, and D. Payne, Journal of Instrumentation 9, P04016 (2014).
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
 
 ## Honda et al. flux models
 
-Files in the directory `example_resources/flux` containing the name *honda* are from
+Files in the directory [`pisa_examples/resources/flux`](/pisa_examples/resources/flux) containing the name *honda* are from
 > http://www.icrr.u-tokyo.ac.jp/~mhonda
 
 with associated paper
 >  M. Honda, M. S. Athar, T. Kajita, K. Kasahara, and S. Midorikawa, Phys. Rev. D 92, 023004 (2015).
 
 ## Barr et al. flux models
 
-Files in the directory `example_resources/flux` containing the name *bartol* are modified slightly (to have similar format to the work by Honda et al. cited above) from
+Files in the directory [`pisa_examples/resources/flux`](/pisa_examples/resources/flux) containing the name *bartol* are
+modified slightly (to have similar format to the work by Honda et al. cited above) from
 >  http://www-pnp.physics.ox.ac.uk/~barr/fluxfiles
 
 with associated paper
 > G. D. Barr, T. K. Gaisser, P. Lipari, S. Robbins, and T. Stanev, Phys. Rev. D 70, 023006 (2004).
 
+## GLoBES
+
+The service [`osc.globes`](/pisa/stages/osc/globes.py) does not reproduce but calls upon the GLoBES software
+> https://www.mpi-hd.mpg.de/personalhomes/globes/index.html
+
+The authors of that software request that anyone who uses their work to produce results cite their work.
+Please do so if you make use of the above service. The form of the citation that they request
+is found in their documentation at
+> https://www.mpi-hd.mpg.de/personalhomes/globes/documentation.html
+
+## nuSQuIDS
+
+The service [`osc.nusquids`](/pisa/stages/osc/nusquids.py) does not reproduce but calls upon the nuSQuIDS software
+> https://github.com/arguelles/nuSQuIDS
+
+which is subject to the LGPL-3.0 license.
+
+## prob3numba
+
+Files in [`pisa/stages/osc/prob3numba`](/pisa/stages/osc/prob3numba) were adapted from the CUDA re-implementation of Prob3++ called prob3GPU
+> https://github.com/rcalland/probGPU
+
+which is cited by the paper
+> R. G. Calland, A. C. Kaboth, and D. Payne, Journal of Instrumentation 9, P04016 (2014).
+
 ## PREM
 
-The preliminary reference Earth model data in the `example_resources/osc` directory (named `PREM*`) come from the paper
+The preliminary reference Earth model data in [`pisa_examples/resources/osc`](/pisa_examples/resources/osc) (named `PREM*`) come from the paper
 > A. M. Dziewonski and D. L. Anderson, Physics of the Earth and Planetary Interiors 25, 297 (1981)
 
+## emcee
+
+The files [`llh_client.py`](/pisa/utils/llh_client.py) and [`analysis.py`](/pisa/analysis/analysis.py) call upon the emcee software
+> https://github.com/dfm/emcee
+
+which is subject to the following copyright:
+```
+The MIT License (MIT)
+
+Copyright (c) 2010-2021 Daniel Foreman-Mackey & contributors.
+
+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.
+```
+
 ## KDE
 
-The file `pisa/pisa/utils/vbwkde.py` contains an implementation of (part of) the paper 
+The file [`vbwkde.py`](/pisa/utils/vbwkde.py) contains an implementation of (part of) the paper
 > Z. I. Botev, J. F. Grotowski, and D. P. Kroese, Ann. Statist. 38, 2916 (2010).
 
 The functions `isj_bandwidth` and `fixed_point` therein are adapted directly from the Matlab implementation by Zdravko Botev at
@@ -82,9 +212,47 @@ and are therefore subject to the following copyright:
   SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ```
 
+## scikit-learn
+
+The service [`utils.kfold`](/pisa/stages/utils/kfold.py) does not reproduce but calls upon the scikit-learn software
+> https://github.com/scikit-learn/scikit-learn
+
+The software is subject to the following copyright:
+```
+BSD 3-Clause License
+
+Copyright (c) 2007-2024 The scikit-learn developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of the copyright holder nor the names of its
+  contributors may be used to endorse or promote products derived from
+  this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+```
+
 ## Versioneer
 
-Automatic versioning is provided by public-domain sofware The Versioneer, written by Brian Warner (files `versioneer.py` and `pisa/_version.py`).
-This project can be found at
-> https://github.com/warner/python-versioneer
+Automatic versioning is provided by public-domain sofware The Versioneer, written by Brian Warner
+(files [`versioneer.py`](versioneer.py) and [`_version.py`](/pisa/_version.py)). This project can be found at
+> https://github.com/python-versioneer/python-versioneer
 

LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright (c) 2014-2017 The IceCube Collaboration
+   Copyright (c) 2014-2025 The IceCube Collaboration
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

docs/source/conf.py

@@ -62,24 +62,24 @@
 
 # General information about the project.
 project = u'PISA'
-copyright = u'2021, The IceCube/PINGU Collaboration'
+copyright = u'2025, The IceCube/PINGU Collaboration'
 author = u'The IceCube/PINGU Collaboration'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u'4.0'
+version = u'4.1'
 # The full version, including alpha/beta/rc tags.
-release = u'4.0'
+release = u'4.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+#language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

pisa/README.md

@@ -1,37 +1,4 @@
-## About PISA
+# About PISA
 
 PISA implements a modular architecture wherein users can combine one or more analysis pipelines into distribution makers to make "data" and—separately—template distributions.
 Within each pipeline, users can choose among several implementations for each of the stages they choose to include.
-
-Finally, multiple types of analysis can be performed using the generated distributions to ultimately characterize the ability of the detector to make a measurement.
-
-### Analysis types
-
-PISA implements both what we call ***parameterized-Monte Carlo (MC) stages*** and ***reweighted-MC stages***.
-In the former, distributions (and not individual event weights) are modified to reflect the effects of each analysis stage.
-In the latter, the individual events' weights and properties (such as reconstructed energy) are modified directly to reflect the effects of the detector, and only in the end are the events histogrammed to characterize their distribution.
-
-See the analysis guide for more explanaton of the difference between the two.
-
-### How an analysis is structured
-
-All of the analyses possible utilize a "data" distribution.
-This can come from an actual measurement or by *injecting* a set of assumed-true values for the various parameters into the analysis pipeline(s) and producing what is called ***Asimov data***—the expected distribution given those parameter values—or ***pseudo data***, which is Asimov data but with random (Poisson) fluctuations applied.
-A minimizer attempts to match the "data" distribution with a template by varying the parameters used to generate the template.
-The "closeness" of match between the generated template and the "data" distribution is measured by a criterion such as chi-squared or log likelihood.
-
-An important question is the significance of the experiment to measure one or more of the above parameters (the *measured parameters*).
-To do this, the measured parameters are fixed successively to a range of values and, at each value, the matching process above is repeated with all other parameters—the *nuissance parameters*—allowed to vary.
-This shows sensitivity of the criterion to the measured parameters, and hence the ability for the experiment to measure those parameters.
-Put another way: The more the closeness creiterion varies with a change in the measurement parameters (after the nuissance parameters have done their best to try to make the templates all look like the data), the better able the experiment is to distinguish between values of the measured parameters.
-
-### An example parameterized-MC analysis pipeline
-
-![Parameterized-MC analysis pipeline](images/PINGUSimulationChain.png)
-
-The original drawing is [here](https://docs.google.com/drawings/edit?id=1RxQj8rPndwFygxw3BUf4bx5B35GAMk0Gsos_BiJIN34).
-
-### More information about analysis
-
-An excellent (and far more detailed) description of the analysis process is maintained by Elim Cheung with particular application to IceCube/DeepCore atmospheric neutrino measurements [here](http://umdgrb.umd.edu/~elims/Fitter/Basics).
-She wrote her own fitter to perform these tasks. You can evaluate her ezFit analysis software as an alternative to (or as a complementary tool for comparing results with) PISA [here](http://code.icecube.wisc.edu/projects/icecube/browser/IceCube/sandbox/elims/ezfit).