Difference between revisions of "User Manual"

From LIBISIS
Jump to navigation Jump to search
 
(48 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
There are many different Matlab commands within Libisis. These include basic commands, such as taking the exponential of a dataset, through to integration and plotting commands. The following is an online user manual for the matlab interface of the Libisis software.  
 
There are many different Matlab commands within Libisis. These include basic commands, such as taking the exponential of a dataset, through to integration and plotting commands. The following is an online user manual for the matlab interface of the Libisis software.  
 +
  
 
== Overview ==
 
== Overview ==
  
There are many different object types within Libisis used to store experimental data. Once an object is created, functions exist to manipulate the data contained within. The most common objects for plotting and data manipulation are [[IXTdataset_1d]] and [[IXTdataset_2d]] objects. All relevant data pertaining to a run can be stored in an [[IXTrunfile]] object. Data from many different file formats may be read into these objects for manipulation. Described below are many different functions for handling data.
+
There are many different object types within Libisis used to store experimental data. Once an object is created, functions exist to manipulate the data contained within. The most common objects for plotting and data manipulation are [[IXTdataset_1d]], [[IXTdataset_2d]] and [[IXTdataset_3d]] objects. [[IXTrunfile]] objects contain all raw data from a run.
 +
 
 +
 
 +
[[IXTdataset_1d]] objects store signal and error information against one dimension (the x axis). Label and titling information is also stored. [[IXTdataset_2d]] objects also contain a second dimension (the y axis). As would be expected [[IXTdataset_3d]] objects contain yet another (z) dimension. [[IXTpolygons]] contains a list of shapes with signal data that can be plotted. All relevant data pertaining to a run can be stored in an [[IXTrunfile]] object. The object can be thought of as an array of [[IXTdataset_2d]] objects with a lot of additional information. [[IXTdataset_1d]], [[IXTdataset_2d]] and [[IXTrunfile]] have fully implemented and similar functions, [[IXTdataset_3d]] and [[IXTpolygons]] are a special case and do not have many of the data manipulation functions as of yet.
 +
 
 +
 
 +
Data is read into these objects (using methods described below) and can then be manipulated using many different tools and functions described in this documentation.  
 +
 
  
===[[Directory Structure]]===
+
===[[General Behaviour]]===
The functions are organised into a particular directorary structure outlined [[Directory Structure | here]].
+
Most functions share a general behaviour outlined [[General Behaviour|here]]
  
 
==Data Manipulation Functions==
 
==Data Manipulation Functions==
 +
  
 
=== [[Input and Output Functions]] ===
 
=== [[Input and Output Functions]] ===
These functions are used for importing data into Libisis and exporting data from Libisis into file formats.
+
 
 +
 
 +
Below are just a few of the possible read and write functions, [[Input and Output Functions#Other Formats|other formats]] can also be used.
 +
 
 +
* [[Input and Output Functions#Assigning a RAW File|set_path]], [[Input and Output Functions#Assigning a RAW File|set_inst]]. [[Input and Output Functions#Assigning a RAW File|set_ext]], [[Input and Output Functions#Assigning a RAW File|ass]].
 +
 
 +
*[[Input and Output Functions#RAW Files|getspectra]], [[Input and Output Functions#RAW Files|getspectrum]] - Read in spectra from IXTraw_file objects or from RAW files
 +
 
 +
*[[Input and Output Functions#ASCII Files|read_ascii]], [[Input and Output Functions#ASCII Files|write_ascii]] - Read or write to text files
 +
 
 +
*[[Input and Output Functions#Point Data|read_points]], [[Input and Output Functions#Point Data|write_points]] - Read or write to text files, forcing data to be point data
 +
 
 +
*[[Input and Output Functions#Histogram Data|read_hist]], [[Input and Output Functions#Histogram Data|write_hist]] - Read or write to text files, forcing data to be histogram data
 +
 
 +
*[[Input and Output Functions#Slices, Cuts and Masks|read_slice]], [[Input and Output Functions#Slices, Cuts and Masks|read_cut]], [[Input and Output Functions#Slices, Cuts and Masks|read_mask]] - Special functions to read from other formats
 +
 
 +
* [[Input and Output Functions#Nexus Files|read_nxs]] [[Input and Output Functions#Nexus Files|write_nxs]]- Read and write from Nexus file format
 +
 
 +
* [[Using Homer and Getting Started|Homer]] - Information about using Homer to import data into Libisis
 +
 
 +
 
 +
 
 
=== [[Binary Operators]] ===
 
=== [[Binary Operators]] ===
 +
 +
 
Binary operators such as +, -, *, etc. are used to perform arithmetic operations between datasets and/or numbers  
 
Binary operators such as +, -, *, etc. are used to perform arithmetic operations between datasets and/or numbers  
 +
 +
 +
 
=== [[Elementary Functions]]===
 
=== [[Elementary Functions]]===
Elementary functions such as sin, cos and tan can be used on datasets
+
 
 +
 
 +
Elementary functions act on each signal element identically
 +
 
 +
*[[Elementary Functions|log]], [[Elementary Functions|exp]] - logarithmic functions
 +
 
 +
*[[Elementary Functions|sin]], [[Elementary Functions|cos]], [[Elementary Functions|tan]] - trigonomic functions
 +
 
 +
*[[Elementary Functions|sinh]], [[Elementary Functions|cosh]], [[Elementary Functions|tanh]] - hyperbolic functions
 +
 
 +
 
 +
 
 
=== [[Data Manipulation Functions]] ===
 
=== [[Data Manipulation Functions]] ===
[[Data Manipulation Functions#Shift Functions|shift]], [[Data Manipulation Functions#Shift Functions|shift_x]], [[Data Manipulation Functions#Shift Functions|shift_y]], [[Data Manipulation Functions#Shift Functions|shift_xy]]
 
  
[[Data Manipulation Functions#Scale Functions|scale]], [[Data Manipulation Functions#ScaleFunctions|scale_x]], [[Data Manipulation Functions#Scale Functions|scale_y]]
 
  
[[Data Manipulation Functions#Flip Functions|flip]], [[Data Manipulation Functions#Flip Functions|flip_x]], [[Data Manipulation Functions#Flip Functions|flip_y]]
+
*[[Data Manipulation Functions#Shift Functions|shift]], [[Data Manipulation Functions#Shift Functions|shift_x]], [[Data Manipulation Functions#Shift Functions|shift_y]], [[Data Manipulation Functions#Shift Functions|shift_xy]] - Shift data along an independent axis
 +
 
 +
*[[Data Manipulation Functions#Scale Functions|scale]], [[Data Manipulation Functions#ScaleFunctions|scale_x]], [[Data Manipulation Functions#Scale Functions|scale_y]] - Scale one of the independent axes
 +
 
 +
*[[Data Manipulation Functions#Flip Functions|flip]], [[Data Manipulation Functions#Flip Functions|flip_x]], [[Data Manipulation Functions#Flip Functions|flip_y]] - Reverse the data in a dataset
 +
 
 +
 
  
 
=== [[Rebin Functions]] ===
 
=== [[Rebin Functions]] ===
[[Rebin Functions#Rebin Functions|rebin]], [[Rebin Functions#Rebin Functions|rebin_x]], [[Rebin Functions#Rebin Functions|rebin_y]], [[Rebin Functions#Rebin Functions|rebin_xy]]
 
  
[[Rebin Functions#Rebunch Functions|rebunch]], [[Rebin Functions#Rebunch Functions|rebunch_x]], [[Rebin Functions#Rebunch Functions|rebunch_y]], [[Rebin Functions#Rebunch Functions|rebunch_xy]]
 
  
[[Rebin Functions#Rgroup Functions|regroup]], [[Rebin Functions#Rgroup Functions|regroup_x]],  
+
Three different methods exist for rebinning a function. Rebin will rebin the data into user defined bins. Rebunch will bunch together a user defined number of bins. Regroup rebins data using a minimum binwidth given by the user but insures that the new bins are coincident with the existing bins.
[[Rebin Functions#Rgroup Functions|regroup_y]], [[Rebin Functions#Rgroup Functions|regroup_xy]]
+
 
 +
*[[Rebin Functions#Rebin Functions|rebin]], [[Rebin Functions#Rebin Functions|rebin_x]], [[Rebin Functions#Rebin Functions|rebin_y]], [[Rebin Functions#Rebin Functions|rebin_xy]]
 +
 
 +
*[[Rebin Functions#Rebunch Functions|rebunch]], [[Rebin Functions#Rebunch Functions|rebunch_x]], [[Rebin Functions#Rebunch Functions|rebunch_y]], [[Rebin Functions#Rebunch Functions|rebunch_xy]]
 +
 
 +
*[[Rebin Functions#Rgroup Functions|regroup]], [[Rebin Functions#Rgroup Functions|regroup_x]], [[Rebin Functions#Rgroup Functions|regroup_y]], [[Rebin Functions#Rgroup Functions|regroup_xy]]
 +
 
 +
 
  
 
=== [[High Level Functions]] ===
 
=== [[High Level Functions]] ===
  
[[High Level Functions#First Derivative|deriv1x]], [[High Level Functions#Second Derivative|deriv2x]], [[High Level Functions#First Derivative|deriv1y]], [[High Level Functions#Second Derivative|deriv2y]], [[High Level Functions#First Derivative|deriv1]], [[High Level Functions#Second Derivative|deriv2]]
 
  
[[High Level Functions#Integral Functions|integrate_x]], [[High Level Functions#Integral Functions|integrate_y]], [[High Level Functions#Integral Functions|integrate_xy]], [[High Level Functions#Integral Functions|integrate]]
+
*[[High Level Functions#First Derivative|deriv1x]], [[High Level Functions#Second Derivative|deriv2x]], [[High Level Functions#First Derivative|deriv1y]], [[High Level Functions#Second Derivative|deriv2y]], [[High Level Functions#First Derivative|deriv1]], [[High Level Functions#Second Derivative|deriv2]] - Takes derivatives of a dataset
  
[[High Level Functions#Smooth Functions|smooth]]
+
*[[High Level Functions#Integral Functions|integrate_x]], [[High Level Functions#Integral Functions|integrate_y]], [[High Level Functions#Integral Functions|integrate_xy]], [[High Level Functions#Integral Functions|integrate]] - Integrates a dataset between user defined limits
  
[[High Level Functions#Interpolate Functions|interp_x]], [[High Level Functions#Interpolate Functions|interp_y]], [[High Level Functions#Interpolate Functions|interp]]
+
*[[High Level Functions#Smooth Functions|smooth]] - Smooths out signal data to avoid small, sharp deviations
  
[[High Level Functions#Unspike Functions|unspike]]
+
*[[High Level Functions#Interpolate Functions|interp_x]], [[High Level Functions#Interpolate Functions|interp_y]], [[High Level Functions#Interpolate Functions|interp]] - Interpolates data onto a different set of points
  
[[High Level Functions#Fit Functions|fit]]
+
*[[High Level Functions#Unspike Functions|unspike]] - Removes any large spikes from the data
 +
 
 +
*[[High Level Functions#Fit Functions|fit]] - Fitting data to known functions and giving curves of best fit
 +
 
 +
*[[High Level Functions#Function Evaluation|func_eval]] - Evaluate a function at the given x and y data points
  
[[High Level Functions#Function Evaluation|func_eval]]
 
  
  
 
=== [[Special Functions]] ===
 
=== [[Special Functions]] ===
Special functions are provided, mainly for internal use, to convert datasets or change the properties of a dataset.  
+
 
 +
 
 +
Special functions are used to transform data between different types.
 +
 
 +
*[[Special Functions#Contract Functions|contract]] - Turn an array of [[IXTdataset_2d]] objects into a single [[IXTdataset_2d]] object
 +
 
 +
*[[Special Functions#Expand Functions|expand_d1d]], [[Special Functions#Expand Functions|expand_listd1d]], [[Special Functions#Expand Functions|expand_d2d]], [[Special Functions#Expand Functions|expand_listd2d]] - Expand single objects into many objects
 +
 
 +
*[[Special Functions#Conversion Functions|oned_to_twod]] - Convert an [[IXTdataset_1d]] into an [[IXTdataset_2d]]
 +
 
 +
*[[Special Functions#Conversion Functions|hist2point]], [[Special Functions#Conversion Functions|hist2point_x]], [[Special Functions#Conversion Functions|hist2point_y]] - Convert between histogram and point data
 +
 
 +
*[[Special Functions#Noisify|noisify]] - Add noise to a dataset.
 +
 
 +
 
  
 
==Graphics==
 
==Graphics==
 +
 +
 +
===[[Using Default Properties and Name Tags]]===
 +
 +
 +
Default properties and name tags are an integral part of Libisis graphics. They allow greater control of plots and it is particularly important to know about them when building applications on top of the Libisis structure. Names and tags can be used to easily identify and set properties for plots.
 +
 +
 
===[[Plot Commands]]===
 
===[[Plot Commands]]===
There are many different ways to plot datasets, these are all outlined [[Plot Commands | here]].
+
 
 +
 
 +
*[[Plot Commands#One Dimensional Plots|dh]], [[Plot Commands#One Dimensional Plots|dl]], [[Plot Commands#One Dimensional Plots|dm]], [[Plot Commands#One Dimensional Plots|de]], [[Plot Commands#One Dimensional Plots|dp]], [[Plot Commands#One Dimensional Plots|dd]] - One dimensional plotting commands
 +
 
 +
*[[Plot Commands#Overplots|ph]], [[Plot Commands#Overplots|pl]], [[Plot Commands#Overplots|pm]], [[Plot Commands#Overplots|pe]], [[Plot Commands#Overplots|pp]], [[Plot Commands#Overplots|pd]] - over plotting commands
 +
 
 +
*[[Plot Commands#Two Dimensional Plots|ds]], [[Plot Commands#Two Dimensional Plots|da]], [[Plot Commands#Two Dimensional Plots|mp]] - Two dimensional plotting commands
 +
 
 +
*[[Plot Commands#Three Dimensional Plots|sm]] - Sliceomatic (three dimensional) plotting
 +
 
 
===[[Pre-Emptive Formatting]]===
 
===[[Pre-Emptive Formatting]]===
Many properties can be set before a plot is made, for instance on a line plot, the line colour may be set before a plot is made
+
 
 +
 
 +
*[[Pre-Emptive Formatting#Colors|acolor]], [[Pre-Emptive Formatting#Lines|aline]], [[Pre-Emptive Formatting#Markers|amark]] - Change default properties of plots before they are made
 +
 
 +
 
 
===[[Retrospective Formatting]]===
 
===[[Retrospective Formatting]]===
Most formatting is performed after a plot is made. This includes changing limits and  
+
 
 +
 
 +
*[[Retrospective Formatting#Limits|lx]], [[Retrospective Formatting#Limits|ly]], [[Retrospective Formatting#Limits|lz]] - Changes the limits of the axes
 +
 
 +
*[[Retrospective Formatting#Changing the Scale to Log|linlogbutton]], [[Retrospective Formatting#Changing the Scale to Log|linlogmenu]], [[Retrospective Formatting#Changing the Scale to Log|linx]], [[Retrospective Formatting#Changing the Scale to Log|liny]], [[Retrospective Formatting#Changing the Scale to Log|linz]], [[Retrospective Formatting#Changing the Scale to Log|logx]] ,[[Retrospective Formatting#Changing the Scale to Log|logy]] ,[[Retrospective Formatting#Changing the Scale to Log|logz]] - changes the axes scale to logarithmic or linear
 +
 
 +
*[[Retrospective Formatting#Changing the Aspect Ratio|aspect]] - changes the aspect ratio
 +
 
 +
*[[Retrospective Formatting#Finding Points on a Plot|dxy]],[[Retrospective Formatting#Finding Points on a Plot|dxyz]],[[Retrospective Formatting#Finding Points on a Plot|dxyc]] - returns the co-ordinates of a clicked point on a plot, and/or marks the point with a label
 +
 
 +
*[[Retrospective Formatting#Figure Control Functions|kf / keep_figure]], [[Retrospective Formatting#Figure Control Functions|rf / release_figure]] - hold or release a figure window
 +
 
 +
*[[Retrospective Formatting#Advanced Controls|set_plot]], [[Retrospective Formatting#Advanced Controls|set_axes]], [[Retrospective Formatting#Advanced Controls|set_figure]] - set advanced properties in the figure, axes or plot
 +
 
 +
*[[Retrospective Formatting#Adding a Legend|set_legend]] - adds a legend to the plot
 +
 
 +
 
 
===[[Other Commands]]===
 
===[[Other Commands]]===
Some other commands are contained within the graphics package to facilitate the advanced user.
 
  
==Full Function List==
 
  
[[dean's test page]]
+
*[[Other Commands#Renaming a Plot|rename]] - rename a plot but keep default properties
 +
 
 +
*[[Other Commands#Extracting Information|fromplot]], [[Other Commands#Other Information|get_all_name_tags]], [[Other Commands#Other Information|get_all_handles]], [[Other Commands#Other Information|get_handles]], [[Other Commands#Other Information|check_figure]] - get information from a plot
 +
 
 +
* [[Other Commands#Setting Default Properties|set_user_preferences]], [[Other Commands#Setting Default Properties|set_default_properties]], [[Other Commands#Setting Default Properties|reset_default]], [[Other Commands#Setting Default Properties|reset_all]] - set (or reset) default properties for plot types
 +
 
 +
*[[Other Commands#Undo Last Plot|undop]] - undo the last plot
 +
 
 +
*[[Other Commands#Add a Color Slider|color_slider]] - add a color slider to a [[Plot Commands#Two Dimensional Plots|two dimensional plot]]
 +
 
 +
*[[Other Commands#Alias|alias]] - make an alias for a function
 +
 
 +
 
 +
 
 +
===[[User Reference]]===
 +
 
 +
 
 +
Information for reference purposes, such as valid linestyles, marker styles etc.
 +
 
 +
 
 +
==[[Tutorial]]==
 +
 
 +
A general tutorial. This is mainly from the graphics viewpoint but should provide a good overview of how to do things.
 +
 
 +
 
 +
*[[Tutorial#Before You Begin]]
 +
*[[Tutorial#Introduction To Libisis]]
 +
*[[Tutorial#Reading In Data]]
 +
*[[Tutorial#Setting Colours and Styles on 1d Plots]]
 +
*[[Tutorial#Two Dimensional Plotting]]
 +
*[[Tutorial#Reading from a slice]]
 +
*[[Tutorial#Data Manipulation In Matlab]]
 +
*[[Tutorial#Some Rebinning]]
 +
*[[Tutorial#Some Binary Operations]]
 +
*[[Tutorial#Integrating Data]]
 +
*[[Tutorial#Fitting]]
 +
*[[Tutorial#Using the Homer GUI]]
 +
*[[Tutorial#Getting Help]]

Latest revision as of 10:29, 22 October 2009

There are many different Matlab commands within Libisis. These include basic commands, such as taking the exponential of a dataset, through to integration and plotting commands. The following is an online user manual for the matlab interface of the Libisis software.


Overview

There are many different object types within Libisis used to store experimental data. Once an object is created, functions exist to manipulate the data contained within. The most common objects for plotting and data manipulation are IXTdataset_1d, IXTdataset_2d and IXTdataset_3d objects. IXTrunfile objects contain all raw data from a run.


IXTdataset_1d objects store signal and error information against one dimension (the x axis). Label and titling information is also stored. IXTdataset_2d objects also contain a second dimension (the y axis). As would be expected IXTdataset_3d objects contain yet another (z) dimension. IXTpolygons contains a list of shapes with signal data that can be plotted. All relevant data pertaining to a run can be stored in an IXTrunfile object. The object can be thought of as an array of IXTdataset_2d objects with a lot of additional information. IXTdataset_1d, IXTdataset_2d and IXTrunfile have fully implemented and similar functions, IXTdataset_3d and IXTpolygons are a special case and do not have many of the data manipulation functions as of yet.


Data is read into these objects (using methods described below) and can then be manipulated using many different tools and functions described in this documentation.


General Behaviour

Most functions share a general behaviour outlined here

Data Manipulation Functions

Input and Output Functions

Below are just a few of the possible read and write functions, other formats can also be used.

  • Homer - Information about using Homer to import data into Libisis


Binary Operators

Binary operators such as +, -, *, etc. are used to perform arithmetic operations between datasets and/or numbers


Elementary Functions

Elementary functions act on each signal element identically

  • log, exp - logarithmic functions


Data Manipulation Functions


Rebin Functions

Three different methods exist for rebinning a function. Rebin will rebin the data into user defined bins. Rebunch will bunch together a user defined number of bins. Regroup rebins data using a minimum binwidth given by the user but insures that the new bins are coincident with the existing bins.


High Level Functions

  • smooth - Smooths out signal data to avoid small, sharp deviations
  • unspike - Removes any large spikes from the data
  • fit - Fitting data to known functions and giving curves of best fit
  • func_eval - Evaluate a function at the given x and y data points


Special Functions

Special functions are used to transform data between different types.


Graphics

Using Default Properties and Name Tags

Default properties and name tags are an integral part of Libisis graphics. They allow greater control of plots and it is particularly important to know about them when building applications on top of the Libisis structure. Names and tags can be used to easily identify and set properties for plots.


Plot Commands

  • ds, da, mp - Two dimensional plotting commands
  • sm - Sliceomatic (three dimensional) plotting

Pre-Emptive Formatting


Retrospective Formatting

  • lx, ly, lz - Changes the limits of the axes
  • aspect - changes the aspect ratio
  • dxy,dxyz,dxyc - returns the co-ordinates of a clicked point on a plot, and/or marks the point with a label


Other Commands

  • rename - rename a plot but keep default properties
  • undop - undo the last plot
  • alias - make an alias for a function


User Reference

Information for reference purposes, such as valid linestyles, marker styles etc.


Tutorial

A general tutorial. This is mainly from the graphics viewpoint but should provide a good overview of how to do things.