NAD files
This page describes a NAD (Neighbourhood Algorithm Direct access) file. This is the format in which na-sampler writes out all of the points (models) in parameter space generated by the neighbourhood algorithm.
A NAD file is read in by other programs which use the models generated by na-sampler, e.g. na-bayes and S-plot. Utility programs are included in the na-sampler package to read and write NAD files. For example readnad reads the NAD file and writes some summary information to the screen.
Format
NAD is an unformatted direct access file consisting of three parts which produce a total of 4*(nd*ne+ne+5)+nh+nhu bytes, where nd is the number of dimensions in the parameter space (i.e. the number of variables), ne is the number of models in the ensemble, nh is the length in bytes of a file header, and nhu is the number of bytes in the user portion of that file header ( nhu < nh ).
A multi-record direct access file format is used for compactness in storing the ensemble, and speed of I/O. The record length for NAD files is 4*(nd+1) bytes, and the total number of records is mul*4*(nd+1). FORTRAN routines read_nad and write_nad are provided for reading and writing NAD files. They write a NAD file using the following code,
len = 4*(5+nd*ne+ne)+nh
open(lu,file=fnme,status='unknown',form='unformatted',
access='direct',recl=len)
write(lu,rec=1)-mul,nd,ne,nh,nhu,header
close (lu)
len = 4*(nd+1)
open(lu,file=fnme,status='unknown',form='unformatted',
access='direct',recl =len)
do i = 1,ne
write(lu,rec=i+mul)(models(i,k),k=1,nd),data(i)
end do
close (lu)
Two parts to the header
The header block is split into two parts. The first contains nh-nhu bytes and is reserved for use by the NA-programs. The second is provided so that the user may write information into a NAD header, e.g date, run details etc. In this way users may make use of NAD files in their own analysis programs etc. The length of the user header is nhu bytes and is written in the user subroutine writemodels supplied to the program na-sampler. The user portion of the header may be of any length including zero. If you do not wish to use NAD files in your own programs then the simplest thing to do in subroutine writemodels is to return the length of the user NAD header as zero (i.e. set nhu=0).
Writing a NAD header (user's part)
For example a FORTRAN subroutine that writes the real*4 array mydata(100) and the integers n1,n2 and n3 into the header, could look like this
Subroutine (header,nhu,mydata,n1,n2,n3)
real*4 mydata(100)
character header(412)
nhu = 4*(3+100)
open(lu,file='naduser',status='unknown',form='unformatted',
access='direct',recl=nhu)
write(lu,rec=1)n1,n2,n3,mydata
close(lu)
open(lu,file='naduser',status='unknown',form='unformatted',
access='direct',recl=nhu)
read(lu,rec=1)header
close(lu)
return
Note that the user variables are first written out to a direct access file and then read back in again into the character string header, which is returned to the main program. In the program na-sampler the internal header string is then added to the front of this character string.
The same array variables could be read back from the temporary file 'naduser' with FORTRAN code like this.
real*4 mydata(100)
len = 4*(3+100)
open(lu,file=fnme,status='unknown',form='unformatted',access='direct',recl=len)
write(lu,rec=1)hdummy
where hdummy is a character string of length nh-nhu bytes. The reserved portion of the header is built in a similar manner. Note that it is allowed that nhu = 0, which means that the user portion of the header file is empty.
Format of the reserved portion of the NAD header
The reserved portion of a NAD header file is used to pass information to other programs that make use of NAD files. For example the programs in the package NA-bayes (i.e. nab.f and naplot.f). Currently the reserved header portion is read from the nad file with the following f77 code.
real*4 range(2,nd)
real*4 scales(nd+1)
len = 4*(8+3*nd)
open(lu,file=fnme,status='old',form='unformatted',access='direct',recl=len)
read(lu,rec=1)-mul,nd,ne,nh,nhu,ns1,ns,nr,range,scales
Note that the last 4 variables (i.e. 4*(1+3*nd) bytes) define the format of the reserved NAD header. We call it `reserved' because the user is not allowed to change it, however it may be necessary for the user to know its format if writing ones own NAD files, e.g. for input into NA-bayes. At the present time the reserved NAD header simply contains the definition of the parameter space ranges, scale factors and the three parameters ns1,ns and nr used in the NA sampler program.
Note the program nab.f in NA-bayes gets the definition of the parameter space ranges from this NAD file. Note that the format of the reserved portion of the NAD header may change in the future, however, its size will always be set at nh-nhu and so it can always be skipped over when reading NAD files.
Related links:
NA homepage - where the latest versions of NA-Bayes and NA-sampler can be accessed.
NA-sampler - the latest version of this manual.
splot - graphics program for display of multi-dimensional ensembles.
RFI - Receiver function utility programs and graphics (included with NA-Sampler package.)
NA-Bayes - the manual for the neighbourhood algorithm Bayesian inference package.
naplot - graphics program for displaying Bayesian estimators (included with NA-Bayes package).
summary.pdf - A short summary of NA-sampler written for the IASPEI handbook (PDF file)