.. _datastructures:

================
Data structures
================

Locan provides :class:`LocData` as the one data class to deal with the following data structures:

1) localization data
2) selections of localization data
3) collections of selections


Comments on LocData:
----------------------------

1) Properties:
    Localization data consists of a list of individual localizations with spatial coordinates and several other
    properties (detailed list in :ref:`properties`) like

        * coordinates
        * intensity
        * frame
        * ...

    There is no fundamental difference between 2D and 3D localization data.

    Multiple sets of localization data like two-color localizations will be represented by independent :class:`LocData` objects.

    The unit for length throughout the project is given by the input unit for localization coordinates,
    unless specified in the metadata. In most cases the unit will be nanometre.


2) Dataset:
    A :class:`LocData` object is typically instantiated from an experimental or simulated localization dataset.
    The list of localizations is represented in a :class:`pandas.DataFrame` under the attribute :attr:`LocData.data`. In
    addition :class:`LocData` has some single-number-properties describing the dataset as a whole. Such properties could be
    (detailed list in :ref:`properties`):

        * total number of localizations
        * centroid
        * total emission strength
        * area/volume (for all possible hulls)
        * ...


3) Selection:
    A :class:`LocData` object can also be instantiated from a selection of localizations. Selections carry a reference to
    another :class:`LocData` object and a list of selected indices to not copy the original dataset with all localization
    properties for each selection. This way a large set of selections can be created with minimal memory requirements.


4) Collection:
    A :class:`LocData` object can also represent a list of selections as e.g. generated by clustering the
    localization data. The :attr:`LocData.data` of a collection consists of the list of all properties from the collected
    :class:`LocData` (e.g. selections).


5) Hulls:
    For the spatial coordinates in each :class:`LocData` object there are various hulls that might be of interest:

    1. minimal bounding box
    2. convex hull
    3. alpha complex or alpha shape
    4. minimal oriented bounding box

    These hulls are provided from stand-alone methods or through :class:`LocData` attributes.
    Hull objects expose attributes such as :attr:`LocData.region_measure` (among others) that are also added as
    :class:`LocData` properties.


6) Additional properties:
    Other :class:`LocData` properties might be provided by independent methods.