:py:mod:`expelliarmus`
======================

.. py:module:: expelliarmus


Subpackages
-----------
.. toctree::
   :titlesonly:
   :maxdepth: 3

   wizard/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   expelliarmus.Wizard




.. py:class:: Wizard(encoding: str, fpath: Optional[Union[str, pathlib.Path]] = None, chunk_size: Optional[int] = 8192, time_window: Optional[int] = 10, buff_size: Optional[int] = _DEFAULT_BUFF_SIZE)

   Wizard allows to cast powerful spells, such as reading entire files to NumPy arrays or chunks of these, or cutting binary files to a certain duration.

   :param encoding: the encoding of the file, to be chosen among DAT, EVT2 and EVT3.
   :param fpath: the file to be read, either in chunks or fully.
   :param buff_size: the size of the buffer used to read the binary file.
   :param chunk_size: the chunk lenght when reading files in chunks.
   :param time_window: the time window lenght in millisecond when reading files in chunks of milliseconds.

   .. py:property:: encoding
      :type: str

      The encoding of the files handles by Wizard.

      :returns: the encoding.

   .. py:property:: fpath
      :type: pathlib.Path

      Wizard input file path.

      :returns: the file path.

   .. py:property:: buff_size
      :type: int

      The buffer size used by Wizard to read the binary files.

      :returns: the buffer size.

   .. py:property:: chunk_size
      :type: int

      The length of each chunk provided by Wizard when reading files in chunks.

      :returns: the chunk size.

   .. py:property:: time_window
      :type: int

      The time window lenght, expressed in milliseconds.

      :returns: the time window length.

   .. py:method:: set_file(fpath: Union[str, pathlib.Path]) -> None

      Function that sets the input file.

      :param fpath: the path to the file.


   .. py:method:: set_chunk_size(chunk_size: int) -> None

      Function to sets the size of the chunks to be read.
      WARNING: due to the vectorized events in event files, the chunks can be longer that 'chunk_size' (at most 'chunk_size+12').

      :param fpath: path to the input file.
      :param chunk_size: size of the chunks ot be read.


   .. py:method:: set_encoding(encoding: Union[str, pathlib.Path]) -> None

      Sets the encoding proprierty of the class.

      :param encoding: the encoding of the file.


   .. py:method:: set_buff_size(buff_size: int) -> None

      Sets te buffer size used to read the binary file.

      :param buff_size: the buffer size specified.


   .. py:method:: set_time_window(time_window: int) -> None

      Sets the time window lenght.

      :param buff_size: the time window specified.


   .. py:method:: reset() -> None

      Function used to reset the generator, so that the file can be read from the beginning.


   .. py:method:: cut(fpath_out: Union[str, pathlib.Path], new_duration: int, fpath_in: Optional[Union[str, pathlib.Path]] = None) -> int

      Cuts the duration of the recording contained in 'fpath_in' to 'new_duration' and saves the result to 'fpath_out'.

      :param fpath_in: path to input file.
      :param fpath_out: path to output file.
      :param new_duration: the desired duration, expressed in milliseconds.

      :returns: the number of events encoded in the output file.


   .. py:method:: read(fpath: Optional[Union[str, pathlib.Path]] = None) -> numpy.ndarray

      Reads a binary file to a structured NumPy of events.

      :param fpath: path to the input file.

      :returns: the structured NumPy array.


   .. py:method:: save(fpath: Union[str, pathlib.Path], arr: numpy.ndarray) -> None

      Compresses the provided to the chosen encoding format.

      :param fpath: path to output file.
      :param arr: the NumPy array to be saved.

      :returns: the number of events encoded in the output file.


   .. py:method:: read_chunk() -> numpy.ndarray

      Generator used to read the file in chunks.

      :returns: structured NumPy array of events.


   .. py:method:: read_time_window() -> numpy.ndarray

      Generator used to read the file in time windows.

      :returns: structured NumPy array of events.