============
File formats
============

PyNN supports writing datafiles in both text and binary formats. PyNN comes with
several built-in formats, but it is very easy to define your own.

The default format is text-based. If we assume that you have run a simulation,
and have recorded spikes, membrane potential and/or synaptic conductances for the
neurons in a ``Population`` ``p``, then you can write the recorded data to a file
in text format simply by specifying the filename::

    >>> p.printSpikes("my_spike_data.dat")
    >>> p.print_v("my_Vm_data.dat")
    
(the file extension can be anything you like).

If you would like to write the data in a binary format, you must first create a
PyNN ``File`` object`::

    >>> from pyNN.recording.files import NumpyBinaryFile, HDF5ArrayFile
    >>> spike_file = NumpyBinaryFile("my_spike_data.npz", "w")
    >>> p.printSpikes(spike_file)
    >>> spike_file.close()
    >>> vm_file = HDF5ArrayFile("my_Vm_data.h5", "w")
    >>> p.print_v(vm_file)
    >>> vm_file.close()
    
Note that we do not currently take advantage of the ability of HDF5 or NumPy
binary files to contain multiple data sets. In addition to ``NumpyBinaryFile`` and
``HDF5ArrayFile`` (which requires PyTables to be installed), the ``recording.files``
module also contains ``PickleFile`` and ``StandardTextFile``.

The file contents can then be accessed using NumPy, PyTables or the standard
``pickle/cPickle`` module, or by creating a PyNN ``File`` object in read mode::

    >>> spike_file = NumpyBinaryFile("my_spike_data.npz", "r")
    >>> metadata = spike_file.get_metadata()
    >>> spikes = spike_file.read()
    
    
Defining your own file formats
==============================

If you wish to define your own file format, it is straightforward to create
new PyNN-compatible ``File`` class by subclassing ``recording.files.BaseFile``:
the only requirement is that the class should implement a method
``write(data, metadata)``, where ``data`` will be a NumPy array and ``metadata``
will be a dictionary.