Input and Output Functions

ASCII Files

• IXTdataset_1d objects may be stored in ASCII files.
• These files may contain x and y data or x, s, error data in a 2 or 3 column format.
• Column 1 will be x values, column 2 will be s values and if available column 3 will be error values, if not available then error is assumed to be 0.
• Any information at the start or end of the file that is not in a 2 or 3 column format is ignored (for instance, header information may be stored here).
• Columns may be separated by commas, tabs, or spaces.
• ASCII files may contain point or histogram data, the x column in histogram data will have one more value than the s and e columns.

• The following files would all be acceptable ASCII files

title = plots1 xaxis = wavelength yaxis = signal 
490.2 30000
491.2 31923
492.2 40000

Represents a three point dataset with 0 error.

title = plots1 xaxis = wavelength yaxis = signal 
490.2 30000 300
491.2 31923 300 
492.2 40000 250
493.2

Represents a 3 column histogram dataset with error data.

490.2,30000,300
491.2,31923,300
492.2,40000,250
493.2

Will represent the same 3 column histogram dataset with error data.

• When files are written by libisis a header is written at the top of the file with the following information

name = dataset name
title = dataset title 
signal_units = dataset s axis label 
x_units = dataset x axis label
x_distribution = 1

x1 s1 e1
x2 s2 e2 
...

where the header information is taken from the dataset being written.

• To read and write ASCII files in the format (point or histogram) specified by the file or dataset use

>> read_ascii('filename')
>> write_ascii(dataset,'filename')

if no filename is given then the user will be prompted to locate the file.

Point Data

One can force the written or read ASCII file to be in the form of point data by using the commands

>>read_points('filename')
write_points(dataset, 'filename')

Histogram Data

One can force the written or read ASCII file to be in the form of histogram data by using the commands

>> read_hist('filename')
>> write_hist(dataset, 'filename')

RAW Files

RAW files come directly from instruments and can also be read into Libisis. Data can then be extracted from the RAW file to form an IXTdataset_1d or an IXTdataset_2d object.

• To read in a rawfile (in the form of an IXTraw_file object) use the command

>> rawfile1 = IXTraw_file('filename')

• To read data into an IXTdataset_1d object use the command

>> dataset = getspectrum(rawfile1, spectrum_number)

where spectrum_number is the spectrum which is required.

• to read multiple runs into an IXTdataset_2d object use the command

>> dataset_2d = getspectra(rawfile1, [start:end])

where start and end are the initial and final spectrum to include in the dataset_2d.

EXAMPLE:

>> rawfile1 = IXTraw_file('c:/RAWfiles/HET15958');
>> nsp = geti(rawfile1,'nsp1');
>> d2a = getspectra(rawfile1, [1:nsp]);
>> d1a = getspectrum(rawfile1, 25); 

this will load all spectra from the HET15958 raw file contained in the folder c:/RAWfiles into an IXTdataset_2d object called d2a and load spectrum 25 into an IXTdataset_1d object name d1a.

Using the

The Homer Utilites head and get_ei can be used to get extra information out of the raw file

gget

generic raw file access

it is possible at the matlab comand line to extract any variable from the rawfile by making a call to a populated IXTraw_file object.

>> rawfile=IXTraw_file('/path/to/my/file.raw')
>> value=gget(rawfile,'FIELD')

dae access

It is possible to access the data in the DAE by populating an IXTraw_file with a special string argument. We prefix DAE: to the name of the instrument control computer. Once this has been successfully populated all data access and get functions can be called.

>> rawf=IXTraw_file('DAE:ndxmerlin')
>> w1=getspectrum(rawf,1)
>> title=gget(rawf,'TITL')

This process is not possible with all instruments and requires the newest ICP to be installed. Full homer processes are possible but take a very long time, it is best used to access single spectra.

head

head() returns the header information for the raw file defined by the run_number, or the path to a defined raw file. Multiple run numbers can be combined together with limited practical use.

>>  head(run_number)
>>  head(path_to_raw_file)

• run_number can be defined in the following ways

1. a numerical array of numbers [12345 45673 34436] or a single numeric
2. an array of strings char('12345' '45673' '34436') or a single string
3. a cell array of strings {'12345' '45673' '34436'}
4. a cell array of numerics {12345 45673 34436}

• path_to_raw_file is defined as a string or a cell array of strings of the form 'C:\data\myfile.raw', relative paths are also possible as well as using the Global IXTpath objects 'inst_data:::myfile.raw' provided they have been set properly in the Instrument setup

mhead() returns the header information for each raw file defined by an array of run numbers, or an array of paths to a raw file.

