From cb6007cf9788641ab98e50199070078fa4c26cbf Mon Sep 17 00:00:00 2001 From: Christian Palmroos <50318651+Christian-Palmroos@users.noreply.github.com> Date: Mon, 16 Dec 2024 17:44:42 +0200 Subject: [PATCH] Update README.md --- README.md | 45 +++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5feb48a..47f758e 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,38 @@ -# The bowtie analysis tool ---- +# SPEARHEAD bowtie analysis tool + +- [About](#about) +- [How to install](#how-to-install) +- [How to use](#how-to-use) +- [Contributing](#contributing) +- [Acknowledgement](#acknowledgement) + +## About This analysis tool runs bowtie analysis for particle instruments' energy channels. The input is a csv table of channel responses indexed by the incident energy. The results of analysis are the geometric factor (with errors) and the effective energy of the channel. +*Tested in Ubuntu 20.04.6 LTS with Python version 3.12.8.* + +## How to install + +1. This tool requires a recent Python (>=3.10) installation. [Following SunPy's approach, we recommend installing Python via miniforge (click for instructions).](https://docs.sunpy.org/en/stable/tutorial/installation.html#installing-python) +2. [Download this file](https://github.com/spearhead-he/bowtie/archive/refs/heads/main.zip) and extract to a folder of your choice (or clone the repository [https://github.com/spearhead-he/bowtie](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. *(Optional, but recommended)* Create a new virtual environment (e.g., `conda create --name bowtie`, 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` +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 on how to run bowtie analysis with this package. + The package operates with two main classes, which are called `Bowtie` and `Spectra`. `Bowtie` stores response functions and contains the methods to run bowtie analysis, while `Spectra` contains the information of the spectral indices and the amount of different spectra that are used in the bowtie calculation. -Bowtie +### Bowtie --- The `Bowtie` class contains the data that the bowtie analysis is applied on, and the energy range to be considered in the calculations. Its methods make running analysis easy and straightforward. @@ -32,7 +54,7 @@ Methods: spectra : {Spectra} See bowtie_analysis(). plot : {bool} See bowtie_analysis() -Spectra +### Spectra --- The `Spectra` class contains the range of spectra that are applied on the response function to run bowtie analysis. @@ -46,3 +68,18 @@ Methods: 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](https://github.com/spearhead-he/bowtie/issues) to report bugs and request new features or [pull requests](https://github.com/spearhead-he/bowtie/pulls) to submit new code. + +If you don't have a GitHub account, you can [sign-up for free here](https://github.com/signup), 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.