PICOcode.AnalysisModules
########################

The AnalysisModules subpackage of PICOcode contains the processing code
required to convert raw data to reconstructed data; that is, to summarize the
data obtained in an event such that events may be categorized, e.g. into
single- versus multi-bubble events, alpha- versus neutron-induced, etc.  This
is achieved through three steps of processing, contained in the event_modules,
run_modules, and dataset_modules directories, which contain scripts which
operate on events, runs, and full datasets, respectively.



Event Modules
=============

Event modules operate on one event at a time, and do not require data from any
other event in order to complete.  Each processor must inherit from the 
:class:`ProcessorBase<PICOcode.AnalysisModules.event_modules.processor_base.ProcessorBase>`
class, and override the
:meth:`run()<PICOcode.AnalysisModules.event_modules.processor_base.ProcessorBase.run>`
member function.  This **run()** member function should simply call any other
user-made functions which are members of the class.

Each module contained in the top level of the PICOcode.AnalysisModules.event_modules
package is intended to contain a reference processor, i.e. one which can
provide a template class which may be inherited by classes in dataset-specific
directories.  For example, the ``pico40l_22`` directory contains the 
:class:`FastDAQAnalysis<PICOcode.AnalysisModules.event_modules.pico40l_22.fastdaq_analysis.FastDAQAnalysis>`
class, which inherits from
:class:`FastDAQAnalysisBase<PICOcode.AnalysisModules.event_modules.fastdaq_analysis.FastDAQAnalysisBase>`.
The latter implements a basic form for acoustic ``t0``-finding and energy
calculation, with parameters initialized in its ``__init__()`` function such as
frequency bin edges for the energy calculation.  Inheritors may override these
parameters, or completely rewrite each function, add functions for futher
analyses, etc.

During processing, each event is processed in parallel.


.. toctree::
   :maxdepth: 2

   files/PICOcode.AnalysisModules.event_modules.rst



Run Modules
===========

Run modules are processing scripts/functions which operate on an entire run.
For the most part, these are external C++ programs which are called via the
:func:`subprocess.run` Python function, with the exception of
:mod:`XYZlookup<PICOcode.AnalysisModules.run_modules.XYZlookup>`, a module
which has been translated from MATLAB code.  The C++ programs called here
include `AutoBub3hs <https://github.com/picoexperiment/AutoBub3hs>`_,
`PICOJarTracker <https://github.com/picoexperiment/PICOJarTracker>`_, and
`XYZFixL2 <https://github.com/picoexperiment/XYZFixL2>`_.

As much as possible, future analyses should be written as event-specific
processors under the :ref:`Event Modules` subpackage.


To Do
-----
The processors in this subpackage should be bundled in a RunModuleBase class,
or similar.



Dataset Modules
===============

Dataset modules run on an entire dataset, i.e. all data in a particular set of
data collection (e.g. all runs processed for ``pico40l-22``).  The main
purpose of these processors is so-called "level 2" processing, which includes
corrections to the data from :ref:`event-level<Event Modules>` and
:ref:`run-level<Run Modules>` such as position corrections for acoustic and
dytran data.

The structure of this subpackage is similar to 
:ref:`event-level<Event Modules>` in that there is a base class,
:class:`DatasetProcessorBase<PICOcode.AnalysisModules.dataset_modules.dataset_processor_base.DatasetProcessorBase>`
which all other processors must inherit from.  This all inheritors must
override the
:meth:`run<PICOcode.AnalysisModules.dataset_modules.dataset_processor_base.DatasetProcessorBase.run>`
method, which initiates all required processing.  Additionally, certain
attributes of the class must be filled:
 -
 :attr:`header<PICOcode.AnalysisModules.dataset_modules.dataset_processor_base.DatasetProcessorBase.header>`
 -