SPEARHEAD VDA tool

• SPEARHEAD VDA tool
  • About
  • How to install
  • How to use
  • Example output
  • What's new in v1.2.0
  • Documentation
  • Contributing
  • Acknowledgement

About

The VDA tool helps in the automation of Velocity Dispersion Analysis (VDA) of one or multiple Solar Energetic Particle (SEP) events. The events are provided to the tool as datetime ranges or reference times, from a file or entered in the Notebook. The user can parameterize the given Notebook and control the spacecraft whose data are used (Solar Orbiter, STEREO-A, Parker Solar Probe, SOHO, Wind or BepiColombo), which particle species are used, the sensor from which they are detected, the viewings to be considered, and the background window of each event.

The tool has three notebooks: vda_multi_event.ipynb, the VDA of one or more events from one spacecraft, vda_multi_spacecraft.ipynb, the VDA of one event from several spacecraft, with their VDA fits in one plot, and vda_custom_points.ipynb, the VDA fit of onset points given by the user, in groups such as one per spacecraft.

The tool utilizes the Pandas module and generates multiple DataFrames during its execution. The final output of the tool is the release time and apparent path length of each inputted event, with a plot of its VDA analysis.

Tested in Ubuntu with Python 3.11 to 3.14, and MacOS 15.1.1 with Python 3.12.8

How to install

Access online (JupyterHub)

You can access the complete VDA 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.11) installation. Following SunPy's approach, we recommend installing Python via miniforge (click for instructions).
2. Open a terminal or the miniforge prompt, create a new virtual environment (e.g., conda create --name vda python=3.12) and activate it (e.g., conda activate vda).
3. Install the tool and its dependencies from PyPI with pip install "spearhead-vda[notebook]"
4. Download the notebooks and their example files into a folder of your choice (here vda) with spearhead-vda-notebooks vda, and move to it with cd vda
5. Open a Jupyter Notebook by running jupyter-lab vda_multi_event.ipynb (or jupyter-lab vda_multi_spacecraft.ipynb, jupyter-lab vda_custom_points.ipynb)

Install from the repository

To use the latest code of the repository or change it:

1. Download this file and extract to a folder of your choice (or clone the repository https://github.com/spearhead-he/VDA if you know how to use git).
2. Open a terminal or the miniforge prompt and move to the directory where the code is.
3. Create a new virtual environment (e.g., conda create --name vda python=3.12) and activate it (e.g., conda activate vda).
4. Install the tool and its dependencies with pip install -e ".[notebook]" (or, equivalently, pip install -r requirements.txt)
5. Open the Jupyter Notebook by running jupyter-lab vda_multi_event.ipynb (or jupyter-lab vda_multi_spacecraft.ipynb, jupyter-lab vda_custom_points.ipynb)

How to use

Open the Notebook vda_multi_event.ipynb and run its cells in order: a setup cell, a form with all the parameters (tabs Events, Data, Energy channels, Onsets and Views/Plots), and one cell per step of the analysis:

from spearhead.vda.notebook import VDA_notebook
tool = VDA_notebook()

tool.parameters_form()       # all the parameters
tool.run_data()              # events, data download and grouping of the energy channels
tool.background_selection()  # background window of each event
tool.run_onsets()            # onsets, and their selection
tool.run_vda()               # results and plots

The events are given with a .csv file (datetime ranges or reference times, see the examples) or entered in the form. See the user guide for details.

The Notebook vda_multi_spacecraft.ipynb has the same cells, with VDA_multi_spacecraft_notebook instead of VDA_notebook, for one event and several spacecraft (see the user guide). The Notebook vda_custom_points.ipynb has a form with the onset points (or a points file, see the example) and the VDA step (see the user guide).

Example output

The VDA plots of the notebooks with their default parameters and example data.

vda_multi_event.ipynb: the default event (2021-10-28) from Solar Orbiter, with the onsets of the proton channels as circles and of the electron channels as stars, and the release time and apparent path length (APL) of the VDA fit.

vda_multi_spacecraft.ipynb: the same event from Solar Orbiter, STEREO-A and SOHO, with the VDA fit of each spacecraft extended to inverse beta 0.

vda_custom_points.ipynb: the example points of the 2024-11-21 event (examples/custom_points_example.csv) seen by SOHO, STEREO-A and Solar Orbiter, with reference times at inverse beta 0.

What's new in v1.2.0

• The release time at the Sun and the time its light reaches 1 AU are given in the printed results, the results table and the VDA plots. The VDA plots have a legend of the symbols and a table of the results, and every fit starts at inverse beta 0.
• The apparent path length (APL) is in AU. It was too large by the factor 1 / distance of the observer from the Sun.
• Resampled data are timestamped at the centre of their bins, so the release times are half a bin later (2.5 minutes for the default 5 minutes).
• Each reference time has an observer (Earth, a spacecraft, or its distance from the Sun in AU), and is shown at the Sun.
• Warnings for VDA fits that are not physical: an APL that is not positive or is shorter than the distance of the observer from the Sun, or a release after the earliest onset.
• vda.run() runs the analysis in scripts, from the events to the VDA fits.
• Clearer and quieter messages: errors before the download, one line per event in the data step, and a clear error for Solar Orbiter without data on SOAR.

See the changelog for all the changes, and how to upgrade from previous versions.

Documentation

• User guide: the Notebooks, the spacecraft and their instruments, the parameters, the events files, background windows, onset selection, results, multiple spacecraft and custom points
• Using the VDA tool without the notebook: the analysis code in scripts
• Development: installation for development, the tests and the baseline image of the VDA plot
• Changelog

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.