Difference between revisions of "Input and Output Functions"

From LIBISIS
Jump to navigation Jump to search
 
(24 intermediate revisions by 3 users not shown)
Line 2: Line 2:
  
 
* [[IXTdataset_1d]] objects may be stored in ASCII files.  
 
* [[IXTdataset_1d]] objects may be stored in ASCII files.  
* These files may contain x and y data or x, y, error data in a 2 or 3 column format.  
+
* 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 y values and if available column 3 will be error values, if not available then error is assumed to be 0.  
+
* 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).  
 
* 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.  
 
* 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 y and e columns.  
+
* 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   
 
* The following files would all be acceptable ASCII files   
  
<pre>
+
<pre>title = plots1 xaxis = wavelength yaxis = signal  
title = plots1 xaxis = wavelength yaxis = signal  
 
 
490.2 30000
 
490.2 30000
 
491.2 31923
 
491.2 31923
492.2 40000
+
492.2 40000</pre>
</pre>
+
 
 +
Represents a three point dataset with 0 error.
  
Represents a three point dataset with 0 error
 
  
<pre>
+
<pre>title = plots1 xaxis = wavelength yaxis = signal  
title = plots1 xaxis = wavelength yaxis = signal  
 
 
490.2 30000 300
 
490.2 30000 300
 
491.2 31923 300  
 
491.2 31923 300  
 
492.2 40000 250
 
492.2 40000 250
493.2
+
493.2</pre>
</pre>
+
 
 +
Represents a 3 column histogram dataset with error data.
  
Represents a 3 column histogram dataset with error data
 
  
<pre>
+
<pre>490.2,30000,300
490.2,30000,300
 
 
491.2,31923,300
 
491.2,31923,300
 
492.2,40000,250
 
492.2,40000,250
Line 38: Line 36:
 
Will represent the same 3 column histogram dataset with error data.
 
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
 
  
<pre>
+
* 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  
+
<pre>name = dataset name
    signal_units = dataset s axis label  
+
title = dataset title  
    x_units = dataset x axis label
+
signal_units = dataset s axis label  
    x_distribution = 1
+
x_units = dataset x axis label
 +
x_distribution = 1
  
 
x1 s1 e1
 
x1 s1 e1
 
x2 s2 e2  
 
x2 s2 e2  
...
+
...</pre>
 +
 
 +
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
 +
 
 +
 
 +
<pre>>> read_ascii('filename')
 +
>> write_ascii(dataset,'filename')</pre>
  
</pre>
 
  
where the header information is taken from the dataset being written.
+
if no filename is given then the user will be prompted to locate the file.  
  
To read and write data to ASCII files in
 
  
  
 
=== Point Data ===  
 
=== Point Data ===  
 +
One can force the written or read ASCII file to be in the form of point data by using the commands
 +
 +
 +
<pre>>>read_points('filename')
 +
write_points(dataset, 'filename')</pre>
 +
 +
  
 
=== Histogram Data ===
 
=== Histogram Data ===
 +
One can force the written or read ASCII file to be in the form of histogram data by using the commands
 +
 +
 +
<pre>>> read_hist('filename')
 +
>> write_hist(dataset, 'filename')</pre>
  
  
Line 66: Line 83:
 
== RAW Files ==
 
== RAW Files ==
  
== Other Formats ==
+
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. One can do this in two different ways
 +
 
 +
 
 +
 
 +
=== Using RAW File Objects ===
 +
 
 +
 
 +
* To read in a rawfile (in the form of an [[IXTraw_file]] object) use the command
 +
 
 +
<pre>>> rawfile1 = IXTraw_file('filename')</pre>
 +
 
 +
 
 +
* To read data into an [[IXTdataset_1d]] object use the command
 +
 
 +
 
 +
<pre>>> dataset = getspectrum(rawfile1, spectrum_number)</pre>
 +
 
 +
 
 +
where '''spectrum_number''' is the spectrum which is required.
 +
 
 +
 
 +
* to read multiple runs into an [[IXTdataset_2d]] object use the command
 +
 
 +
 
 +
<pre>>> dataset_2d = getspectra(rawfile1, [start:end])</pre>
 +
 
 +
 
 +
where start and end are the initial and final spectrum to include in the dataset_2d.
 +
 
 +
 
 +
 
 +
''''' EXAMPLE: '''''
 +
 
 +
<pre>>> rawfile1 = IXTraw_file('c:/RAWfiles/HET15958');
 +
>> nsp = geti(rawfile1,'nsp1');
 +
>> d2a = getspectra(rawfile1, [1:nsp]);
 +
>> d1a = getspectrum(rawfile1, 25); </pre>
 +
 
 +
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.
 +
 
 +
 
 +
* Other information is contained in the rawfile, see [[IXTraw_file]] documentation for more information.
 +
 
 +
 
 +
 
 +
=== Assigning a RAW File ===
 +
 
 +
Rawfiles can also be assigned in the matlab environment. Once assigned, the rawfile will be used in any commands (such as getspectrum and getspectra) that are not given a rawfile object. All actions that can be performed on a rawfile object may be performed on the assigned runfile by simply omitting the rawfile object in the call to the function.
 +
 
 +
* Assigning RAW files makes routine operations quicker by omitting the need to enter an object name each time an operation is to be performed
 +
