| Name | numcmctools JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | MCMC plotting framework for official results from neutrino oscillation experiments |
| upload_time | 2024-10-17 16:12:08 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License Copyright (c) 2024 NuMCMCTools 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. |
| keywords |
neutrino
physics
hep
mcmc
plotting
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
uproot
numpy
matplotlib
tqdm
sympy
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# NuMCMCTools
This package is intended as a lightweight tool to assist in analysis using
public releases of MCMC chains from neutrino oscillation analyses. The
following experiments have released data compatible with this software:
* Experiment 1
* Experiment 2
## Installation
To install `numcmctools` with PyPI, run the following command:
```bash
pip install numcmctools
```
To install directly from source, first clone numcmctools with git:
```bash
git clone https://github.com/NuMCMCTools/NuMCMCTools.git
```
enter the new NuMCMCTool directory and simply run:
```bash
pip install .
```
The pacakge does not need to be installed to use it, you can simply `git clone`
the package and add your own macros that include the `numcmcmtools` folder.
## File Format
The expected input format for this code is a ROOT file containing at
least one TTree. The tree can have any name. Inside the tree, there
will be at least six branches called:
* DeltaCP, in radians, across any $2\pi$ interval
* Theta13, in radians, [0, $\pi$/2]
* Theta23, in radians, [0, $\pi$/2]
* Theta12, in radians, [0, $\pi$/2]
* Deltam2_32, in $\text{eV}^2$
* Deltam2_21, in $\text{eV}^2$
which correspond to the standard parameters of neutrino mixing; the
first four are the PMNS angles, and the last two are the mass
splittings. For more information on the parameterization see the [PDG
review on neutrino mixing](https://pdg.lbl.gov/2024/web/viewer.html?file=../reviews/rpp2024-rev-neutrino-mixing.pdf).
Each parameter has some prior set by the original analyzers. The
format of this information is a TList containing a TNamed for each branch,
which specifies the name of the branch and its prior.
The priors are specified as either `Uniform` or `Gaussian(mean, sigma)`.
There is then a further specification as to which variable the functional form
applies to. For example, a specification of
``` Theta23 Uniform:sin^2(Theta23)```
indicates that the prior for Theta23 is uniform in $\sin^2\theta_{23}$.
The file additionally contains a citation to the original analysis that
produced the chain.
There may be additional information contained in the file; please see
the data release from the particular analysis for more detail.
In this code, the class `mcmcsamples` is responsible for loading
in the required information from the file. The constructor takes the
filepath for the input file and the name of the oscillation parameters
tree, and an optional argument for additional variables to be loaded.
An example tree (`examples/testchaindata.root`) with the required
features is provided for testing the functionality of this software.
A very basic script for loading the example tree is
`examples/load_mcmc.py` and can be run as follows:
```bash
python -m examples.load_mcmc
```
## Posterior Density Functions and Contours
After the tree is loaded, an instance of `plotstack` can be created,
which is initialized with an `mcmcsamples` instance. Individual
`plot`s can be added to the plot stack. One and two dimensional plots
are currently supported.
A plot is added to the plot stack with the `add_plot` function, which
takes as arguments an array of the name(s) of the variables to be
plotted as strings, any change in priors to be applied (see section below for details),
the bins and axis ranges for the plots, as defined in
[numpy.histogram](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html)
or
[numpy.histogram2d](https://numpy.org/doc/stable/reference/generated/numpy.histogram2d.html),
and finally whether to treat the two mass orderings separately
(`True`) or together (`False`, default).
Any number of plots can be added to the stack. When all plots are
created, they can be filled by calling `fill_plots`, which has two
optional arguments. The first causes only the first
`n_steps` to be filled from the tree; this is useful in testing the
plot stack for very large input trees; the second restricts the number
of steps read from the tree to be `batchsize` at any given time, which
is helpful for memory management. Above a batch size of approximately
100000, there is no performance impact on the time it takes to read
large trees and fill plots; this value is therefore set at the
default. The number of plots to be filled does have an impact on the run
time of the code.
After the histograms are filled, they are normalized to create
probability _density_ functions, such that individual bins are
normalized to the width/area of the bin and the integral is normalized
to 1.
Credible intervals can be created by calling `make_intervals`
on either the plot stack or individual plots within the stack. The
function takes an array of credible interval levels.
PDFs and intervals can be drawn with `draw_plot` and `draw_interval`
respectively, and can take an `Figure` argument from matplotlib. When
dividing a figure into subfigures, use the `subfigures` command, rather
than `subplots`, as `subplots` is used internally.
The plot stack can also be used to automatically draw all of the plots
in the stack, choosing the optimal dimensions for the subfigure array.
An example of the plotting features is in `examples/simpleplots.py` and
can be run as follows:
```bash
python -m examples.simpleplots
```
The output of this example should look as follows
## Derived Variables
Variables derived from the six required parameters—for example,
$\sin^2\theta_{23}$-can be defined and used for plotting. Each new
variable must be given a unique name and defined as a function which
uses the required parameters as input variables, spelled exactly as
they are defined above.
The new variable is then attached to an instance of the `mcmcsamples`
class using the `add_variable` function, which takes as arguments the
name of the new variable and the function defining it.
An example of this feature is in `examples/custom_variables.py` and
can be run as follows:
```bash
python -m examples.custom_variables
```
The output of this example should have two canvases which look as follows
## Changing Priors
Priors for parameters can be changed automatically when making plots.
A list of new priors is passed when adding a new `plot` to the `plotstack`.
This feature currently only works in 1D and with Uniform or Gaussian priors
in a limited set of transformations of variables. The list of currently
available transformations is:
```
x
sin(x)
sin^2(x)
cos(x)
cos^2(x)
2x
sin(2x)
sin^2(2x)
cos(2x)
cos^2(2x)
exp(-ix)
```
For example, an input chain that has a prior set to be uniform in DeltaCP can
have the following passed to the input chain to make plots with a prior uniform
in $\sin\delta_{CP}$:
```
["Uniform:sin(DeltaCP)"]
```
Examples of this in practice are in the `custom_variables` example.
## Plotting
Plots can be drawn directly from the `plotstack` (shown in the `custom_variables`
example), where the arrangement of pdfs or intervals is done algorithmically.
For more control, the figure and its subdivisions can be arranged by the user
and each plot drawn individually. An example of the latter is shown in both the
`simpleplots` example, and in the `plot_triangle` example, which creates a standard
triangle (corner) plot with the mass ordering separated. This example can be run as
follows:
```bash
python -m examples.plot_triangle -f examples/testchaindata.root -c mcmc
```
or
```bash
plot_triangle -f examples/testchaindata.root -c mcmc
```
if installed throgh pip, which produces the output below.
Raw data
{
"_id": null,
"home_page": null,
"name": "numcmctools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Asher Kaboth <Asher.Kaboth@rhul.ac.uk>, Artur Sztuc <a.sztuc@ucl.ac.uk>",
"keywords": "neutrino, physics, HEP, MCMC, plotting",
"author": null,
"author_email": "Asher Kaboth <Asher.Kaboth@rhul.ac.uk>, Artur Sztuc <a.sztuc@ucl.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/b9/01/09881e50cb5ee075f99be886ecc22f338acda6b9f6cd7400ef9dd2c31e6d/numcmctools-1.0.0.tar.gz",
"platform": null,
"description": "# NuMCMCTools\n\nThis package is intended as a lightweight tool to assist in analysis using \npublic releases of MCMC chains from neutrino oscillation analyses. The\nfollowing experiments have released data compatible with this software:\n\n* Experiment 1\n* Experiment 2\n\n## Installation\n\nTo install `numcmctools` with PyPI, run the following command:\n\n```bash\npip install numcmctools\n```\n\nTo install directly from source, first clone numcmctools with git:\n\n```bash\ngit clone https://github.com/NuMCMCTools/NuMCMCTools.git\n```\n\nenter the new NuMCMCTool directory and simply run:\n\n```bash\npip install .\n```\n\nThe pacakge does not need to be installed to use it, you can simply `git clone`\nthe package and add your own macros that include the `numcmcmtools` folder.\n\n## File Format\n\nThe expected input format for this code is a ROOT file containing at\nleast one TTree. The tree can have any name. Inside the tree, there\nwill be at least six branches called:\n\n* DeltaCP, in radians, across any $2\\pi$ interval\n* Theta13, in radians, [0, $\\pi$/2]\n* Theta23, in radians, [0, $\\pi$/2]\n* Theta12, in radians, [0, $\\pi$/2]\n* Deltam2_32, in $\\text{eV}^2$\n* Deltam2_21, in $\\text{eV}^2$\n\nwhich correspond to the standard parameters of neutrino mixing; the\nfirst four are the PMNS angles, and the last two are the mass\nsplittings. For more information on the parameterization see the [PDG\nreview on neutrino mixing](https://pdg.lbl.gov/2024/web/viewer.html?file=../reviews/rpp2024-rev-neutrino-mixing.pdf).\n\nEach parameter has some prior set by the original analyzers. The\nformat of this information is a TList containing a TNamed for each branch, \nwhich specifies the name of the branch and its prior. \n\nThe priors are specified as either `Uniform` or `Gaussian(mean, sigma)`.\nThere is then a further specification as to which variable the functional form\napplies to. For example, a specification of\n\n``` Theta23 Uniform:sin^2(Theta23)```\n\nindicates that the prior for Theta23 is uniform in $\\sin^2\\theta_{23}$.\n\nThe file additionally contains a citation to the original analysis that\nproduced the chain.\n\nThere may be additional information contained in the file; please see\nthe data release from the particular analysis for more detail.\n\nIn this code, the class `mcmcsamples` is responsible for loading\nin the required information from the file. The constructor takes the\nfilepath for the input file and the name of the oscillation parameters\ntree, and an optional argument for additional variables to be loaded.\n\nAn example tree (`examples/testchaindata.root`) with the required\nfeatures is provided for testing the functionality of this software.\n\nA very basic script for loading the example tree is\n`examples/load_mcmc.py` and can be run as follows:\n\n```bash\n python -m examples.load_mcmc\n```\n\n## Posterior Density Functions and Contours\n\nAfter the tree is loaded, an instance of `plotstack` can be created,\nwhich is initialized with an `mcmcsamples` instance. Individual\n`plot`s can be added to the plot stack. One and two dimensional plots\nare currently supported.\n\nA plot is added to the plot stack with the `add_plot` function, which\ntakes as arguments an array of the name(s) of the variables to be\nplotted as strings, any change in priors to be applied (see section below for details),\nthe bins and axis ranges for the plots, as defined in\n[numpy.histogram](https://numpy.org/doc/stable/reference/generated/numpy.histogram.html)\nor\n[numpy.histogram2d](https://numpy.org/doc/stable/reference/generated/numpy.histogram2d.html),\nand finally whether to treat the two mass orderings separately\n(`True`) or together (`False`, default).\n\nAny number of plots can be added to the stack. When all plots are\ncreated, they can be filled by calling `fill_plots`, which has two\noptional arguments. The first causes only the first\n`n_steps` to be filled from the tree; this is useful in testing the\nplot stack for very large input trees; the second restricts the number\nof steps read from the tree to be `batchsize` at any given time, which\nis helpful for memory management. Above a batch size of approximately\n100000, there is no performance impact on the time it takes to read\nlarge trees and fill plots; this value is therefore set at the\ndefault. The number of plots to be filled does have an impact on the run\ntime of the code.\n\nAfter the histograms are filled, they are normalized to create\nprobability _density_ functions, such that individual bins are\nnormalized to the width/area of the bin and the integral is normalized\nto 1.\n\nCredible intervals can be created by calling `make_intervals`\non either the plot stack or individual plots within the stack. The\nfunction takes an array of credible interval levels.\n\nPDFs and intervals can be drawn with `draw_plot` and `draw_interval`\nrespectively, and can take an `Figure` argument from matplotlib. When\ndividing a figure into subfigures, use the `subfigures` command, rather\nthan `subplots`, as `subplots` is used internally.\n\nThe plot stack can also be used to automatically draw all of the plots\nin the stack, choosing the optimal dimensions for the subfigure array.\n\nAn example of the plotting features is in `examples/simpleplots.py` and\ncan be run as follows:\n\n```bash\n python -m examples.simpleplots\n```\n\nThe output of this example should look as follows\n\n\n\n## Derived Variables\n\nVariables derived from the six required parameters\u2014for example,\n$\\sin^2\\theta_{23}$-can be defined and used for plotting. Each new\nvariable must be given a unique name and defined as a function which\nuses the required parameters as input variables, spelled exactly as\nthey are defined above.\n\nThe new variable is then attached to an instance of the `mcmcsamples`\nclass using the `add_variable` function, which takes as arguments the\nname of the new variable and the function defining it.\n\nAn example of this feature is in `examples/custom_variables.py` and\ncan be run as follows:\n\n```bash\n python -m examples.custom_variables\n```\n\nThe output of this example should have two canvases which look as follows\n\n\n\n\n## Changing Priors\n\nPriors for parameters can be changed automatically when making plots.\nA list of new priors is passed when adding a new `plot` to the `plotstack`.\nThis feature currently only works in 1D and with Uniform or Gaussian priors\nin a limited set of transformations of variables. The list of currently\navailable transformations is:\n\n```\nx\nsin(x)\nsin^2(x)\ncos(x)\ncos^2(x)\n2x\nsin(2x)\nsin^2(2x)\ncos(2x)\ncos^2(2x)\nexp(-ix)\n```\n\nFor example, an input chain that has a prior set to be uniform in DeltaCP can\nhave the following passed to the input chain to make plots with a prior uniform\nin $\\sin\\delta_{CP}$:\n\n```\n[\"Uniform:sin(DeltaCP)\"]\n```\n\nExamples of this in practice are in the `custom_variables` example.\n\n## Plotting\n\nPlots can be drawn directly from the `plotstack` (shown in the `custom_variables` \nexample), where the arrangement of pdfs or intervals is done algorithmically. \nFor more control, the figure and its subdivisions can be arranged by the user\nand each plot drawn individually. An example of the latter is shown in both the\n`simpleplots` example, and in the `plot_triangle` example, which creates a standard\ntriangle (corner) plot with the mass ordering separated. This example can be run as \nfollows:\n\n```bash\n python -m examples.plot_triangle -f examples/testchaindata.root -c mcmc \n```\n\nor \n\n```bash\n plot_triangle -f examples/testchaindata.root -c mcmc \n```\nif installed throgh pip, which produces the output below.\n\n\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 NuMCMCTools 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. ",
"summary": "MCMC plotting framework for official results from neutrino oscillation experiments",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/NuMCMCTools/NuMCMCTools/blob/main/README.md",
"Homepage": "https://github.com/NuMCMCTools/NuMCMCTools",
"Issues": "https://github.com/NuMCMCTools/NuMCMCTools/issues",
"Repository": "https://github.com/NuMCMCTools/NuMCMCTools.git"
},
"split_keywords": [
"neutrino",
" physics",
" hep",
" mcmc",
" plotting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ab75d4104f3430cb689509d7f13fef4837255d0977ebf28a55f86693b67f76c2",
"md5": "e0edae9377dfa05999c01527a70711da",
"sha256": "600b204214bb1fc4acf8fb89c0b50158f380954dd00609160aca6c08124547aa"
},
"downloads": -1,
"filename": "numcmctools-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e0edae9377dfa05999c01527a70711da",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 30069448,
"upload_time": "2024-10-17T16:11:52",
"upload_time_iso_8601": "2024-10-17T16:11:52.445860Z",
"url": "https://files.pythonhosted.org/packages/ab/75/d4104f3430cb689509d7f13fef4837255d0977ebf28a55f86693b67f76c2/numcmctools-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b90109881e50cb5ee075f99be886ecc22f338acda6b9f6cd7400ef9dd2c31e6d",
"md5": "c65bf962d637a381ee13aa17a1e1dd18",
"sha256": "bc693fa357b7b5b67125fbc17db8bbadecfb1c60bc15586daaf691d281fc0afa"
},
"downloads": -1,
"filename": "numcmctools-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c65bf962d637a381ee13aa17a1e1dd18",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 30071041,
"upload_time": "2024-10-17T16:12:08",
"upload_time_iso_8601": "2024-10-17T16:12:08.313346Z",
"url": "https://files.pythonhosted.org/packages/b9/01/09881e50cb5ee075f99be886ecc22f338acda6b9f6cd7400ef9dd2c31e6d/numcmctools-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-17 16:12:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NuMCMCTools",
"github_project": "NuMCMCTools",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "uproot",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "tqdm",
"specs": []
},
{
"name": "sympy",
"specs": []
}
],
"lcname": "numcmctools"
}
