.. _sample_events: http://www.python.org
.. _sample_filters: http://www.python.org

.. _file_formats:

File formats
************

This section describes configuration and data file formats handled by TeraPy.

.. contents::


Configuration files
===================

Configuration files read by TeraPy are in XML format. The default configuration files have already been described in :ref:`configuration`. In addition, TeraPy allows to load and save event sequences (see :ref:`user_events`) and filter banks (see :ref:`user_filters`). The file formats are the same as for default configuration files. These are recalled below.

Scan sequences
______________

Scan sequence files have the following structure:

.. code-block:: xml

 <?xml version="1.0" ?>
	<config scope="events">
		<events>
			<item name="sequence name" class="Sequence">
				<item class="scan event class 1" name="display name 1" some_property="some value"/>
				<item class="scan event class 2" name="display name 2" some_property="some value">
					<item class="scan event class 3" name="display name 3" some_property="some value"/>
			  	</item>
				...
			</item>
		</events>
	</config>

The file can describe one or several scan sequences. Each item in the sequence is represented by an ``<item>`` tag. Properties depend on the scan event class and should be set according to the :ref:`add_events` section.

See the `sample events.ini <sample_events_>`_ file for an example.


Filter banks
____________

The structure of filter bank files is as follows:

.. code-block:: xml

 <?xml version="1.0" ?>
	<config scope="filters">
		<filters name="Filter bank name" dimension="data dimension to apply to (int)">
			<item class="filter class 1" name="filter display name 1" some_property="some value"/>
			<item class="filter class 2" name="filter display name 2" some_property="some value"/>
			...
		</filters>
	</config>

Several filter banks can be placed in the same file, each corresponding to a separate ``<filters>`` entry. The *dimension* property sets the data dimension, to which the filter bank applies (e.g. 1D data -> ``dimension="1"``). If, for a given dimension, more than one bank is present, TeraPy takes the last one in the file.

Each filter in a filter bank corresponds to one ``<item>`` tag. Properties depend on the filter class and should be set according to the :ref:`add_filters` section.

See the `sample filters.ini <sample_filters_>`_ for an example.


.. _data_file_formats:

Data files
==========

Data files are handled by the :doc:`terapy.files`. Currently, the supported formats are

+--------+--------------------------------------------------------------+------+-------+----------------+-------------------+
| format | Description                                                  | Read | Write | Max. dimension | Multiple datasets |
+========+==============================================================+======+=======+================+===================+
| HDF5   | Hierarchical Data Format (see http://www.hdfgroup.org/HDF5/) | Yes  | Yes   |                | Yes               |
+--------+--------------------------------------------------------------+------+-------+----------------+-------------------+
| XLS    | Microsoft Excel spreadsheet                                  | Yes  | Yes   | 2              | Yes               |
+--------+--------------------------------------------------------------+------+-------+----------------+-------------------+
| Text   | Plain text                                                   | Yes  | Yes   | 2              | No                |
+--------+--------------------------------------------------------------+------+-------+----------------+-------------------+
| OPJ    | Origin project file                                          | Yes  | No    | 2              | Yes               |
+--------+--------------------------------------------------------------+------+-------+----------------+-------------------+

If your favorite format is not in this list, don't despair! You can learn how to write a new module in no time with the :ref:`programmer`.