+--------------------------------------+
| |
| Run Header |
| |
+--------------------------------------+
+--------------------------------------+
| Frame Header 1 |
+--------------------------------------+
| Frame Data |
| |
+--------------------------------------+
...
+--------------------------------------+
| Frame Header n |
+--------------------------------------+
| Frame Data |
| |
+--------------------------------------+
+-------------------+-------------------+
| Flags | Tag |
+-------------------+-------------------+ Frame Header
| Sample no. or No. of frames |
+---------------------------------------+
+---------------------------------------+
| Frame Data |
| for trace 0 |
+---------------------------------------+
...
+---------------------------------------+
| |
| Frame Data |
| for trace n-1 |
| |
+---------------------------------------+
Below are the C Language structure definitions used for the headers. They are appropriate for big-endian architectures (Motorola, SPARC, PowerPC). For little-endian architectures (DEC, Intel) it is necessary to flip the byte ordering for all short ints, long ints and doubles.
____________________________________________________________
/*
* run.h -- definitions of run file headers and related info.
*
* (c) 1988, G.R. Detillieux, Spinal Cord Research Centre,
* The University of Manitoba. All Rights Reserved.
*/
#define NCHFRM 16 /* # chans for frame (triggered) data */
#define NCHREG 16 /* # chans for regular (untriggered) data */
#define CHNAMESIZ 42 /* size of channel name string */
typedef short int ADSAMPLE; /* data type used for A/D values */
typedef long int ADPERIOD; /* data type used for time values (sampling periods) */
/* calibration info for one channel: */
struct calinfo {
ADSAMPLE ca_zero; /* A/D value for zero volts */
ADSAMPLE ca_height; /* A/D value for cal pulse minus value for zero */
long int ca_level; /* level of cal pulse in uV */
short int ca_gain; /* gain factor used for channel */
char ca_name[CHNAMESIZ]; /* channel name string */
};
#define RUNMAGIC 0xFFAAFABF /* "magic" number identifying run file */
/* define averaging methods used by dsepr, others in analysis/param.h: */
#define AM_TRAWCAP 0 /* raw trace capture */
#define AM_TAVGCAP 1 /* averaged trace capture, ... */
/* ... same code as AM_TAVGFRMLST */
/* run header in frame data file: */
struct runhdr {
long int rh_magic; /* magic number for run file */
ADPERIOD rh_length; /* run length as #samples */
double rh_samprate; /* sample rate in Hz */
long int rh_nframes; /* # frames in file */
long int rh_frmsiz; /* frame size in bytes */
ADPERIOD rh_delay; /* delay to start of frame as #samples */
ADPERIOD rh_window; /* frame sampling window as #samples */
ADPERIOD rh_gpper; /* gate pulse period as #samples */
ADSAMPLE rh_minbinlevel; /* min. W.F. level for AM_TAVGLEVEL */
ADSAMPLE rh_maxbinlevel; /* max. W.F. level for AM_TAVGLEVEL */
short int rh_avgmethod; /* averaging method, or 0 for raw */
short int rh_levelwf; /* W.F. from which above levels come */
ADPERIOD rh_wreduce; /* #samples by which usable window reduced */
long int rh_starttime[2];/* time capture started, if available */
short int rh_reserve[19]; /* reserved for future use */
short int rh_needrhdfile; /* extra run header info. needed */
short int rh_npts[NCHFRM]; /* # points in triggered channel frames */
short int rh_frmdiv[NCHFRM]; /* sample rate divisors for trig. chan. */
short int rh_regdiv[NCHREG]; /* sample rate divisors for untrig. chan. */
short int rh_frmchan[NCHFRM]; /* channel numbers for traces */
short int rh_regchan[NCHREG]; /* channel numbers for waveforms */
struct calinfo rh_frmcal[NCHFRM]; /* calibr. info for framed channels */
struct calinfo rh_regcal[NCHREG]; /* calibr. info for regular (unframed) channels */
long int rh_frmres[NCHFRM]; /* reserved for future use */
long int rh_regres[NCHREG]; /* reserved for future use */
};
/* header at beginning of each frame: */
struct frmhdr {
long int fh_flags; /* tag, deletion flags & room for more */
ADPERIOD fh_sampnum; /* sample # where gate pulse detected */
};
#define fh_numsweeps fh_sampnum /* # of sweeps in an averaged frame */
/* frame header flags: */
#define DELFLAGS 0xE0000000 /* all 3 deletion flags */
#define MANDEL 0x80000000 /* frame manually deleted */
#define AUTODEL1 0x40000000 /* frame auto-del'd due to clipping */
#define AUTODEL2 0x20000000 /* frame auto-del'd due to bad cal pulse */
#define ISDELETED(fh) ((fh).fh_flags & DELFLAGS)
#define TAGMASK MAXSHORT /* all bits reserved for tags */
#define NTAGS 4096 /* # of different tags used */
#define INTAGLIST(fh,tlist,tlen) (inlist((unsigned short int)((fh).fh_flags & TAGMASK), \
(tlist), (tlen)))
____________________________________________________________
These structures are copied from the calibration file at the start of the data capture. The calibration file (default.cal) simply contains an array of 16 or more of these structures, one for each channel on the A/D converter, with no header or other fields in the file. The structures for the channels to be captured are copied to the rh_frmcal and rh_regcal entries corresponding to the traces or waveforms to which these channels are assigned.
Each of these structures contains three fields that permit conversion from A/D sample values to voltages. The ca_zero represents a zero volt level on the channel, expressed as an A/D sample value. The ca_height represents the height of a calibration pulse of known amplitude, expressed as a displacement in A/D sample values. The ca_level is the amplitude of this same calibration pulse in microvolts. Thus, to convert A/D samples for a given untriggered channel "i" to millivolts, one could use this formula:
(samp - (ca_zero of rh_regcal )) × (ca_level of rh_regcal )
i i
mv = -----------------------------------------------------------
(ca_height of rh_regcal ) × 1000
i
the equivalent in C Language, with required type conversions, would be:
mv = (samp-run.rh_regcal[i].ca_zero)
* (double)run.rh_regcal[i].ca_level
/ ((double)run.rh_regcal[i].ca_height * 1000.0);
Similar unit conversions must be done on the time axis, to convert from sample numbers to, say, milliseconds. The rh_samprate contains the base sampling rate at which the run was captured, so to calculate the the time of onset of the n-th sample at this rate, in milliseconds, the C formula would be:
ms = n * 1000.0 / run.rh_samprate; [1]
The complete C formula to calculate the time of onset of the n-th stored sample for untriggered channel "i" is:
ms = n * 1000.0 / (run.rh_samprate
/ run.rh_regdiv[i]); [2]
From the time of onset of the trigger pulse, the capture program waits for a length of time specified by the rh_delay field, then begins storing samples from the triggered channels into the new frame, for the length of time specified by the rh_window field. Both fields specify time as a number of samples at the base sampling rate. A negative delay indicates that pre-trigger sampling was performed in the frames. For any triggered channel with a divisor n greater than 1, only the first of every n samples is kept, starting with the first sample after the delay has passed. Since triggered channels can be stored at different rates, but for the same length of time in each frame, the number of sample points per frame can vary from channel to channel. The rh_npts array indicates the number of samples per frame for each triggered channel.
The time offset of the n-th sample of channel "i" from the start of the frame can be calculated with a variant of formula [2], using rh_frmdiv rather than rh_regdiv. The time offset of the n-th sample in a given frame, from the start of the run is:
ms = (frm.fh_sampnum + run.rh_delay
+ (n * run.rh_frmdiv[i]))
* 1000.0 / run.rh_samprate; [3]
The contents of this run header file consists of lines of parameter settings, much like shell variables, in the form
NAME='value'
By storing the time in UTC internally, we have a start time that is globally accurate even when data files travel across time zones. This is in contrast to the start date and time stored by Axoscope or pClamp in the ABF file's header, which is stored in local time. This can lead to some confusion if ABF files travel across time zones and are then converted by axon2run, as the resulting run file's start time will not accurately reflect the true local start time of the ABF file's capture. It is best to convert ABF files in the time zone in which they were captured, which can be overridden in software when running axon2run.