# Flux-Tool
[](https://pypi.org/project/flux-tool/)
[](https://www.python.org/)
[](https://github.com/apwood-physics/flux-tool/blob/main/LICENSE)
This package reads neutrino flux universes produced by Package to Predict the Flux (PPFX), and extracts a neutrino flux prediction with corresponding uncertainties.
All analysis products are output to a `.root` file specified in a `config.toml`. The package will also produce figures as `pdf`, `png`, and a `.tex`, for the majority of the products stored in the ROOT file.
## Prerequisites
Before you begin, make sure you have the following prerequisites installed:
- Python 3.11 or later: Visit the official Python website at https://www.python.org/downloads/ to download and install the latest version of Python.
- ROOT 6.28 or later: **Flux-Tool** requires ROOT/PyROOT version 6.28 or later. You can obtain ROOT from the official ROOT website at https://root.cern/install/.
## Installation
**Flux-Tool** is available for installation from PyPI, the Python Package Index. Follow the steps below to install the project:
1. Open your terminal or command prompt.
2. Create a virtual environment (optional but recommended):
```bash
$ python -m venv myenv
```
3. Activate the virtual environment:
```bash
$ source myenv/bin/activate
```
4. Install **Flux-Tool** using pip:
```bash
$ pip install flux-tool
```
## Usage
```shell
$ flux_tool -h
usage: flux_uncertainties [-h] [-c CONFIG] [-p PRODUCTS_FILE] [-v] [-z] [--example-config]
This package coerces PPFX output into a neutrino flux prediction with uncertainties, and stores various spectra related to the
flux, e.g., fractional uncertainties, covariance matrices, etc.
options:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG
specify the path to a toml configuration file
-p PRODUCTS_FILE, --plots-only PRODUCTS_FILE
Specify path to an existing ROOT file for which to produce plots
-v, --verbose
-z, --enable-compression
Enable compression of the output plots directory
--example-config Print an example configuration file
```
Alternatively, this package can be imported directly into an existing python script:
```python
import flux_tool
```
### Example `config.toml`
```toml
# flux_tool configuration file
output_file_name = "out.root"
[Inputs]
directory = "/path/to/directory/containing/input/histograms"
fhc.nominal = "input_fhc_nominal.root"
rhc.nominal = "input_rhc_nominal.root"
fhc.horn_current_up = "input_fhc_horn_current_up.root"
fhc.horn_current_down = "input_fhc_horn_current_down.root"
[Binning]
# Histogram bin edges for each neutrino flavor.
# Accepts:
# 1. an integer number of bins (between 0 and 20 GeV)
# 2. An array of bin edges (NOTE: they can be variable bin widths, but must be monotonically increasing)
# 3. If unspecified, then fixed bin widths of 100 MeV is applied along the [0, 20] GeV interval.
nue = 200
nuebar = [
0.0,
0.2,
0.4,
0.6,
0.8,
1.0,
1.5,
2.0,
2.5,
3.0,
3.5,
4.0,
6.0,
8.0,
12.0,
]
numu = []
numubar = [
0.0,
0.2,
0.4,
0.6,
0.8,
1.0,
1.5,
2.0,
2.5,
3.0,
3.5,
4.0,
6.0,
8.0,
12.0,
20.0
]
[PPFX]
# enable/disable specific PPFX reweight categories from
# appearing in the fractional uncertainty directory
# true = included, false = excluded
[PPFX.enabled]
total = true
attenuation = true
mesinc = true
mesinc_parent_K0 = true
mesinc_parent_Km = true
mesinc_parent_Kp = true
mesinc_parent_pim = true
mesinc_parent_pip = true
mesinc_daughter_K0 = true
mesinc_daughter_Km = true
mesinc_daughter_Kp = true
mesinc_daughter_pim = true
mesinc_daughter_pip = true
mippnumi = false
nua = true
pCfwd = false
pCk = true
pCpi = true
pCnu = true
pCQEL = false
others = true
thintarget = false
[Plotting]
draw_label = true # whether or not to draw the experiment label, e.g., ICARUS Preliminary
experiment = "ICARUS"
stage = "Preliminary"
neutrino_energy_range = [0.0, 6.0] # horizontal axis limits in [GeV]
[Plotting.enabled]
# Enable/disable specific plots from the visualization output
uncorrected_flux = true
flux_prediction = true
flux_prediction_parent_spectra = true
flux_prediction_parent_spectra_stacked = true
ppfx_universes = true
hadron_uncertainties = true
hadron_uncertainties_meson = true
hadron_uncertainties_meson_only = true
pca_scree_plot = true
pca_mesinc_overlay = true
pca_top_components = true
pca_variances = true
pca_components = true
hadron_covariance_matrices = "total" # Can specify the exact name instead of drawing all of the matrices.
hadron_correlation_matrices = true
beam_uncertainties = true
beam_covariance_matrices = true
beam_correlation_matrices = true
beam_systematic_shifts = true
```
## Contents of the Output ROOT File
## `beam_samples`
If provided to `flux_tool`, copies of the systematically altered neutrino flux samples, including the nominal, are stored here.
## `beam_systematic_shifts`
Fractional shifts from the nominal, calculated for each flux sample in `beam_samples`.
## `covariance_matrices`
Contains all covariance and correlation matrices, organized into two subdirectories: one for `hadron` effects and another for `beam` effects (if applicable). Each covariance matrix is stored in 2 forms:
1. `TH2D` (prefixed `hcov_` or `hcorr_`)
2. `TMatrixD`(prefixed `cov_` or `corr_`)
Covariance matrices with the `_abs` suffix are in absolute units of the flux, whereas those without the suffix are normalized the PPFX universe mean, in the case of hadron systematics, or to the nominal beam run, in the case of the beam line systematics.
Each bin is labeled according to the combination of horn polarity, neutrino flavor, and energy bin number, e.g., `fhc-nue-1`.
## `flux_prediction`
This directory holds a set of `TH1D` for each neutrino mode. The flux value is
extracted as the PPFX mean, while the uncertainties incorporate statistical,
hadron systematic, and beam line systematic (if applicable) uncertainties.
## `fractional_uncertainties`
This directory contains two subdirectories, `beam` and `hadron`, containing the fractional contributions to the flux uncertainty for each effect.
## `pca`/
This directory houses the outputs of the Principal Component Analysis of the hadron covariance matrix.
- `eigenvectors/hevec_*` Unit eigenvectors
- `principal_components/hpc_*` principal components scaled by the square root of the corresponding eigenvalue and transposed into bins of neutrino energy
- `hcov_pca` reconstructed hadron covariance matrix used for validation purpose.
- `heigenvals` Each bin of this histogram (`TH2D`) holds the eigenvalues extracted
from the PCA
- `heigenvals_frac` same as the previous, but each eigenvalue is divided by
the sum of all eigenvalues such that each eigenvalue is represented as its contribution to the total variance.
## `ppfx_corrected_flux`
Directory containing the PPFX-corrected neutrino spectra. These histograms
are produced by calculating the means and sigmas of the flux distributions across
the 100 universes contained in `ppfx_output`.
## `ppfx_flux_weights`
Directory containing `TH1D` for each horn-neutrino flavor combination, the bins of which contain weights that can be used to apply the PPFX flux correction.
## `ppfx_output`
Contains the original output received from PPFX, organized into two subdirectories corresponding to Forward Horn Current (FHC) and Reverse Horn Current (RHC). Each contains a `nom` subdirectory which holds the nominal (uncorrected) neutrino flux vs. energy spectrum, `hnom_nu*`, in addition to the PPFX central value, `hcv_nu`. Spectra broken down by parent hadron can be found under the `parent` subdirectory. The remaining subdirectories hold the universes for each hadron production
systematic:
## `statistical_uncertainties`
Directory containing statistical uncertainties for every horn-neutrino flavor combination. Histograms with the suffix `_abs` are in absolute units of the flux, and those without the suffix are in the fractional scale. The two matrices, `hstatistical_uncertainty_matrix` and `statistical_uncertainty_matrix`, are diagonal `TH2D` and `TMatrixD`, respectively, organizing the statistical uncertainties into a useful form to be added with covariance matrices.
## `corr_total`
`TMatrixD` correlation matrix incorporating all sources of uncertainty
## `cov_total_abs`
`TMatrixD` covariance matrix in units of the flux, incorporating all sources of uncertainty
## `hcorr_total`
`TH2D` correlation matrix incorporating all sources of uncertainty
## `hcov_total_abs`
`TH2D` covariance matrix in units of the flux, incorporating all sources of uncertainty
## `matrix_axis`
`TAxis` with the binning and labels of all matrix axes
## `xaxis_variable_bins`
`TAxis` containing the binning applied to all spectra w.r.t. $E_\nu$ in GeV.
Raw data
{
"_id": null,
"home_page": "https://github.com/apwood-physics/flux-tool",
"name": "flux_tool",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Anthony Wood",
"author_email": "apwood@uh.edu",
"download_url": "https://files.pythonhosted.org/packages/76/59/79b9d8a6689fcc6ead0aaafa103116971893382fa94061d839ee789f4c68/flux_tool-1.3.0.tar.gz",
"platform": null,
"description": "# Flux-Tool\n[](https://pypi.org/project/flux-tool/)\n[](https://www.python.org/)\n[](https://github.com/apwood-physics/flux-tool/blob/main/LICENSE)\n\nThis package reads neutrino flux universes produced by Package to Predict the Flux (PPFX), and extracts a neutrino flux prediction with corresponding uncertainties.\nAll analysis products are output to a `.root` file specified in a `config.toml`. The package will also produce figures as `pdf`, `png`, and a `.tex`, for the majority of the products stored in the ROOT file.\n## Prerequisites\n\nBefore you begin, make sure you have the following prerequisites installed:\n\n- Python 3.11 or later: Visit the official Python website at https://www.python.org/downloads/ to download and install the latest version of Python.\n- ROOT 6.28 or later: **Flux-Tool** requires ROOT/PyROOT version 6.28 or later. You can obtain ROOT from the official ROOT website at https://root.cern/install/.\n\n## Installation\n\n**Flux-Tool** is available for installation from PyPI, the Python Package Index. Follow the steps below to install the project:\n\n1. Open your terminal or command prompt.\n\n2. Create a virtual environment (optional but recommended):\n ```bash\n $ python -m venv myenv\n ```\n3. Activate the virtual environment:\n ```bash\n $ source myenv/bin/activate\n ```\n4. Install **Flux-Tool** using pip:\n ```bash\n $ pip install flux-tool\n ```\n## Usage\n```shell\n$ flux_tool -h\nusage: flux_uncertainties [-h] [-c CONFIG] [-p PRODUCTS_FILE] [-v] [-z] [--example-config]\n\nThis package coerces PPFX output into a neutrino flux prediction with uncertainties, and stores various spectra related to the\nflux, e.g., fractional uncertainties, covariance matrices, etc.\n\noptions:\n -h, --help show this help message and exit\n -c CONFIG, --config CONFIG\n specify the path to a toml configuration file\n -p PRODUCTS_FILE, --plots-only PRODUCTS_FILE\n Specify path to an existing ROOT file for which to produce plots\n -v, --verbose\n -z, --enable-compression\n Enable compression of the output plots directory\n --example-config Print an example configuration file\n```\n\nAlternatively, this package can be imported directly into an existing python script:\n\n```python\nimport flux_tool\n```\n\n### Example `config.toml`\n```toml\n# flux_tool configuration file\n\noutput_file_name = \"out.root\"\n\n[Inputs]\ndirectory = \"/path/to/directory/containing/input/histograms\"\nfhc.nominal = \"input_fhc_nominal.root\"\nrhc.nominal = \"input_rhc_nominal.root\"\nfhc.horn_current_up = \"input_fhc_horn_current_up.root\"\nfhc.horn_current_down = \"input_fhc_horn_current_down.root\"\n\n\n[Binning]\n# Histogram bin edges for each neutrino flavor.\n# Accepts:\n# 1. an integer number of bins (between 0 and 20 GeV)\n# 2. An array of bin edges (NOTE: they can be variable bin widths, but must be monotonically increasing)\n# 3. If unspecified, then fixed bin widths of 100 MeV is applied along the [0, 20] GeV interval.\nnue = 200\nnuebar = [\n 0.0,\n 0.2,\n 0.4,\n 0.6,\n 0.8,\n 1.0,\n 1.5,\n 2.0,\n 2.5,\n 3.0,\n 3.5,\n 4.0,\n 6.0,\n 8.0,\n 12.0,\n]\nnumu = []\nnumubar = [\n 0.0,\n 0.2,\n 0.4,\n 0.6,\n 0.8,\n 1.0,\n 1.5,\n 2.0,\n 2.5,\n 3.0,\n 3.5,\n 4.0,\n 6.0,\n 8.0,\n 12.0,\n 20.0\n]\n\n [PPFX]\n# enable/disable specific PPFX reweight categories from\n# appearing in the fractional uncertainty directory\n# true = included, false = excluded\n[PPFX.enabled]\ntotal = true\nattenuation = true\nmesinc = true\nmesinc_parent_K0 = true\nmesinc_parent_Km = true\nmesinc_parent_Kp = true\nmesinc_parent_pim = true\nmesinc_parent_pip = true\nmesinc_daughter_K0 = true\nmesinc_daughter_Km = true\nmesinc_daughter_Kp = true\nmesinc_daughter_pim = true\nmesinc_daughter_pip = true\nmippnumi = false\nnua = true\npCfwd = false\npCk = true\npCpi = true\npCnu = true\npCQEL = false\nothers = true\nthintarget = false\n\n[Plotting]\ndraw_label = true # whether or not to draw the experiment label, e.g., ICARUS Preliminary\nexperiment = \"ICARUS\"\nstage = \"Preliminary\"\nneutrino_energy_range = [0.0, 6.0] # horizontal axis limits in [GeV]\n\n[Plotting.enabled]\n# Enable/disable specific plots from the visualization output\nuncorrected_flux = true\nflux_prediction = true\nflux_prediction_parent_spectra = true\nflux_prediction_parent_spectra_stacked = true\nppfx_universes = true\nhadron_uncertainties = true\nhadron_uncertainties_meson = true\nhadron_uncertainties_meson_only = true\npca_scree_plot = true\npca_mesinc_overlay = true\npca_top_components = true\npca_variances = true\npca_components = true\nhadron_covariance_matrices = \"total\" # Can specify the exact name instead of drawing all of the matrices.\nhadron_correlation_matrices = true\nbeam_uncertainties = true\nbeam_covariance_matrices = true\nbeam_correlation_matrices = true\nbeam_systematic_shifts = true\n```\n\n## Contents of the Output ROOT File\n\n## `beam_samples`\nIf provided to `flux_tool`, copies of the systematically altered neutrino flux samples, including the nominal, are stored here.\n## `beam_systematic_shifts`\nFractional shifts from the nominal, calculated for each flux sample in `beam_samples`.\n## `covariance_matrices`\nContains all covariance and correlation matrices, organized into two subdirectories: one for `hadron` effects and another for `beam` effects (if applicable). Each covariance matrix is stored in 2 forms:\n1. `TH2D` (prefixed `hcov_` or `hcorr_`)\n2. `TMatrixD`(prefixed `cov_` or `corr_`)\nCovariance matrices with the `_abs` suffix are in absolute units of the flux, whereas those without the suffix are normalized the PPFX universe mean, in the case of hadron systematics, or to the nominal beam run, in the case of the beam line systematics.\nEach bin is labeled according to the combination of horn polarity, neutrino flavor, and energy bin number, e.g., `fhc-nue-1`.\n## `flux_prediction`\nThis directory holds a set of `TH1D` for each neutrino mode. The flux value is\nextracted as the PPFX mean, while the uncertainties incorporate statistical,\nhadron systematic, and beam line systematic (if applicable) uncertainties.\n## `fractional_uncertainties`\nThis directory contains two subdirectories, `beam` and `hadron`, containing the fractional contributions to the flux uncertainty for each effect.\n## `pca`/\nThis directory houses the outputs of the Principal Component Analysis of the hadron covariance matrix.\n- `eigenvectors/hevec_*` Unit eigenvectors\n- `principal_components/hpc_*` principal components scaled by the square root of the corresponding eigenvalue and transposed into bins of neutrino energy\n- `hcov_pca` reconstructed hadron covariance matrix used for validation purpose.\n- `heigenvals` Each bin of this histogram (`TH2D`) holds the eigenvalues extracted\nfrom the PCA\n- `heigenvals_frac` same as the previous, but each eigenvalue is divided by\nthe sum of all eigenvalues such that each eigenvalue is represented as its contribution to the total variance.\n## `ppfx_corrected_flux`\nDirectory containing the PPFX-corrected neutrino spectra. These histograms\nare produced by calculating the means and sigmas of the flux distributions across\nthe 100 universes contained in `ppfx_output`.\n## `ppfx_flux_weights`\nDirectory containing `TH1D` for each horn-neutrino flavor combination, the bins of which contain weights that can be used to apply the PPFX flux correction.\n## `ppfx_output`\nContains the original output received from PPFX, organized into two subdirectories corresponding to Forward Horn Current (FHC) and Reverse Horn Current (RHC). Each contains a `nom` subdirectory which holds the nominal (uncorrected) neutrino flux vs. energy spectrum, `hnom_nu*`, in addition to the PPFX central value, `hcv_nu`. Spectra broken down by parent hadron can be found under the `parent` subdirectory. The remaining subdirectories hold the universes for each hadron production\nsystematic:\n## `statistical_uncertainties`\nDirectory containing statistical uncertainties for every horn-neutrino flavor combination. Histograms with the suffix `_abs` are in absolute units of the flux, and those without the suffix are in the fractional scale. The two matrices, `hstatistical_uncertainty_matrix` and `statistical_uncertainty_matrix`, are diagonal `TH2D` and `TMatrixD`, respectively, organizing the statistical uncertainties into a useful form to be added with covariance matrices.\n## `corr_total`\n`TMatrixD` correlation matrix incorporating all sources of uncertainty\n## `cov_total_abs`\n`TMatrixD` covariance matrix in units of the flux, incorporating all sources of uncertainty\n## `hcorr_total`\n`TH2D` correlation matrix incorporating all sources of uncertainty\n## `hcov_total_abs`\n`TH2D` covariance matrix in units of the flux, incorporating all sources of uncertainty\n## `matrix_axis`\n`TAxis` with the binning and labels of all matrix axes\n## `xaxis_variable_bins`\n`TAxis` containing the binning applied to all spectra w.r.t. $E_\\nu$ in GeV.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Package used to study the output histograms from PPFX",
"version": "1.3.0",
"project_urls": {
"Homepage": "https://github.com/apwood-physics/flux-tool",
"Repository": "https://github.com/apwood-physics/flux-tool"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0d8202a41079ffd3e2b85401f38b482c0ad2d05af9baafb3a836178a1f2ce102",
"md5": "94997ca7352f4880b85b0a1ab6e78be6",
"sha256": "7e57e0a3822611e7d07f69fdf83d8f2ccd170d9bf7b6e6336bd6d2952b9bf49a"
},
"downloads": -1,
"filename": "flux_tool-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "94997ca7352f4880b85b0a1ab6e78be6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 48366,
"upload_time": "2024-09-10T19:54:59",
"upload_time_iso_8601": "2024-09-10T19:54:59.434864Z",
"url": "https://files.pythonhosted.org/packages/0d/82/02a41079ffd3e2b85401f38b482c0ad2d05af9baafb3a836178a1f2ce102/flux_tool-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "765979b9d8a6689fcc6ead0aaafa103116971893382fa94061d839ee789f4c68",
"md5": "5e9e962b4a10b3dd5f71cd5fddc56e6a",
"sha256": "88ad4d89e6deabfbe4c04d0881aa7aa546392c89e63b8ffd5a689ad58e5c7950"
},
"downloads": -1,
"filename": "flux_tool-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "5e9e962b4a10b3dd5f71cd5fddc56e6a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.11",
"size": 39383,
"upload_time": "2024-09-10T19:55:00",
"upload_time_iso_8601": "2024-09-10T19:55:00.673265Z",
"url": "https://files.pythonhosted.org/packages/76/59/79b9d8a6689fcc6ead0aaafa103116971893382fa94061d839ee789f4c68/flux_tool-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-10 19:55:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "apwood-physics",
"github_project": "flux-tool",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "flux_tool"
}
JSON
