SOLER SEP Tools

• About
• Installation
  • Update
• Usage
• Access online (JupyterHub)
• Contributing
• Citing
• Acknowledgement

About

This repository contains multiple Python tools for the analysis of Solar Energetic Particles (SEP). They are provided as Jupyter Notebooks that act as an interface to the actual software and also provide the necessary documentation. All tools can be either installed locally or accessed online without installation on SOLER's JupyterHub!

Installation

1. These tools require 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/soler-he/sep_tools 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 sep_tools python=3.12, or python -m venv venv_sep_tools if you don't use miniforge/conda).
5. Activate the just created virtual environment (e.g., conda activate sep_tools, or source venv_sep_tools/bin/activate if you don't use miniforge/conda).
6. If you don't have git installed (try executing it), install it with conda install conda-forge::git.
7. Install the Python dependencies from the requirements.txt file with pip install -r requirements.txt

Update

To update the tools to the latest version, just download this file and extract it. Note that changes that you made to the Notebooks will be overwritten if you extract into the same directory as used in the initial installation; in this case we recommend you make a copy of your edited version.

The tools are continuously updated with small changes. After bigger updates, release versions are tagged and indexed at Zenodo. You can see the latest release version in the right sidebar of the repository (above Contributors) or get a full list at soler-he/sep_tools/releases.

Usage

Activate the created virtual environment in the terminal (step 5. of Installation), go to the folder where the tools have been extracted to, and run jupyter-lab. This will open the default web-browser. There, open the .ipynb file of the specific tool:

• SEP_Fluence-Spectra.ipynb
  Determines and visualizes SEP energy spectra accumulated over a whole event duration
• SEP_Multi-Instrument-Plot.ipynb
  Makes multi-panel time-series plots of various different in-situ measurements, including also selected remote-sensing observations
• SEP_Multi-Spacecraft-Plot.ipynb
  Makes a plot of SEP intensity-time profiles combining observations by different spacecraft
• SEP_PADs-and-Anisotropy.ipynb
  Determines and visualizes SEP Pitch-Angle Distributions (PADs) and first-order anisotropies, including methods for background subtraction
• SEP_PyOnset.ipynb
  Determines SEP onset times and their uncertainties from in-situ intensity measurements using a hybrid Poisson-CUSUM-bootstrapping approach (see PyOnset for more details)
• SEP_Regression-Onset.ipynb
  Determines SEP onset times based on a regression method

If you are new to Jupyter Notebooks, the official documentation will give you more info about What is the Jupyter Notebook? and Running Code with it.

Access online (JupyterHub)

All tools can be accessed online without installation on SOLER's JupyterHub. You only need a (free) GitHub account for verification. Click on the Notebook file below to open the specific tool:

• SEP_Fluence-Spectra.ipynb
  Determines and visualizes SEP energy spectra accumulated over a whole event duration
• SEP_Multi-Instrument-Plot.ipynb
  Makes multi-panel time-series plots of various different in-situ measurements, including also selected remote-sensing observations
• SEP_Multi-Spacecraft-Plot.ipynb
  Makes a plot of SEP intensity-time profiles combining observations by different spacecraft
• SEP_PADs-and-Anisotropy.ipynb
  Determines and visualizes SEP Pitch-Angle Distributions (PADs) and first-order anisotropies, including methods for background subtraction
• SEP_PyOnset.ipynb
  Determines SEP onset times and their uncertainties from in-situ intensity measurements using a hybrid Poisson-CUSUM-bootstrapping approach (see PyOnset for more details)
• SEP_Regression-Onset.ipynb
  Determines SEP onset times based on a regression method

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.

Citing

To cite these tools, please obtain the citation from the corresponding Zenodo entry, where you can generate different citation styles on the bottom right of the page.

Acknowledgement

These tools are developed within the SOLER (Energetic Solar Eruptions: Data and Analysis Tools) project. SOLER has received funding from the European Union’s Horizon Europe programme under grant agreement No 101134999.

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.