The ANNA Framework

A framework designed to analyze the data measured by the single Water Cherenkov Detectors (WCD) of the LAGO detection network. It follows the LAGO hierarchycal structured for the measured data.

Request Feature · Report Bug · Contact us

Table of Contents

1. About ANNA
2. Getting Started
3. Usage
4. Proposed Features
5. Contributing
6. License
7. Contact

About ANNA

ANNA is a complete framework designed to analyse the data the signals produced by the secondary particles emerging from the interaction of singles, multiple and even the complete flux of primary cosmic rays with the atmosphere. These signals are measured for any particle detector located at a LAGO site.

ANNA is structured using different applications files and some headers where the main data classes are defined.

During its normal operation and the different maintenance modes of the LAGO detection network, LAGO produces datasets containing different types of data. All the LAGO datasets follow standardized schemes based on linked data as described in our DMP.

Measured data (Ln)

The measured data LAGO dataset corresponds to any type of data that was measured in a LAGO site, including measurements of any type of radiation, atmospheric conditions, geomagnetic, solar irradiation, telemetry, and any other type of measurement produced by the LAGO detector and its peripherals. The LAGO measured data includes also any data product derived by any means of the previously described data. All the LAGO measured datasets are hierarchically tagged with the L_n label, being n a sequential number, starting by 0, that indicates the level of data processing: L₀ corresponds to the raw data, L₁ is the first level of analysed data, etc.

ANNA main reference and citation

When using ANNA, please cite using the DOI included at the begininig of this file.

H. Asorey for the LAGO Collaboration, "The LAGO ANNA Data Analysis framework", version vM.m.p doi:10.5281/zenodo.8411282.

(back to top)

LAGO ANNA versions

Currently, two electronic boards are consistenly used across the LAGO detection network. Two different versions were developed for LAGO ACQUA, the LAGO data acquisition package. LAGO ANNA follows the same schema:

• LAGO ANNA v1.x.x: Compatible with LAGO ACQUA v1, for the electronic board based on the NEXYS-II FPGA. Current version is the last developed version, LAGO ACQUA v1.5.0. In general, LAGO ANNA v1 are compatible with data acquired using LAGO ACQUA v1.
• LAGO ANNA v2.x.x: Compatible with LAGO ACQUA v2, designed for the electronic board based on the RedPitaya StemLab 125/14 electronic board. This is currently under actively development.
• LAGO ANNA v3.x.x: This will be developed for the new LAGO EDGE detection schema.

Major versions for both the LAGO ACQUA and the LAGO ANNA frameworks are developed in different branchs and identified with the corresponding tags. Master branch always points to the latest stable development.

Getting Started

To get a local copy of the ANNA framework up and running follow these simple example steps.

Prerequisites

System requirements

ANNA runs in any Linux based system, including those supported at iOS, raspberry-pis' and RedPitayas' linux-based OS. For Windows user, we strongly recommend to install some of your preferred linux distribution using virtualbox.

The command for installing required packages depends on the OS architecture.

In Fedora, Scientific Linux and CentOS, use

sudo yum install <package>.

In Ubuntu/Debian, including RPi and RPy SBC, use

sudo apt install <package>.

In both cases, you can also use the graphic package manager included in your preferred distro.

ANNA requires the installation of a few and largerly common standard packages:

• bash
• gcc
• make
• screen
• rsync
• git

As a one-liner for Ubuntu/Debian:

sudo apt install build-essential screen rsync git

(git is optional).

Dependencies

ANNA does not have any dependencies.

Installation

1. If you are using git, just clone this repository:

   cd /path/to/ANNA/installation
   git clone https://github.com/lagoproject/anna.git

   Otherwise, you can also directly download ANNA without using git (in this case, you should reinstall ANNA for every upgrade):

   cd /path/to/ANNA/installation
   wget -c https://github.com/lagoproject/anna/archive/refs/heads/master.zip
   unzip master.zip
   rm master.zip

2. ANNA compiling is very simple:

   cd /path/to/ANNA/anna
   make

   1. During the first installation of ANNA (or if you need to install ANNA in a different directory), make will define the $LAGO_ANNA environment variable, that points to the ANNA current directory installation. Then, ANNA installer will add the definition of this variable to the user's local .bashrc and to the local $PATH environment variable:

      #
      ## Changes added by the ANNA suite on <installation date>
      #
      export ANNA="/path/to/ANNA/installation/ANNA"
      export LAGO_ANNA_VERSION="<LAGO ANNA current version>"
      export PATH="${ANNA}:$PATH"

If you follow the above described steps and everything works well, you should find some new executable files at the root ${LAGO_ANNA} directory.

(back to top)

ANNA updates, releases, branchs and tags

ANNA is continously used, revised and updated within the LAGO Collaboration.

Unless you are a developer, we recommend to use only the latest ANNA release contained in the master branch of this repository. Stable versions are tagged and can be found in the corresponding section of this repository.

Clone and install ANNA from dev or dev-* branches is strongly discouraged, as these branches are used for testing, bug correction and for the development of new features.

If you are using git, you can update ANNA just by doing:

cd /path/to/ANNA/anna
git pull
make

Otherwise, you could just reinstall ANNA by following the installation guide.

(back to top)

Usage

The ANNA framework follows the basic hierarchical structure of the LAGO Measured data. It includes two basic applications, dump and example intended as basic examples of the usage of the LAGO ANNA classes.

All the ANNA applications have their own integrated help, accesible through the -? modifier.

General help and documentation

The documentation is currently under preparation and will be released soon. A brief description of the action of each code and the available options and modifiers can be seen by calling them with the -? modifier.

(back to top)

Proposed features

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

(back to top)

License

ANNA is distributed under the BSD-3 License. See the LICENCE for more information.

(back to top)

Contact

The ANNA framework is developed by the LAGO Collaboration. If you need to contact us, please complete our contact form.

ANNA principal contact: Dr Hernán Asorey (@asoreyh)

Project Link: https://github.com/lagoproject/anna

(back to top)