>>  mhead(run_numbers)
>>  mhead(paths_to_raw_files)

• run_numbers can be defined in the following ways

1. a numerical array of numbers [12345 45673 34436]
2. an array of strings char('12345' '45673' '34436')
3. a cell array of strings {'12345' '45673' '34436'}
4. a cell array of numerics {12345 45673 34436}

• paths_to_raw_files is defined as a cell or string array of the form 'C:\data\myfile.raw', relative paths are also possible as well as using the Global IXTpath objects 'inst_data:::myfile.raw' provided they have been set properly in the Instrument setup

get_ei

get_ei() returns the energy of given a monochromatic run number, a guide energy can optionally be provided to focus the search for a monitor peak. It also optionally returns a structure containing the peak position, area and normalised area of the two monitors used to determine the energy. Multiple run numbers may be combined.

>>  [ei,props]=get_ei(run_number,ei_guess)
>>  [ei,props]=get_ei(path_to_raw_file,ei_guess)

• run_number can be defined in the following ways

1. a numerical array of numbers [12345 45673 34436] or a single numeric
2. an array of strings char('12345' '45673' '34436') or a single string
3. a cell array of strings {'12345' '45673' '34436'}
4. a cell array of numerics {12345 45673 34436}

• path_to_raw_file is defined as a string or a cell array of strings of the form 'C:\data\myfile.raw', relative paths are also possible as well as using the Global IXTpath objects 'inst_data:::myfile.raw' provided they have been set properly in the Instrument setup
• ei_guess is a single numeric value containing the starting ei for get_ei to use in its calculation

mget_ei()

>>  [ei,props]=mget_ei(run_numbers,ei_guesses)
>>  [ei,props]=mget_ei(path_to_raw_file,ei_guesses)

• run_numbers can be defined in the following ways

1. a numerical array of numbers [12345 45673 34436]
2. an array of strings char('12345' '45673' '34436')
3. a cell array of strings {'12345' '45673' '34436'}
4. a cell array of numerics {12345 45673 34436}

• paths_to_raw_files is defined as a cell or string array of the form 'C:\data\myfile.raw', relative paths are also possible as well as using the Global IXTpath objects 'inst_data:::myfile.raw' provided they have been set properly in the Instrument setup
• ei_guesses must be a numerical array equal to the number of run_numbers, containing the starting ei for mget_ei to use in the energy calculation for each run

• Other information is contained in the rawfile, see IXTraw_file documentation for more information.

Slices, Cuts and Masks

Some other programs can generate a slice, cut or mask object. Two such programs are mslice and Horace.

A slice can be read into a Libisis IXTdataset_2d object using the command

>>w = read_slice(filename)
w = read_slice

• filename is a string containing the location of the .slc file
• If filename is not given then a prompt will ask the user to locate the file
• Output is an IXTdataset_2d, with as much information taken from the slice as possible, otherwise fields are blank.

Similarly, a Mask or a cut from Horace / mslice can be read into Libisis IXTdataset_1d objects using the commands

>>w = read_cut(filename)
>> w = read_mask(filename)

• filename is a string containing the location of the .cut or .msk file
• If filename is not given then a prompt will ask the user to locate the file
• Output is an IXTdataset_1d, with as much information taken from the cut / mask as possible, otherwise fields are blank.

Nexus Files

Objects can be written to file in hdf format using the nexus API, using the write_nxs function. These files can also be read in using the read_nxs command.

>> write_nxs(IXTobject,'filename', entry)

• IXTobject is the object that is being written out (i.e. IXTrunfile, IXTdataset_2d)
• filename is a string showing the location of the .nxs file which is being written
• entry is a string, the top level directory to write the object to (i.e. 'runfile'), by default it is 'object' (optional)

Example:

write_nxs(IXTrunfile,'C:/nexusfiles/maps1020.nxs')

writes the data from the IXTrunfile object into the top-level directory 'runfile' of the maps1020.nxs file

>>w = read_nxs(filename, IXTobject, entry)

• filename is a string showing the location of the .nxs file
• IXTobject is the object that the data is being read into (i.e. IXTrunfile, IXTdataset_2d)
• entry is a string, the top level directory to read the object from (i.e. 'runfile'), by default it is 'object' (optional)
• w will be of the same object type as IXTobject (i.e. IXTrunfile)

Example:

wout = read_nxs('C:/nexusfiles/maps1020.nxs', IXTrunfile, 'runfile')

reads the data from the runfile top directory into the wout object that will be an IXTrunfile object.

Other Formats

Data can be read from other formats or in other ways, such as using Homer to populate an IXTrunfile object.