Source code for irfpy.util.sensortable

''' A common template for plasma sensor table.

.. codeauthor:: Yoshifumi Futaana

The module is intended to be used for "systematic implementation" of
sensor tables, such as for energy, mass, angles.
Here systematic means that

- Same interface (getTable, getBound, getRange methods) for any tables.
- Version (or variant) control.


For user:

The module provides an coherent way of accessing for the lookup tables
for variant of plasma sensors.
It is recommended to try to find the sensor specific table at
``irfpy.<sensorname>.table`` module.

For developer:

To implement ``irfpy.<sensorname>.table`` module, you can make a derived class
from :class:`Table`.

Following will show how to implement a simple VEX/IMA energy table.

.. code-block:: py

    import numpy as np

    class EnergyTableVexImaSimple(Table):

        version = "1.0"    # It is recommended to make a version/variant control.
        units = "eV/q"     # Defining the unit.  It is better to adopt unitq.nit function.

        def __init__(self):
            self.bnd = np.logspace(1, 4, 97)[::-1]    # From 10 keV to 10 eV with 96 log-sep
            self.tbl = np.sqrt(self.bnd[1:] * self.bnd[:-1])

        def getTable(self):
            return self.tbl[:]

        def getBound(self):
            return self.bnd[:]

        def getRange(self):
            lb = self.tbl * .965
            ub = self.tbl * 1.035
            return np.array([lb, ub])
            

        def __str__(self):
            return "EnergyTableVexImaSimple: ver 1.0"
'''

class Table:
    ''' A parent class for plasma sensor table.
    '''
    version = "(UNDEFINED)"
    units = "(UNDEFINED)"

    def __init__(self):
        pass

    def getTable(self):
        ''' Get the table for the central values.

        Get a table with ``n`` elements, where ``n`` is the number of the data.
        '''
        raise NotImplementedError('getTable')

    def getBound(self):
        ''' Get the table for the edge values, without gap.

        Get a table with ``n+1`` elements, where ``n`` is the number of the data.

        The ``i``-th element in :meth:`getTable` should be between the ``i`` and ``i+1``-th
        elements in :meth:`getBound`.

        This can be used for ``pcolor`` or ``histogram`` for instance.
        '''
        raise NotImplementedError('getBound')

    def getRange(self):
        ''' Return the range, for example FWHM.
        
        Return [2, n] elements.
        :meth:`getRange` [0, :] is the lower bound and
        :meth:`getRange` [1, :] is the upper bound.

        This can be used for ``errorbar`` drawing or ``gfactor`` calculation for instance.
        '''
        raise NotImplementedError('getFwhm')

    def __str__(self):
        ''' Describe the table
        '''
        raise NotImplementedError('')

import unittest
import doctest


def doctests():
    return unittest.TestSuite((
        doctest.DocTestSuite(),
        ))
if __name__ == '__main__':
    unittest.main(defaultTest='doctests')