Data Importers
==============

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

Importer functions are managed in :py:mod:`reda.importers`. An importer module
must provide the following functionality:

* import a given data format into a :py:class:`pandas.DataFrame`
* import electrode positions into a :py:class:`pandas.DataFrame`, if available
  in this data format
* import topography into a :py:class:`pandas.DataFrame`, if available in this
  data format

Internal structure (for developers)
-----------------------------------

* All import functions should start with *import_*.
  Multiple `import_*` functions in an imported module are allowed, i.e. to
  provide import variations of a given data format (e.g., text files and binary
  data).
* Each `import_*` function must return three variables: data, electrode
  positions, topography. Return `None` for electrode positions and topography
  if not available.

A basic structure for an importer would be located in **reda.importers**::

   def import_new_data_file(filename, **kwargs):
      """Provide a proper docstring !

      Parameters
      ----------
      filename : str
         Path to datafile

      Additional Parameters
      ---------------------
      individual_parameter_1: bool
         Something that the user can change for the import

      Returns
      -------
      data : pandas.DataFrame
         The data, in proper format
      electrode_positions : pandas.DataFrame
         Electrode positions, columns x, y, z.
      topography : pandas.DataFrame
         Topography, columns x, y, z
      """
      # code here
      [...]
      return data, electrode_positions, topography

.. note::

    We retained from introducing importer objects by means of classes to make
    usage as simple as possible. If at some point it will be necessary to use
    classes for the importers, they can be built upon the import functions.

Test data
---------

We require at least one test data set for each importer in order to make sure
the importer works, now and in the future.

Test data should be stored in the separate testing repository,
https://github.com/geophysics-ubonn/reda_testing, in order to keep the
repository size of reda small. However, if data sets are not too large, one
import/analysis example is fine for the documentation gallery (in the
**examples/** subdirectory of the reda repository).