SPEARHEAD bow-tie analysis tool

• About
• How to install
• How to use
• Contributing
• Acknowledgement

About

This analysis tool runs a bow-tie analysis (Van Allen et al. 1974) for the energy channels of a generic particle instrument. The input is a CSV table of channel responses indexed by the incident energy. The analysis results are the geometric factor (with errors) and the effective energy of the channel. The analysis description may be found here (A description of the BepiColombo/SIXS-P cruise phase data product). The instrument response may be obtained by simulation, analytical model, or measurement and presented as a discrete function on an energy grid. The only requirement is that the grid must be monotonously ascending.

Tested in Ubuntu 20.04.6 LTS with Python version 3.12.8.

How to install

Access online (JupyterHub)

You can access the complete bow-tie analysis tool online on the JupyterHub server of the SPEARHEAD project. All you need is a (free) GitHub account for verification. Access the tool by opening this link!

Install locally

1. This tool requires a recent Python (>=3.10) installation. Following SunPy's approach, we recommend installing Python via miniforge (click for instructions).
2. Download this file and extract to a folder of your choice (or clone the repository https://github.com/spearhead-he/bowtie if you know how to use git).
3. Open a terminal or the miniforge prompt and move to the directory where the code is.
4. Create a new virtual environment (e.g., conda create --name bowtie python=3.12 or python -m venv venv_bowtie_tool if you don't use miniforge/conda) and activate it (e.g., conda activate bowtie, or source venv_bowtie_tool/bin/activate if you don't use miniforge/conda).
5. Install the Python dependencies from the requirements.txt file with pip install -r requirements.txt within the virtual environment.
6. Open the Jupyter Notebook by running jupyter-lab bowtie_example.ipynb

How to use

The Notebook is a simple example that also acts as a tutorial to teach the user how to run the bow-tie analysis with this tool.

The instrument response function(s) must be stored in a CSV file. The first column is the midpoint of the energy bin. The next columns are the response functions of the particle instrument.

The tool operates with two main classes, which are called Bowtie and Spectra. Bowtie stores response functions and contains the methods to run bow-tie analysis, while Spectra contains information on the spectral indices and the amount of different spectra that are used in the bow-tie calculation.

Bowtie

The Bowtie class contains the data that the bow-tie analysis is applied to and the energy range to be considered in the calculations. Its methods make running analysis easy and straightforward.

Methods:

set_energy_range(energy_min, energy_max):
    energy_min : {float} The minimum energy in MeV to consider
    energy_max : {float} See energy_min.

bowtie_analysis(channel, spectra, plot):
    channel : {str} The channel name as it appears in the csv table.
    spectra : {Spectra} The Spectra class object, introduced in this package. Contains the 
                        spectral indices and the power law spectra used in the bow-tie analysis.
    plot : {bool} A boolean switch to produce a plot visualizing the analysis.

bowtie_analysis_full_stack(spectra, plot):
    A wrapper for bowtie_analysis(). Runs the analysis on all channels that appear in the input file.
    spectra : {Spectra} See bowtie_analysis().
    plot : {bool} See bowtie_analysis()

Spectra

The Spectra class contains the range of spectra that are applied on the response function to run bow-tie analysis.

Methods:

set_spectral_indices(gamma_min, gamma_max):
    gamma_min : {float} The minimum spectral index to consider in the calculation.
    gamma_max : {float} See gamma_min.

produce_power_law_spectra(response_df):
    response_df : {pandas.DataFrame} The input csv table read in to a pandas DataFrame. Contains
                                     the channel responses as a function of incident energy.

Contributing

Contributions to this tool are very much welcome and encouraged! Contributions can take the form of issues to report bugs and request new features or pull requests to submit new code.

If you don't have a GitHub account, you can sign-up for free here, or you can also reach out to us with feedback by sending an email to jan.gieseler@utu.fi.

Acknowledgement

This tool is developed within the SPEARHEAD (SPEcification, Analysis & Re-calibration of High Energy pArticle Data) project. SPEARHEAD has received funding from the European Union’s Horizon Europe programme under grant agreement No 101135044.

The tool reflects only the authors’ view and the European Commission is not responsible for any use that may be made of the information it contains.