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)

where models is an array containing the nd*ne real*4 variables in the ensemble, data is a real*4 array containing the data misfit value for each model, mul is the number of records of length 4*(nd+1) bytes in the header and header is a character string of length nh containing other information.

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)

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

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 sites:

• NA homepage (where NA programs can be downloaded)
• Malcolm's homepage