* Once a directory has been assigned, different file numbers (run numbers) can be chosen in a single command - making the process efficient.
 +
* Only one RAW file may be assigned at any one time
 +
 
 +
To assign a runfile use the commands
 +
 
 +
<pre> >> set_path(path)
 +
>> set_inst(inst)
 +
>> set_ext('RAW')
 +
>> ass(number)
 +
</pre>
 +
 
 +
* path is the path where the RAW file is stored
 +
* inst is the three letter abreviation of the instrument used to generate the raw file (e.g. MAP, MAR, MER, HET)
 +
* number is the raw file number (run number) that you wish to assign.
 +
 
 +
'''''Example:'''''
 +
 
 +
<pre> >> set_path('c:/maps_files/raw_files')
 +
>> set_inst('MAP')
 +
>> set_ext('RAW')
 +
>> ass(6404)
 +
</pre>
 +
 
 +
* A file must exist called C:/maps_files/raw_files/MAP06404.RAW
 +
 
 +
=== Plotting Spectra From Assigned RAW Files ===
 +
 
 +
One can plot spectra from assigned raw files using the following commands:
 +
 
 +
<pre> >> dl(spectrum)
 +
>> da(spectra)
 +
</pre>
 +
 
 +
* dl is any [[Plot Commands#One Dimensional Plots|one dimensional plot ]] command
 +
* da is any [[Plot Commands#Two Dimensional Plots|two dimensional plot]] command
 +
* spectrum is an array of numbers indicating which spectra of the currently assigned RAW file to plot
 +
* spectra is an array of numbers indicating which spectra of the currently assigned RAW file to plot in two dimensions.
 +
 
 +
 
 +
 
 +
==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
 +
 
 +
<pre>>>w = read_slice(filename)
 +
w = read_slice</pre>
 +
 
 +
* '''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
 +
 
 +
<pre> >> w = read_cut(filename)
 +
>> w = read_mask(filename)</pre>
 +
 
 +
* '''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.
 +
 
 +
 
 +
<pre>>> write_nxs(IXTobject,'filename', entry)</pre>
 +
 
 +
*'''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:'''''
 +
 
 +
 
 +
<tt> write_nxs(IXTrunfile,'C:/nexusfiles/maps1020.nxs')</tt>
 +
 
 +
 
 +
writes the data from the IXTrunfile object into the top-level directory 'runfile' of the maps1020.nxs file
 +
 
 +
 
 +
<pre>>>w = read_nxs(filename, IXTobject, entry)</pre>
 +
 
 +
*'''filename''' is a string showing the location of the .nxs file
 +
*'''IXTobject''' is the type of 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''' is the actual object which will hold the data being read, it will be of the same object type as IXTobject (i.e. [[IXTrunfile]])
 +
 
 +
 
 +
'''''Example:'''''
  
  
== Reading Data ==
+
<tt>wout = read_nxs('C:/nexusfiles/maps1020.nxs', IXTrunfile, 'runfile')</tt>
  
=== From a RAW File ===
 
  
=== From an ASCII File ===
+
reads the data from the runfile top directory into the wout object that will be an [[IXTrunfile]] object.
  
=== From Other Sources ===
 
  
== Writing Data ==
 
  
=== To an ASCII File ===
+
== Other Formats ==
  
=== To a Binary File ===
 
  
===
+
Data can be read from other formats or in other ways, such as using [[Homer_and_mgenie_style_functions| Homer]] to populate an [[IXTrunfile]] object.

Latest revision as of 16:10, 26 April 2009

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. One can do this in two different ways


Using RAW File Objects

  • To read in a rawfile (in the form of an IXTraw_file object) use the command
>> rawfile1 = IXTraw_file('filename')



>> 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.


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


Assigning a RAW File

Rawfiles can also be assigned in the matlab environment. Once assigned, the rawfile will be used in any commands (such as getspectrum and getspectra) that are not given a rawfile object. All actions that can be performed on a rawfile object may be performed on the assigned runfile by simply omitting the rawfile object in the call to the function.

  • Assigning RAW files makes routine operations quicker by omitting the need to enter an object name each time an operation is to be performed
  • Once a directory has been assigned, different file numbers (run numbers) can be chosen in a single command - making the process efficient.
  • Only one RAW file may be assigned at any one time

To assign a runfile use the commands

 >> set_path(path)
 >> set_inst(inst)
 >> set_ext('RAW')
 >> ass(number)
  • path is the path where the RAW file is stored
  • inst is the three letter abreviation of the instrument used to generate the raw file (e.g. MAP, MAR, MER, HET)
  • number is the raw file number (run number) that you wish to assign.

Example:

 >> set_path('c:/maps_files/raw_files')
 >> set_inst('MAP')
 >> set_ext('RAW')
 >> ass(6404)
  • A file must exist called C:/maps_files/raw_files/MAP06404.RAW

Plotting Spectra From Assigned RAW Files

One can plot spectra from assigned raw files using the following commands:

 >> dl(spectrum)
 >> da(spectra)
  • dl is any one dimensional plot command
  • da is any two dimensional plot command
  • spectrum is an array of numbers indicating which spectra of the currently assigned RAW file to plot
  • spectra is an array of numbers indicating which spectra of the currently assigned RAW file to plot in two dimensions.


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 type of 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 is the actual object which will hold the data being read, it 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.