evefile 0.1.0rc2__py3-none-any.whl → 0.2.0__py3-none-any.whl

evefile/entities/metadata.py

@@ -68,6 +68,12 @@ documentation:
 
         * :class:`IntervalNormalizedChannelMetadata`
 
+    * :class:`ArrayChannelMetadata`
+
+      * :class:`MCAChannelMetadata`
+
+        * :class:`MCAChannelCalibration`
+
 
 Module documentation
 ====================
@@ -77,6 +83,8 @@ Module documentation
 import copy
 import logging
 
+import numpy as np
+
 logger = logging.getLogger(__name__)
 
 
@@ -129,6 +137,7 @@ class Metadata:
         #       string representation using self.__str__
         # Use only append or extend in subclasses!
         self._attributes = ["name"]
+        self._attribute_name_length = 0
 
     def __str__(self):
         """
@@ -141,12 +150,12 @@ class Metadata:
 
         """
         output = []
-        attribute_name_length = max(
+        self._attribute_name_length = max(
             len(attribute) for attribute in self._attributes
         )
         for attribute in self._attributes:
             output.append(
-                f"{attribute:>{attribute_name_length}}:"
+                f"{attribute:>{self._attribute_name_length}}:"
                 f" {getattr(self, attribute)}"
             )
         if self.options:
@@ -590,3 +599,197 @@ class IntervalNormalizedChannelMetadata(
     def __init__(self):
         super().__init__()
         self._attributes.extend(["normalize_id"])
+
+
+class ArrayChannelMetadata(ChannelMetadata):
+    """
+    Metadata for channels with numeric 1D data.
+
+    This class complements the class
+    :class:`evefile.entities.data.ArrayChannelData`.
+
+
+    Examples
+    --------
+    The :class:`ArrayChannelMetadata` class is not meant to be used
+    directly, as any entities, but rather indirectly by means of the
+    respective facades in the boundaries technical layer of the
+    ``evefile`` package. Hence, for the time being,
+    there are no dedicated examples how to use this class. Of course,
+    you can instantiate an object as usual.
+
+
+    .. versionadded:: 0.2
+
+    """
+
+
+class MCAChannelMetadata(ArrayChannelMetadata):
+    """
+    Metadata for multichannel analyzer (MCA) channels.
+
+    This class complements the class
+    :class:`evefile.entities.data.MCAChannelData`.
+
+
+    Attributes
+    ----------
+    calibration : :class:`MCAChannelCalibration`
+        Metadata for the calibration of the MCA channel.
+
+    preset_life_time : :class:`float`
+        Preset life time
+
+        For how many seconds to acquire data, according to a clock which
+        counts only when the hardware is ready to accept data (live time).
+
+    preset_real_time : :class:`float`
+        Preset real time
+
+        For how many seconds to acquire data, according to a free running
+        clock (real time)
+
+
+    Examples
+    --------
+    The :class:`MCAChannelMetadata` class is not meant
+    to be used directly, as any entities, but rather indirectly by means
+    of the respective facades in the boundaries technical layer of the
+    ``evefile`` package. Hence, for the time being,
+    there are no dedicated examples how to use this class. Of course,
+    you can instantiate an object as usual.
+
+
+    .. versionadded:: 0.2
+
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.calibration = MCAChannelCalibration()
+        self.preset_life_time = 0.0
+        self.preset_real_time = 0.0
+        # Note: calibration gets handled explicitly
+        self._attributes.extend(["preset_life_time", "preset_real_time"])
+
+    def __str__(self):
+        str_representation = super().__str__()
+        attribute = "calibration"
+        str_representation += (
+            f"\n{attribute:>{self._attribute_name_length}}:\n"
+        )
+        whitespace = " " * (self._attribute_name_length + 2)
+        calibration_parameters = [
+            f"{whitespace}{parameter}"
+            for parameter in self.calibration.__str__().split("\n")
+        ]
+        str_representation += "\n".join(calibration_parameters)
+        return str_representation
+
+
+class MCAChannelCalibration:
+    """
+    Metadata for MCA channel calibration.
+
+    Many MCA channels need to be calibrated (with a second-order
+    polynomial) to convert the channel numbers to actual energies.
+
+    From the `EPICS MCA Record description
+    <https://millenia.cars.aps.anl.gov/software/epics/mcaRecord.html>`_:
+    "The relationship between calibrated units (cal) and channel number
+    (chan) is defined as ``cal=CALO + chan*CALS + chan^2*CALQ``. The first
+    channel in the spectrum is defined as chan=0." Here, ``CALO`` is the
+    offset, ``CALS`` the slope, and ``CALQ`` the quadratic term of the
+    polynomial.
+
+    Attributes
+    ----------
+    offset : :class:`float`
+        Calibration offset, *i.e.* 0th order coefficient of the polynomial.
+
+    slope : :class:`float`
+        Calibration slope, *i.e.* 1st order coefficient of the polynomial.
+
+    quadratic : :class:`float`
+        2nd order coefficient of the polynomial.
+
+
+    Examples
+    --------
+    To calibrate your MCA with a number of channels with the given
+    calibration parameters (offset, slope, quadratic term), use:
+
+    .. code-block::
+
+        calibration = MCAChannelCalibration()
+        # Set the calibration parameters
+        calibrated_values = calibration.calibrate(n_channels=4096)
+
+    The :obj:`MCAChannelData <evefile.entities.data.MCAChannelData>`
+    object will usually perform the calibration transparently for you if
+    necessary. Even better, this object knows how many channels the MCA has.
+
+
+    .. versionadded:: 0.2
+
+    """
+
+    def __init__(self):
+        self.offset = 0.0
+        self.slope = 1.0
+        self.quadratic = 0.0
+
+    def __str__(self):
+        """
+        Human-readable representation of the metadata.
+
+        Returns
+        -------
+        output : :class:`str`
+            Multiline string with one attribute per line
+
+        """
+        output = []
+        attributes = [
+            item
+            for item in dir(self)
+            if not item.startswith("_") and not callable(getattr(self, item))
+        ]
+        attribute_name_length = max(
+            len(attribute) for attribute in attributes
+        )
+        for attribute in attributes:
+            output.append(
+                f"{attribute:>{attribute_name_length}}:"
+                f" {getattr(self, attribute)}"
+            )
+        return "\n".join(output)
+
+    def calibrate(self, n_channels=0):
+        """
+        Return calibrated values for given number of channels.
+
+        From the `EPICS MCA Record description
+        <https://millenia.cars.aps.anl.gov/software/epics/mcaRecord.html>`_:
+        "The relationship between calibrated units (cal) and channel number
+        (chan) is defined as ``cal=CALO + chan*CALS + chan^2*CALQ``. The first
+        channel in the spectrum is defined as chan=0." Here, ``CALO`` is the
+        offset, ``CALS`` the slope, and ``CALQ`` the quadratic term of the
+        polynomial.
+
+        Parameters
+        ----------
+        n_channels : :class:`int`
+            Number of channels of the MCA
+
+        Returns
+        -------
+        calibrated_values : :class:`numpy.ndarray`
+            Calibrated values for the given number of channels.
+
+        """
+        channels = np.arange(n_channels)
+        calibrated_values = (
+            self.offset + channels * self.slope + channels**2 * self.quadratic
+        )
+        return calibrated_values

{evefile-0.1.0rc2.dist-info → evefile-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evefile
-Version: 0.1.0rc2
+Version: 0.2.0
 Summary: Transitional package to read eveH5 files containing synchrotron radiometry data recorded at BESSY/MLS in Berlin
 Home-page: https://www.ptb.de/cms/en/ptb/fachabteilungen/abt7/ptb-sr.html
 Author: Till Biskup
@@ -64,18 +64,32 @@ evefile
 
 *Transitional package to read eveH5 files containing synchrotron radiometry data recorded at BESSY/MLS in Berlin.*
 
-Welcome! This is evefile, a Python package for **importing (synchrotron) radiometry data** obtained at one of the beamlines at **BESSY-II or MLS in Berlin**, mostly operated by the German National Metrology Institute, the `Physikalisch-Technische Bundesanstalt (PTB) <https://www.ptb.de/>`_. This package acts as transitional interface between the (eveH5) data files and the processing and analysis code. For related packages for importing, viewing, and analysing those data, have a look at the "related projects" section below.
+Welcome! This is evefile, a Python package for **importing (synchrotron) radiometry data** obtained at one of the beamlines at **BESSY-II or MLS in Berlin**, mostly operated by the German National Metrology Institute, the `Physikalisch-Technische Bundesanstalt (PTB) <https://www.ptb.de/>`_. This package acts as *transitional* interface between the (eveH5) data files and the processing and analysis code. For related packages for importing, viewing, and analysing those data, have a look at the "related projects" section below.
+
+Loading the contents of a data file of a measurement is as simple as::
+
+    import evefile
+
+    file = evefile.EveFile(filename="my_measurement_file.h5")
+
+Here, ``file`` contains all the information contained in the data file as a hierarchy of Python objects.
 
 
 Features
 ========
 
-A list of (planned) features:
+A list of features:
 
 * Importer for eve HDF5 files (used at PTB in Berlin, Germany)
 
 * Fully backwards-compatible to older eveH5 versions
 
+* Complete information available that is contained in an eveH5 file
+
+* Data are (only) loaded on demand, not when loading the file
+
+* Powerful and intuitive abstractions, allowing for associative access to data and information – beyond a purely tabular view of the data
+
 
 And to make it even more convenient for users and future-proof:
 

evefile-0.2.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+evefile/__init__.py,sha256=DtUfummsLsWO7A-xiqL1hUEBll8Qc1z7829P9Sb0kOk,215
+evefile/__pycache__/__init__.cpython-311.pyc,sha256=RkdWBYZ3wcT04KJ8H7KPKwhPhMc-GV9vbGSuOIOtqjE,398
+evefile/boundaries/__init__.py,sha256=OKIxX1YeMY3Bda2g27xm-uQwH191EL6qLIHoPIoz_88,64
+evefile/boundaries/evefile.py,sha256=brXK3bkuL4DEckaMsA6Kne8FvCw_Y2TQmTBDp-WTYRs,25038
+evefile/boundaries/eveh5.py,sha256=u-aEXXBoQYCfKb7l7w1x2VVKlQ2mT5S8gMdLiHZteYU,29750
+evefile/boundaries/__pycache__/__init__.cpython-311.pyc,sha256=GnLdTDzJRRVDQg_l9nctkGQs0GU8oILd3Lg1XY7kKhg,251
+evefile/boundaries/__pycache__/evefile.cpython-311.pyc,sha256=m_tf3Q7SRWXJd-kpvxRCKzLjIbu7d8jAes820V61sZM,29953
+evefile/boundaries/__pycache__/eveh5.cpython-311.pyc,sha256=IpaPRhZkmdR-z6x257TujkwRgAeyuhPwAn7NnvslNJM,35831
+evefile/controllers/__init__.py,sha256=K4ysYHyf7p5dFDIppJyx8-ydZpLfwvjoikhUcOapKuQ,147
+evefile/controllers/joining.py,sha256=GywsV8-Ah-jkvdN2GUiDZrhLoABR710MmkhS6ro8Qtk,42459
+evefile/controllers/timestamp_mapping.py,sha256=mqD3bugpP68xFJa4yjgTgKJ6IXdIL7kcAjO_PdJNxoI,6886
+evefile/controllers/version_mapping.py,sha256=CuaKQtFwVXBj-uEsrqYgff6hCokwvgNjxhL4-QRwivg,49602
+evefile/controllers/__pycache__/__init__.cpython-311.pyc,sha256=OAlQR88n3ns13ecANQdSyPZ4w0F350NhCicFxjMAJmw,356
+evefile/controllers/__pycache__/joining.cpython-311.pyc,sha256=TmQHb4_0TgAH6TjCSbA04Nx_5IrsDSl6RivXf2DjjF4,48362
+evefile/controllers/__pycache__/timestamp_mapping.cpython-311.pyc,sha256=U2mJyG-MSaDfwtlsiDv9yGvJaaDFg00MatSW7-0Abp4,7772
+evefile/controllers/__pycache__/version_mapping.cpython-311.pyc,sha256=jD6hwVO-sYPrneeonr9nJmRDrkc18NUjK2r8XH0VNhE,63323
+evefile/entities/__init__.py,sha256=VfS-6fdCiqlYobw7gcCMcfdm8Fct_6AnSPw99JHV2bo,170
+evefile/entities/data.py,sha256=b6TnGo68M-aM4U46Q3bVQ4bSPT0XrZXKSQkRWo7DaKg,76898
+evefile/entities/file.py,sha256=grOHe2ONwieh58imbEq1ahLZyXooardctNanvcuWOJs,9816
+evefile/entities/metadata.py,sha256=1_BZe3pXJ7UczvHn1QvlQDaFtmCF-LsDTrt8pX-7X70,24309
+evefile/entities/__pycache__/__init__.cpython-311.pyc,sha256=Rc8OF9IeRYpJbN7Qw5AFn5qPxm7g_carXQKqnuZUHz4,380
+evefile/entities/__pycache__/data.cpython-311.pyc,sha256=QkUi9-JSX9Tv2vIgpW_6Jq6oLAha-EucpG47Nd-nNlA,91357
+evefile/entities/__pycache__/file.cpython-311.pyc,sha256=scDx1m5UN-HcCqAArH3Gzw-tSjE0fWSiiTzR8xTSlfg,11764
+evefile/entities/__pycache__/metadata.cpython-311.pyc,sha256=yqIS_DWViW2XNQOH1y0FTPzT1_6DFxu_uZOwA9MD-b8,33039
+evefile-0.2.0.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+evefile-0.2.0.dist-info/licenses/LICENSE,sha256=VYLxbjlmThdMWJAgeCXSLlcHUDR0kk0C40P92FH3o3M,766
+evefile-0.2.0.dist-info/METADATA,sha256=mScSW0pFX1lfx4U82nKi_MPtOdCI59EhMubGtxjB3n4,5598
+evefile-0.2.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+evefile-0.2.0.dist-info/top_level.txt,sha256=AiXT2Ch6ZWznVmfIXckmjoPXMfucyXMj4SP_46hKN7s,8
+evefile-0.2.0.dist-info/RECORD,,

{evefile-0.1.0rc2.dist-info → evefile-0.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

evefile-0.1.0rc2.dist-info/RECORD

@@ -1,30 +0,0 @@
-evefile/__init__.py,sha256=DtUfummsLsWO7A-xiqL1hUEBll8Qc1z7829P9Sb0kOk,215
-evefile/__pycache__/__init__.cpython-311.pyc,sha256=RkdWBYZ3wcT04KJ8H7KPKwhPhMc-GV9vbGSuOIOtqjE,398
-evefile/boundaries/__init__.py,sha256=OKIxX1YeMY3Bda2g27xm-uQwH191EL6qLIHoPIoz_88,64
-evefile/boundaries/evefile.py,sha256=uVptvR2-1bvCjByxi4JNO45VkMyt7t6pYBwRa5vjO9w,18186
-evefile/boundaries/eveh5.py,sha256=u-aEXXBoQYCfKb7l7w1x2VVKlQ2mT5S8gMdLiHZteYU,29750
-evefile/boundaries/__pycache__/__init__.cpython-311.pyc,sha256=GnLdTDzJRRVDQg_l9nctkGQs0GU8oILd3Lg1XY7kKhg,251
-evefile/boundaries/__pycache__/evefile.cpython-311.pyc,sha256=n0oPx3nUc5SMzKGNektf1o4YBIuWllxQma9jd0bLKlE,22020
-evefile/boundaries/__pycache__/eveh5.cpython-311.pyc,sha256=IpaPRhZkmdR-z6x257TujkwRgAeyuhPwAn7NnvslNJM,35831
-evefile/controllers/__init__.py,sha256=K4ysYHyf7p5dFDIppJyx8-ydZpLfwvjoikhUcOapKuQ,147
-evefile/controllers/joining.py,sha256=o0GI6bBxtAU5uZkXoZ6JhgerZ_fgD3Y6IaoYt4UjSJI,42173
-evefile/controllers/timestamp_mapping.py,sha256=_plmzVtY_CaVp3wYy1VhfGenRwWLRJiIA6yw398r_Ec,4686
-evefile/controllers/version_mapping.py,sha256=zplXv7lKvvzd0NI1pMpavVFCdrkauXBnT_uvXTJu8PQ,41958
-evefile/controllers/__pycache__/__init__.cpython-311.pyc,sha256=OAlQR88n3ns13ecANQdSyPZ4w0F350NhCicFxjMAJmw,356
-evefile/controllers/__pycache__/joining.cpython-311.pyc,sha256=si4e2UAuNQrQ6fGp6vXf_a7MUimLLeKDDh148OUzwPo,48080
-evefile/controllers/__pycache__/timestamp_mapping.cpython-311.pyc,sha256=yDqvWtdJg9FfAoT3vSQ2jI9tuIslMZxGTNjCOXtPpRs,4898
-evefile/controllers/__pycache__/version_mapping.cpython-311.pyc,sha256=rQ-M_O5po_E3bwjbG200AdZBT_g8N0WShDX-BFpYKl4,52416
-evefile/entities/__init__.py,sha256=VfS-6fdCiqlYobw7gcCMcfdm8Fct_6AnSPw99JHV2bo,170
-evefile/entities/data.py,sha256=w6XMPqCtYqPGcRGmmZsWbOfT2WHsevc82Ws5uMB3tjc,54930
-evefile/entities/file.py,sha256=grOHe2ONwieh58imbEq1ahLZyXooardctNanvcuWOJs,9816
-evefile/entities/metadata.py,sha256=DVgLWM3bob2JWh_wpf6jGJ6LnIRsErB_AJmOx-u_P3E,18111
-evefile/entities/__pycache__/__init__.cpython-311.pyc,sha256=Rc8OF9IeRYpJbN7Qw5AFn5qPxm7g_carXQKqnuZUHz4,380
-evefile/entities/__pycache__/data.cpython-311.pyc,sha256=B_mzzKZ6uqGufF52z9I4jM8eIIMEEUF-zIVdSDEzS24,68181
-evefile/entities/__pycache__/file.cpython-311.pyc,sha256=scDx1m5UN-HcCqAArH3Gzw-tSjE0fWSiiTzR8xTSlfg,11764
-evefile/entities/__pycache__/metadata.cpython-311.pyc,sha256=AMbmJ_dJbM6fzzMw124sH6CYvUEaYNeV0vTn1CHEJEQ,24716
-evefile-0.1.0rc2.dist-info/licenses/COPYING,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-evefile-0.1.0rc2.dist-info/licenses/LICENSE,sha256=VYLxbjlmThdMWJAgeCXSLlcHUDR0kk0C40P92FH3o3M,766
-evefile-0.1.0rc2.dist-info/METADATA,sha256=SLm_dKzLTvD7OxUUzKT9yzUOLxOr1_o9RaN1Wyfs5qQ,5075
-evefile-0.1.0rc2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-evefile-0.1.0rc2.dist-info/top_level.txt,sha256=AiXT2Ch6ZWznVmfIXckmjoPXMfucyXMj4SP_46hKN7s,8
-evefile-0.1.0rc2.dist-info/RECORD,,