This document describes how the BFS format is used with bioassay spot
data when communicating with plug-ins.

A typical plug-in execution sequence is:
 1. Export current data to BFS
 2. Execute the plug-in which processes the data
 3. Import the transformed data to BASE


The export will generate at least two files. One metadata file
and one data file. Row and column annotation files can be created
if the plug-in needs it. Additional data files can also be created
if needed. This document only discusses the export part of the
procedure. Note that reporter and assay annotation files are always
needed if new spot data is going to be imported.

The metadata file (export)
==========================

There are two BFS subtypes:

* matrix: One data file is required for each value/formula to
  export. The columns in the data files represents assays.

* serial: One data file is required for each assay. The columns
  in the data files represents values/formulas.

Files
-----

For both subtypes a [files] section is used to name the files holding
data and annotations. The following keys should be used:

 * rdata: The filename of the file containing reporter annotations
 * pdata: The filename of the file containing assay annotations
 * sdata1,...,sdataN: N entries numbered from 1 to N with the filenames
   of the files containing spot data. If the 'serial' subtype is used there
   should be one file for each assay in the bioassay set. If the 'matrix' 
   subtype is used there should be one file for each entry in the [sdata]
   section (see the 'Spot data' section below).

The rdata and pdata files are optional. Other custom files may be included.
It is recommended that custom file entries use 'x-' as a prefix to avoid
key clashes in future version.

Example:

[files]
rdata	rdata.txt
pdata	pdata.txt
sdata1	sdata1.txt
sdata2	sdata2.txt
x-custom	custom.txt


Spot data
---------

The [sdata] section contains metadata about the spot data that has been
exported. The order in this section is important.

If the 'matrix' subtype is used the order must match the 'sdataX'
entries in the [files] section. Eg. the data that corresponds to the
first line in this section is found in the 'sdata1' file. The number
of entries in this section must be the same as the number of 'sdataX'
entries in the [files] section.

If the 'serial' subtype is used the order must match the column order 
inside each of the 'sdataX' files. Eg. the data that corresponds to the
first line in this section is found in the first column in all 'sdata'
files. The number of entries in this section must match the number of
column in the 'sdata' files.

The key of each line is the name or title of the data that is exported.
The value describes the data type and can be either 'text', 'float' or
'int'.

Example:

[sdata]
Ch 1	float
Ch 2	float
Weight	float
Flag	int


Plug-in parameters
------------------

The [parameters] section contains extra parameters needed by the plug-in.
Keys and values are defined by the plug-in/job configuration. Duplicate
keys are not allowed, and order is not important. Multiple values for the
same parameter are separated with a tab character.

Example:

[parameters]
beta	0.5
length	100
vector	10	10.3	23
median	true


Reporter annotation file (export)
=================================

The file used for reporter annotations is given by the 'rdata' entry in the
[files] section. This file is optional. If it is used the only required
column is the ID column. In this case, the ID column holds the internal
bioassay set 'position' value. All sdata files should have the same number
of rows as this file (not counting the header line) and data should be sorted
in the same order.

Additional columns may be included in the export.

Note that the same underlying reporter may be assigned to more than one
position. If the plug-in needs to operate on merged-per-reporter data
the export should include either the internal or external reporter id in
an additional column and use this information to determine what should
be merged.


Assay annotation file (export)
==============================

The file used for assay annotations is given by the 'pdata' entry in the
[files] section. This file is optional. If it is used, the only required
column is the ID column. In this case, the ID column holds the internal
bioassay 'id' value.

If the 'matrix' subtype is used the columns in the sdata files must be in
the same order as the assays appear in this file. The number of columns in
the sdata files must be the same as the number of rows in this file (not
counting the header line).

If the 'serial' subtype is used, the 'sdata1' file has data for the assay
that is described in the first line in this file, the 'sdata2' file has data
for the second assay, etc. The number of data files must match the number of
lines in this file.

Additional columns may be included in the export.

Data files (export)
===================

Data files contains data in matrix format. More than one data file may be
required. The organisation of the data depends on the format subtype. In
both subtypes the number and order of the rows must match the information
in the reporter annotation file.

If the 'matrix' subtype is used, the columns corresponds to assays. The
number of columns and their order must match the lines in the assays
annotation file. The number of sdata files and their content is defined
by the entries in the [sdata] section.

If the 'serial' subtype is used, the the number of columns and their order
must match the entries in the [sdata] section. Each sdata file has data from
one assay. The number of sdata files in the [files] section must match the
number of lines in the assays annotation file. Eg. spot data for the assay 
on the first line is found in the file referenced in the 'sdata1' entry.