===============================
PySight With Different Hardware
===============================

Introduction
------------

PySight's main design goal is to parse list (``.lst``) files generated by a FAST ComTec multiscaler. However, during the design process of the software we tried implementing a "public API" that could fit other data formats.

During PySight's work, it generates a ``pandas.DataFrame`` with the recorded data. Each row in this DataFrame is a photon, and its indices correspond to the frame, line, z-plane, time-since-laser-pulse and spectral channel of each particular event.

PySight's GUI allows the user to choose a ``pickle`` file (``.p``) generated by Python, that contains a DataFrame of this structure. The algorithm will verify the integrity of this DataFrame, and will produces an n-dimensional volume populated with the photons recorded.

Specific Data Structure
-----------------------

The DataFrame must have a column named ``abs_time`` that contains the time of arrival of the photon relative to the start of the experiment. It also must have a MultiIndex containing the following column names:

* ``Channel`` - Spectral channel of the data. Currently only values of 1 and 2 are supported.

* ``Frames`` - Time of the start of the frame that this photon belongs to.

* ``Lines`` - Time of the start of the line that this photon belongs to.

If further data dimensions exist, they should be inserted as ordinary data columns:

* ``time_rel_pulse`` - Time since the last laser pulse, used for FLIM.

* ``Phase`` - ``[0, 2π)`` phase of the photon in a TAG lens period. Used for volumetric imaging.


Bugs
----

While the basic feature works, i.e. PySight will detect the pickle file and process it, this feature hasn't been tested on real data from different photon counting systems. In the very likely case of bugs, please contact the package authors and we'll be glad to assist.


