diff --git a/docs/source/api/python/mantid/api/IEventWorkspace.rst b/docs/source/api/python/mantid/api/IEventWorkspace.rst
index 359981467b60e4d1882de05017f6866533ed511d..bec9724dd59bf802f19ebd79b93bbc43c03ff72f 100644
--- a/docs/source/api/python/mantid/api/IEventWorkspace.rst
+++ b/docs/source/api/python/mantid/api/IEventWorkspace.rst
@@ -1,3 +1,5 @@
+.. _mantid.api.IEventWorkspace:
+
=================
IEventWorkspace
=================
diff --git a/docs/source/api/python/mantid/api/MatrixWorkspace.rst b/docs/source/api/python/mantid/api/MatrixWorkspace.rst
index f7d69a1fc061e0e28225ef3e50bd2d8c7a327a10..e83b1e1f45383be1fb0a119f4e0a32afce9efad4 100644
--- a/docs/source/api/python/mantid/api/MatrixWorkspace.rst
+++ b/docs/source/api/python/mantid/api/MatrixWorkspace.rst
@@ -1,3 +1,5 @@
+.. _mantid.api.MatrixWorkspace:
+
=================
MatrixWorkspace
=================
diff --git a/docs/source/api/python/mantid/api/Run.rst b/docs/source/api/python/mantid/api/Run.rst
index f5b3463ddc19a1ca37feb383cfba87657b453f97..0138e1103f6a25297f5978b003753878507e4934 100644
--- a/docs/source/api/python/mantid/api/Run.rst
+++ b/docs/source/api/python/mantid/api/Run.rst
@@ -1,3 +1,5 @@
+.. _mantid.api.Run:
+
=====
Run
=====
diff --git a/docs/source/api/python/mantid/api/Sample.rst b/docs/source/api/python/mantid/api/Sample.rst
index cd8af4d42b43ce52465dfec3d3612a4c4b8fa0d6..8cb15a0ab8da3ccc366bdc60c880e812400477b4 100644
--- a/docs/source/api/python/mantid/api/Sample.rst
+++ b/docs/source/api/python/mantid/api/Sample.rst
@@ -1,3 +1,5 @@
+.. _mantid.api.Sample:
+
========
Sample
========
diff --git a/docs/source/api/python/mantid/api/Workspace.rst b/docs/source/api/python/mantid/api/Workspace.rst
index 48a295f86682b159dfd9a59311686b7ed5a48abe..a552bf94f99f75d3c4a11053aadd6a9f37acea99 100644
--- a/docs/source/api/python/mantid/api/Workspace.rst
+++ b/docs/source/api/python/mantid/api/Workspace.rst
@@ -1,3 +1,5 @@
+.. _mantid.api.Workspace:
+
===========
Workspace
===========
diff --git a/docs/source/concepts/EventWorkspace.rst b/docs/source/concepts/EventWorkspace.rst
index b7bcce91b4b590366caf825176def99994d2de7b..68a82b6804f3c082cfb47ac09e5c452dcaf140b4 100644
--- a/docs/source/concepts/EventWorkspace.rst
+++ b/docs/source/concepts/EventWorkspace.rst
@@ -1,8 +1,12 @@
.. _EventWorkspace:
+===============
Event Workspace
===============
+.. contents::
+ :local:
+
Quick Summary For Users
-----------------------
@@ -11,7 +15,7 @@ where the information about each individual neutron detection event is
maintained. For you as a user, this means that:
- You can :ref:`rebin <algm-rebin>` an EventWorkspace over and over and no
- information is ever lost.
+ information is ever lost (as long as you choose the PreserveEvents option).
- The histogram (Y and E values) of an EventWorkspace are only
calculated when they are requested.
@@ -35,6 +39,178 @@ maintained. For you as a user, this means that:
your data as an EventWorkspace for as much processing as is possible
(as long as you have enough memory!).
+Working with Event Workspaces in Python
+----------------------------------------
+
+EventWorkspace is designed to be able to be read (but not written to)
+like a :ref:`MatrixWorkspace <MatrixWorkspace>`. You can look at the :ref:`Event Workspace API reference <mantid.api.IEventWorkspace>` for a full list of properties and operations, but here are some of the key ones.
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to an EventWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is an Event Workspace you can use this:
+
+.. testcode:: CheckEventWorkspace
+
+ from mantid.api import IEventWorkspace
+
+ eventWS = CreateSampleWorkspace(WorkspaceType="Event")
+
+ if isinstance(eventWS, IEventWorkspace):
+ print eventWS.getName() + " is an " + eventWS.id()
+
+Output:
+
+.. testoutput:: CheckEventWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ eventWS is an EventWorkspace
+
+
+Event Workspace Properties
+###########################
+
+In addition to the Properties of the :ref:`MatrixWorkspace <MatrixWorkspace>`, the Event Workspace also has the following:
+
+.. testcode:: EventWorkspaceProperties
+
+ eventWS = CreateSampleWorkspace(WorkspaceType="Event")
+
+ print "Number of events:", eventWS.getNumberEvents()
+ print "Maximum time of flight:", eventWS.getTofMax()
+
+.. testoutput:: EventWorkspaceProperties
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of events: ...
+ Maximum time of flight: ...
+
+Event lists
+###########
+
+Event Workspaces store their data in event lists, one per spectrum. You can access them using:
+
+.. testcode:: EventWorkspaceEventLists
+
+ eventWS = CreateSampleWorkspace(WorkspaceType="Event")
+
+ # get the number of event lists
+ evListCount = eventWS.getNumberHistograms()
+
+ # Get the first event list
+ evList = eventWS.getEventList(0)
+
+ # Get some basic information
+ print "Number of events in event List 0:", evList.getNumberEvents()
+ print "Minimum time of flight in event List 0:", evList.getTofMax()
+ print "Maximum time of flight in event List 0:", evList.getTofMax()
+ print "Memory used:", evList.getMemorySize()
+ print "Type of Events:", evList.getEventType()
+
+ # Get a vector of the pulse times of the events
+ pulseTimes = evList.getPulseTimes()
+
+ # Get a vector of the TOFs of the events
+ tofs = evList.getTofs()
+
+ # Get a vector of the weights of the events
+ weights = evList.getWeights()
+
+ # Get a vector of the errors squared of the weights of the events
+ weightErrors = evList.getWeightErrors()
+
+ # Integrate the events between a range of X values
+ print "Events between 1000 and 5000:", evList.integrate(1000,5000,False)
+
+ #Check if the list is sorted in TOF
+ print "Is sorted by TOF:", evList.isSortedByTof()
+
+.. testoutput:: EventWorkspaceEventLists
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of events in event List 0: ...
+ Minimum time of flight in event List 0: ...
+ Maximum time of flight in event List 0: ...
+ Memory used: ...
+ Type of Events: TOF
+ Events between 1000 and 5000: ...
+ Is sorted by TOF: True
+
+Changing EventLists
+^^^^^^^^^^^^^^^^^^^
+
+Please note these should only be done as part of a Python Algorithm, otherwise these actions will not be recorded in the workspace history.
+
+
+.. testcode:: ChangingEventLists
+
+ import math
+ eventWS = CreateSampleWorkspace(WorkspaceType="Event")
+ # Get the first event list
+ evList = eventWS.getEventList(0)
+
+ # Add an offset to the pulsetime (wall-clock time) of each event in the list.
+ print "First pulse time before addPulsetime:", evList.getPulseTimes()[0]
+ seconds = 200.0
+ evList.addPulsetime(seconds)
+ print "First pulse time after addPulsetime:", evList.getPulseTimes()[0]
+
+ # Add an offset to the TOF of each event in the list.
+ print "First tof before addTof:", evList.getTofs()[0]
+ microseconds = 2.7
+ evList.addTof(microseconds)
+ print "First tof after addTof:", evList.getTofs()[0]
+
+ # Convert the tof units by scaling by a multiplier.
+ print "First tof before scaleTof:", evList.getTofs()[0]
+ factor = 1.5
+ evList.scaleTof(factor)
+ print "First tof after scaleTof:", evList.getTofs()[0]
+
+ # Multiply the weights in this event list by a scalar with an error.
+ print "First event weight before multiply:", evList.getWeights()[0], \
+ "+/-", math.sqrt(evList.getWeightErrors()[0])
+ factor = 10.0
+ error = 5.0
+ evList.multiply(factor,error)
+ print "First event weight after multiply:", evList.getWeights()[0], \
+ "+/-", math.sqrt(evList.getWeightErrors()[0])
+
+ # Divide the weights in this event list by a scalar with an error.
+ print "First event weight before divide:", evList.getWeights()[0], \
+ "+/-", math.sqrt(evList.getWeightErrors()[0])
+ factor = 1.5
+ error = 0.0
+ evList.divide(factor,error)
+ print "First event weight after divide:", evList.getWeights()[0], \
+ "+/-", math.sqrt(evList.getWeightErrors()[0])
+
+ # Mask out events that have a tof between tofMin and tofMax (inclusively)
+ print "Number of events before masking:", evList.getNumberEvents()
+ evList.maskTof(1000,5000)
+ print "Number of events after masking:", evList.getNumberEvents()
+
+.. testoutput:: ChangingEventLists
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ First pulse time before addPulsetime: 2010-01-01T00:32:55...
+ First pulse time after addPulsetime: 2010-01-01T00:36:15...
+ First tof before addTof: 118...
+ First tof after addTof: 121...
+ First tof before scaleTof: 121...
+ First tof after scaleTof: 181...
+ First event weight before multiply: 1.0... +/- 1.0...
+ First event weight after multiply: 10.0 +/- 3.34...
+ First event weight before divide: 10.0 +/- 3.34...
+ First event weight after divide: 6.6... +/- 2.73...
+ Number of events before masking: ...
+ Number of events after masking: ...
+
For Developers/Writing Algorithms
---------------------------------
@@ -42,7 +218,7 @@ The following information will be useful to you if you want to write an
algorithm that is EventWorkspace-aware.
Individual Neutron Event Data (TofEvent)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+########################################
The TofEvent class holds information for each neutron detection event
data:
@@ -54,7 +230,7 @@ data:
Note that this field can be converted to other units, e.g. d-spacing.
Lists of Events (EventList)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+###########################
- The EventList class consists of a list of TofEvent's. The order of
this list is not significant, since various algorithms will resort by
@@ -76,34 +252,34 @@ EventWorkpspace->makeSpectraMap to generate the spectra map (map between
spectrum # and detector IDs) by using the info in each EventList.
Most Recently Used List (MRUList)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#################################
An EventWorkspace contains a list of the 100 most-recently used
histograms, a MRUList. This MRU caches the last histogram
data generated for fastest display.
A note about workspace index / spectrum number / detector ID
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+############################################################
-The loading algorithms **match** the workspace index and spectrum number
+For event workspaces there is no benefit, and only a drawback to grouping detectors in hardware, therefore most of the loading algorithms for event data **match** the workspace index and spectrum number
in the EventWorkspace. Therefore, in an EventWorkspace, the two numbers
will be the same, and your workspace's Axis[1] is a simple 1:1 map. As
mentioned above, the detectorID is saved in EventList, but the
makeSpectraMap() method generates the usual SpectraDetectorMap object.
Workspace2D compatibility
-~~~~~~~~~~~~~~~~~~~~~~~~~
+#########################
EventWorkspace is designed to be able to be read (but not written to)
-like a :ref:`Workspace2D <Workspace2D>`. By default, if an algorithm
+like a :ref:`MatrixWorkspace <MatrixWorkspace>`. By default, if an algorithm
performs an operation and outputs a new workspace, the
-WorkspaceFactory will create a Workspace2D *copy*
+WorkspaceFactory will create a :ref:`Workspace2D` *copy*
of your EventWorkspace's histogram representation. If you attempt to
change an EventWorkspace's Y or E data in place, you will get an error
message, since that is not possible.
A Note about Thread Safety
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+##########################
Thread safety can be surprising when using an EventWorkspace:
diff --git a/docs/source/concepts/Instrument.rst b/docs/source/concepts/Instrument.rst
index 0180cdd274d0f3fb70424b59740d6f5e0977a88e..75b5c59bfcd47fbe46e916abdcc78a394587a20a 100644
--- a/docs/source/concepts/Instrument.rst
+++ b/docs/source/concepts/Instrument.rst
@@ -3,10 +3,13 @@
Instrument
==========
-What are they?
---------------
+.. contents::
+ :local:
-The Instrument is a geometrical description of the components that make
+What are Instruments?
+---------------------
+
+The Instrument in Mantid is a geometrical description of the components that make
up the beam line. The components described will generally include:
- The source
@@ -29,8 +32,7 @@ file <InstrumentDefinitionFile>`.
The Mantid geometry is further explained :ref:`here <Geometry>`.
-Why do we have a full instrument description, and not just a list of L2 and 2Theta values?
-------------------------------------------------------------------------------------------
+**Why do we have a full instrument description, and not just a list of L2 and 2Theta values?**
A list of L2 and 2Theta values will provide information to perform unit
conversions and several other algorithms, however a full geometric
@@ -42,6 +44,167 @@ instrument description allows much more.
- Updating the instrument geometry according to values stored in
log-files
+Working with Instruments in Python
+----------------------------------
+
+Getting the Instrument from a workspace
+#######################################
+
+You can get access to the Instrument for a workspace with
+
+.. testsetup:: WorkspaceInstrument
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: WorkspaceInstrument
+
+ instrument = ws.getInstrument()
+
+.. testoutput:: WorkspaceInstrument
+ :hide:
+
+
+Instrument Properties
+#####################
+
+.. testcode:: InstrumentPropertiestest
+
+ ws = CreateSampleWorkspace()
+ instrument = ws.getInstrument()
+
+ # get the instrument name
+ print instrument.getName()
+ # Get the validity dates for this instrument definition
+ print instrument.getValidToDate()
+ print instrument.getValidFromDate()
+ # Get the X,Y,Z position of the source and sample
+ source = instrument.getSource()
+ sample = instrument.getSample()
+ print source.getPos()
+ print sample.getPos()
+ # Get the distance from the source to the sample
+ print sample.getDistance(source)
+
+.. testoutput:: InstrumentPropertiestest
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ basic_rect
+ ...
+ 10.0
+
+Finding Specific Components of the instrument
+#############################################
+
+The instrument class has several methods to help in finding the objects that describe specific parts of the instrument.
+
+.. testcode:: InstrumentComponents
+
+ ws = CreateSampleWorkspace()
+ instrument = ws.getInstrument()
+
+ # Get the source and sample
+ source = instrument.getSource()
+ sample = instrument.getSample()
+
+ # You can get a component by name
+ bank1 = instrument.getComponentByName("bank1")
+ # Or by Detector_id
+ det101 = instrument.getDetector(101)
+
+.. testoutput:: InstrumentProperties
+ :hide:
+
+Instrument Parameters
+#####################
+
+Instruments, or any component within them (bank, detector, chopper, slit etc) can have parameters defined for them. These can be accessed from Python. Any search for instrument parameters cascades up the instrument tree, so a detector will inherit any parameters from it's back, and it's instrument.
+
+.. testcode:: InstrumentParameters
+
+ # setup
+ ws = CreateSampleWorkspace()
+ #set a string parameter on the whole instrument
+ SetInstrumentParameter(ws,ParameterName="TestParam",Value="Hello")
+
+ #set a Number parameter just for bank 1
+ SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3", ComponentName="bank1",ParameterType="Number")
+
+ #set a different value on bank 2
+ SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3.5", ComponentName="bank2",ParameterType="Number")
+
+
+ instrument=ws.getInstrument()
+ bank1=instrument.getComponentByName("bank1")
+ bank2=instrument.getComponentByName("bank2")
+
+ print ("The whole instrument parameter can be read from anywhere.")
+ print (" The instrument: " + instrument.getStringParameter("TestParam")[0])
+ print (" bank 1: " + bank1.getStringParameter("TestParam")[0])
+ print (" bank 2: " + bank2.getStringParameter("TestParam")[0])
+
+ print ("The parameters on the Bank 1 can be read from the bank or below.")
+ #For this one call getIntParameter as the number was an int
+ print (" bank 1: " + str(bank1.getIntParameter("NumberParam")[0]))
+ #For this one call getNumberParameter as the number was a float
+ print (" bank 2: " + str(bank2.getNumberParameter("NumberParam")[0]))
+ #if you are not sure of the type of a parameter you can call getParameterType
+ print (" The type of NumberParam in bank 1: " + bank1.getParameterType("NumberParam"))
+ print (" The type of NumberParam in bank 2: " + bank2.getParameterType("NumberParam"))
+
+Output:
+
+.. testoutput:: InstrumentParameters
+
+ The whole instrument parameter can be read from anywhere.
+ The instrument: Hello
+ bank 1: Hello
+ bank 2: Hello
+ The parameters on the Bank 1 can be read from the bank or below.
+ bank 1: 3
+ bank 2: 3.5
+ The type of NumberParam in bank 1: int
+ The type of NumberParam in bank 2: double
+
+
+
+Getting all the Parameters on an instrument component
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. testsetup:: InstrumentParametersList
+
+ # setup
+ ws = CreateSampleWorkspace()
+ #set a string parameter on the whole instrument
+ SetInstrumentParameter(ws,ParameterName="TestParam",Value="Hello")
+
+ #set a Number parameter just for bank 1
+ SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3", ComponentName="bank1",ParameterType="Number")
+
+ #set a different value on bank 2
+ SetInstrumentParameter(ws,ParameterName="NumberParam",Value="3.5", ComponentName="bank2",ParameterType="Number")
+
+.. testcode:: InstrumentParametersList
+
+ # setup as above
+ instrument=ws.getInstrument()
+ det101=instrument.getDetector(101)
+
+ for name in det101.getParameterNames() :
+ print name,
+ if det101.getParameterType(name) == "int":
+ print det101.getIntParameter(name)
+ if det101.getParameterType(name) == "double":
+ print det101.getNumberParameter(name)
+ if det101.getParameterType(name) == "string":
+ print det101.getStringParameter(name)
+
+
+Output:
+
+.. testoutput:: InstrumentParametersList
+ NumberParam [3]
+ TestParam ['Hello']
-.. categories:: Concepts
\ No newline at end of file
+.. categories:: Concepts
diff --git a/docs/source/concepts/MDHistoWorkspace.rst b/docs/source/concepts/MDHistoWorkspace.rst
index af2e92bd3ca3d6608ab213b244718959713c7c75..40d0e08c05c08e7122497e8434a13d0d36f0453e 100644
--- a/docs/source/concepts/MDHistoWorkspace.rst
+++ b/docs/source/concepts/MDHistoWorkspace.rst
@@ -1,8 +1,12 @@
.. _MDHistoWorkspace:
+======================
MD Histogram Workspace
======================
+.. contents::
+ :local:
+
The MD Histogram Workspace[MDHistoWorkspace] is a simple multi-dimensional workspace. In
contrast to the :ref:`MDWorkspace <MDWorkspace>`, which contains
points in space, the MDHistoWorkspace consists of a signal and error
@@ -45,8 +49,139 @@ Viewing a MDHistoWorkspace
Viewer <http://www.mantidproject.org/MantidPlot:_SliceViewer>`__, which shows 2D slices of the
multiple-dimension workspace.
+
+Working with MD Histo Workspaces in Python
+------------------------------------------
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to an MDHistoWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is an MDHistoWorkspace you can use this:
+
+.. testcode:: CheckMDHistoWorkspace
+
+ from mantid.api import IMDHistoWorkspace
+
+ ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+
+ if isinstance(ws, IMDHistoWorkspace):
+ print ws.getName() + " is a " + ws.id()
+
+Output:
+
+.. testoutput:: CheckMDHistoWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ ws is a MDHistoWorkspace
+
+
+MD Histo Workspace Properties
+#############################
+
+For a full list of the available properties and operation look at the :py:obj:`IMDHistoWorkspace api page <mantid.api.IMDHistoWorkspace>`.
+
+.. testcode:: MDHistoWorkspaceProperties
+
+ ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+
+ print "Number of events =", ws.getNEvents()
+ print "Number of dimensions =", ws.getNumDims()
+ print "Normalization =", ws.displayNormalization()
+ for i in range(ws.getNumDims()):
+ dimension = ws.getDimension(i)
+ print "\tDimension {0} Name: {1}".format(i,
+ dimension.getName())
+
+.. testoutput:: MDHistoWorkspaceProperties
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of events = 0
+ Number of dimensions = 2
+ Normalization = NoNormalization
+ Dimension 0 Name: Dim1
+ Dimension 1 Name: Dim2
+
+Dimensions
+^^^^^^^^^^
+
+As a generic multi dimensional container being able to access information about the dimensions is very important.
+
+.. testcode:: MDHistoWorkspaceDimensions
+
+ ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+
+ print "Number of dimensions =", ws.getNumDims()
+ for i in range(ws.getNumDims()):
+ dimension = ws.getDimension(i)
+ print "\tDimension {0} Name: {1} id: {2} Range: {3}-{4} {5}".format(i,
+ dimension.getDimensionId(),
+ dimension.getName(),
+ dimension.getMinimum(),
+ dimension.getMaximum(),
+ dimension.getUnits())
+
+ print "The dimension assigned to X =", ws.getXDimension().getName()
+ print "The dimension assigned to Y =", ws.getYDimension().getName()
+ try:
+ print "The dimension assigned to Z =", ws.getZDimension().getName()
+ except RuntimeError:
+ # if the dimension does not exist you will get a RuntimeError
+ print "Workspace does not have a Z dimension"
+
+ # you can also get a dimension by it's id
+ dim = ws.getDimensionIndexById("Dim1")
+ # or name
+ dim = ws.getDimensionIndexByName("Dim2")
+
+
+.. testoutput:: MDHistoWorkspaceDimensions
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of dimensions = 2
+ Dimension 0 Name: Dim1 id: Dim1 Range: -3.0-3.0 MomentumTransfer
+ Dimension 1 Name: Dim2 id: Dim2 Range: -10.0-10.0 EnergyTransfer
+ The dimension assigned to X = Dim1
+ The dimension assigned to Y = Dim2
+ The dimension assigned to Z = Workspace does not have a Z dimension
+
+Accessing the Data
+##################
+
+.. testcode:: MDWorkspaceData
+
+ ws=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+
+ # To get the signal and error at a prticular position
+ index = ws.getLinearIndex(5,5)
+ print ws.signalAt(index)
+ print ws.errorSquaredAt(index)
+
+ # To extract the whole signal aray
+ signalArray = ws.getSignalArray()
+ # or the whole error squared array
+ errorSquaredArray = ws.getErrorSquaredArray()
+
+.. testoutput:: MDWorkspaceData
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ 55.0
+ 3025.0
+
Arithmetic Operations
----------------------
+#####################
The following algorithms allow you to perform simple arithmetic on the
values:
@@ -62,29 +197,33 @@ The formulas used are described in each algorithm's wiki page.
The basic arithmetic operators are available from python. For example:
-| ``# Get two workspaces``
-| ``AÂ =Â mtd['workspaceA']``
-| ``BÂ =Â mtd['workspaceB']``
-| ``# Creating a new workspace``
-| ``CÂ =Â AÂ +Â B``
-| ``CÂ =Â AÂ -Â B``
-| ``CÂ =Â AÂ *Â B``
-| ``CÂ =Â AÂ /Â B``
-| ``# Modifying a workspace in-place``
-| ``CÂ +=Â A``
-| ``CÂ -=Â A``
-| ``CÂ *=Â A``
-| ``CÂ /=Â A``
-| ``# Operators with doubles``
-| ``CÂ =Â AÂ *Â 12.3``
-| ``CÂ *=Â 3.45``
-
-Compound arithmetic expressions can be made, e.g:
-
-``EÂ =Â (AÂ -Â B)Â /Â (CÂ -Â D)``
+.. testcode:: MDWorkspaceArithmetic
+
+ # Get two workspaces
+ A=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+ B = A.clone()
+
+ # Creating a new workspace
+ C = A + B
+ C = A - B
+ C = A * B
+ C = A / B
+ # Modifying a workspace in-place
+ C += A
+ C -= A
+ C *= A
+ C /= A
+ # Operators with doubles
+ C = A * 12.3
+ C *= 3.45
+
+ #Compound arithmetic expressions can be made, e.g:
+ E = (A - B) / (C * C)
Boolean Operations
-~~~~~~~~~~~~~~~~~~
+##################
The MDHistoWorkspace can be treated as a boolean workspace. In this
case, 0.0 is "false" and 1.0 is "true".
@@ -103,24 +242,31 @@ These boolean operators are available from python. Make sure you use the
bitwise operators: & \| ^ ~ , not the "word" operators (and, or, not).
For example:
-| ``# Create boolean workspaces by comparisons``
-| ``CÂ =Â AÂ >Â B``
-| ``DÂ =Â BÂ <Â 12.34``
-| ``# Combine boolean workspaces using not, or, and, xor:``
-| ``not_CÂ =Â ~C``
-| ``C_or_DÂ =Â CÂ |Â D``
-| ``C_and_DÂ =Â CÂ &Â D``
-| ``C_xor_DÂ =Â CÂ ^Â D``
-| ``CÂ |=Â D``
-| ``CÂ &=Â D``
-| ``CÂ ^=Â D``
-
-| ``# Compound expressions can be used:``
-| ``DÂ =Â (AÂ >Â 123)Â &Â (AÂ >Â B)Â &Â (AÂ <Â 456)``
+.. testcode:: MDWorkspaceBoolean
+
+ # Get two workspaces
+ A=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10', \
+ SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+ B = A.clone()
+
+ # Create boolean workspaces by comparisons
+ C = A > B
+ D = B < 12.34
+ # Combine boolean workspaces using not, or, and, xor:
+ not_C = ~C
+ C_or_D = C | D
+ C_and_D = C & D
+ C_xor_D = C ^ D
+ C |= D
+ C &= D
+ C ^= D
+ # Compound expressions can be used:
+ D = (A > 123) & (A > B) & (A < 456)
Using Boolean Masks
-^^^^^^^^^^^^^^^^^^^
-
+###################
+
The :ref:`SetMDUsingMask <algm-SetMDUsingMask>` algorithm allows you to modify
the values in a MDHistoWorkspace using a mask created using the boolean
operations above. See the `algorithm wiki page <algm-SetMDUsingMask>`__ for
@@ -128,4 +274,4 @@ more details.
-.. categories:: Concepts
\ No newline at end of file
+.. categories:: Concepts
diff --git a/docs/source/concepts/MDWorkspace.rst b/docs/source/concepts/MDWorkspace.rst
index 1319e4009e67062c24557cfbbb8af78eb345a444..5de154941d78215cc4dfd2b69545e99afa156abc 100644
--- a/docs/source/concepts/MDWorkspace.rst
+++ b/docs/source/concepts/MDWorkspace.rst
@@ -1,8 +1,12 @@
.. _MDWorkspace:
+============
MD Workspace
============
+.. contents::
+ :local:
+
The MD Workspace [MDWorkspace] (short for "Multi-Dimensional" Workspace) is a generic
data structure holdings points (MDEvents) that are defined by their
position in several dimensions. See also
@@ -59,6 +63,7 @@ There are several algorithms that will create a MDWorkspace:
- :ref:`CreateMDWorkspace <algm-CreateMDWorkspace>` creates a blank MDWorkspace
with any arbitrary set of dimensions.
+- :ref:`CreateMD <algm-CreateMD>` Creates an MDWorkspace in the Q3D, HKL frame.
- :ref:`ConvertToDiffractionMDWorkspace <algm-ConvertToDiffractionMDWorkspace>`
converts an :ref:`EventWorkspace <EventWorkspace>` or
:ref:`Workspace2D <Workspace2D>` from detector space to reciprocal
@@ -104,4 +109,139 @@ the proper plugin is installed.
+Working with Table Workspaces in Python
+---------------------------------------
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to an MDWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is an MDWorkspace Workspace you can use this:
+
+.. testcode:: CheckMDWorkspace
+
+ from mantid.api import IMDEventWorkspace
+
+ mdws = CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U')
+
+ if isinstance(mdws, IMDEventWorkspace):
+ print mdws.getName() + " is a " + mdws.id()
+
+Output:
+
+.. testoutput:: CheckMDWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ mdws is a MDEventWorkspace<MDLeanEvent,3>
+
+
+MD Workspace Properties
+#######################
+
+For a full list of the available properties and operation look at the :py:obj:`IMDEventWorkspace api page <mantid.api.IMDEventWorkspace>`.
+
+.. testcode:: MDWorkspaceProperties
+
+ ws = CreateMDWorkspace(Dimensions='2', EventType='MDEvent', Extents='-10,10,-10,10',
+ Names='Q_lab_x,Q_lab_y', Units='A,B')
+ FakeMDEventData(ws, UniformParams="1000000")
+
+ print "Number of events =", ws.getNEvents()
+ print "Number of dimensions =", ws.getNumDims()
+ print "Normalization =", ws.displayNormalization()
+ for i in range(ws.getNumDims()):
+ dimension = ws.getDimension(i)
+ print "\tDimension {0} Name: {1}".format(i,
+ dimension.getName())
+
+ bc =ws.getBoxController()
+ print "Is the workspace using a file back end?", bc.isFileBacked()
+ backEndFilename = bc.getFilename()
+
+.. testoutput:: MDWorkspaceProperties
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of events = 1000000
+ Number of dimensions = 2
+ Normalization = VolumeNormalization
+ Dimension 0 Name: Q_lab_x
+ Dimension 1 Name: Q_lab_y
+ Is the workspace using a file back end? False
+
+Dimensions
+^^^^^^^^^^
+
+As a generic multi dimensional container being able to access information about the dimensions is very important.
+
+.. testcode:: MDWorkspaceDimensions
+
+ ws = CreateMDWorkspace(Dimensions='3', EventType='MDEvent', Extents='-10,10,-5,5,-1,1',
+ Names='Q_lab_x,Q_lab_y,Q_lab_z', Units='1\A,1\A,1\A')
+ FakeMDEventData(ws, UniformParams="1000000")
+
+ print "Number of dimensions =", ws.getNumDims()
+ for i in range(ws.getNumDims()):
+ dimension = ws.getDimension(i)
+ print "\tDimension {0} Name: {1} id: {2} Range: {3}-{4} {5}".format(i,
+ dimension.getDimensionId(),
+ dimension.getName(),
+ dimension.getMinimum(),
+ dimension.getMaximum(),
+ dimension.getUnits())
+
+ print "The dimension assigned to X =", ws.getXDimension().getName()
+ print "The dimension assigned to Y =", ws.getYDimension().getName()
+ try:
+ print "The dimension assigned to Z =", ws.getZDimension().getName()
+ except RuntimeError:
+ # if the dimension does not exist you will get a RuntimeError
+ print "Workspace does not have a Z dimension"
+
+ # you can also get a dimension by it's id
+ dim = ws.getDimensionIndexById("Q_lab_x")
+ # or name
+ dim = ws.getDimensionIndexByName("Q_lab_x")
+
+
+.. testoutput:: MDWorkspaceDimensions
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Number of dimensions = 3
+ Dimension 0 Name: Q_lab_x id: Q_lab_x Range: -10.0-10.0 1\A
+ Dimension 1 Name: Q_lab_y id: Q_lab_y Range: -5.0-5.0 1\A
+ Dimension 2 Name: Q_lab_z id: Q_lab_z Range: -1.0-1.0 1\A
+ The dimension assigned to X = Q_lab_x
+ The dimension assigned to Y = Q_lab_y
+ The dimension assigned to Z = Q_lab_z
+
+Accessing the Data
+^^^^^^^^^^^^^^^^^^
+
+To access the data of an MDWorkspace you need to convert it to a regular grid, or :ref:`MDHistoWorkspace`.
+
+
+.. testcode:: MDWorkspaceConvertToHisto
+
+ # Setup
+ mdWS = CreateMDWorkspace(Dimensions=4, Extents=[-1,1,-1,1,-1,1,-10,10], Names="H,K,L,E", Units="U,U,U,V")
+ FakeMDEventData(InputWorkspace=mdWS, PeakParams='500000,0,0,0,0,3')
+
+ # Create a histogrammed (binned) workspace with 100 bins in each of the H, K and L dimensions
+ histoWS = BinMD(InputWorkspace=mdWS, AlignedDim0='H,-1,1,100', AlignedDim1='K,-1,1,100', AlignedDim2='L,-1,1,100')
+
+ # Or you can also use CutMD, to define bin widths and the cut projection
+ from mantid.api import Projection
+ SetUB(Workspace=mdWS, a=1, b=1, c=1, alpha=90, beta=90, gamma=90)
+ SetSpecialCoordinates(InputWorkspace=mdWS, SpecialCoordinates='HKL')
+
+ projection = Projection([1,1,0], [-1,1,0])
+ proj_ws = projection.createWorkspace()
+
+ # Apply the cut with bin widths of 0.1 in H,K and L and integrating over -5 to +5 in E
+ out_md = CutMD(mdWS, Projection=proj_ws, PBins=([0.1], [0.1], [0.1], [-5,5]), NoPix=True)
+
+
.. categories:: Concepts
\ No newline at end of file
diff --git a/docs/source/concepts/MatrixWorkspace.rst b/docs/source/concepts/MatrixWorkspace.rst
index f885f4d67a0f20d0425e4ff794d1da29b5979992..563094d77749404cc2e8d35ab4c76ec162d0f826 100644
--- a/docs/source/concepts/MatrixWorkspace.rst
+++ b/docs/source/concepts/MatrixWorkspace.rst
@@ -1,35 +1,412 @@
.. _MatrixWorkspace:
+
+================
Matrix Workspace
================
+.. contents::
+ :local:
+
+A MatrixWorkspace is a generic name for any workspace that can be access like a table of X, Y and E values. This is the prime interface for accessing workspace data in Mantid. This covers several workspace types including:
+
+- :ref:`Workspace2D <Workspace2D>` - A workspace for holding two dimensional data in memory, this is the most commonly used workspace.
+- :ref:`EventWorkspace <EventWorkspace>` - A workspace that retains the individual neutron event data.
+
What information is in a MatrixWorkspace
----------------------------------------
-Mandatory:
+All Matrix Workspaces contain:
-- Measured or derived data with associated errors
+- Measured or derived data with associated errors, this is referenced as a 2D array of counts and error data. The axes are commonly "SpectraNumber" and another unit of measure, but are very flexible.
-Optionally:
+Also they may contain:
-- `Axes <http://www.mantidproject.org/Interacting_with_Workspaces#Axes>`__ with
+- Axes with
:ref:`Units <Unit Factory>`
-- Sample and sample environment data
-- Run logs
+- :ref:`Sample` and sample environment data
+- :ref:`Run` logs
- A full :ref:`instrument <instrument>` geometric definition, along with
an instrument parameter map
-- A spectra - detector map
+- A spectra - detector mapping
- A distribution flag
- A list of 'masked' bins
-Documentation on the :ref:`CreateWorkspace <algm-CreateWorkspace>`
-algorithm may also be useful.
+Working with Matrix Workspaces in Python
+----------------------------------------
+
+MatrixWorkspace is an abstract description of an specific workspace implementation. It provides access to a common way of accessing the data for a 2D workspace without needing to know the details of how that data is actually stored.
+
+Matrix Workspaces have all the data and operations of the base :ref:`Workspace <Workspace>` class, but add operations to access the data in a useful way.
+
+You can look at the :ref:`Matrix Workspace API reference <mantid.api.MatrixWorkspace>` for a full list of properties and operations, but here are some of the key ones.
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to a MatrixWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is a Matrix Workspace you can use this:
+
+.. testcode:: CheckMatrixWorkspace
+
+ from mantid.api import MatrixWorkspace
+
+ histoWS = CreateSampleWorkspace(WorkspaceType="Histogram")
+
+ if isinstance(histoWS, MatrixWorkspace):
+ print histoWS.getName() + " is a " + histoWS.id() + \
+ " and can be treated as a MatrixWorkspace"
+
+ print "\nFor more workspace types"
+ eventWS = CreateSampleWorkspace(WorkspaceType="Event")
+ svWS = CreateSingleValuedWorkspace()
+ tableWS = CreateEmptyTableWorkspace()
+ groupWS = GroupWorkspaces("histoWS,eventWS")
+ mdWS = CreateMDWorkspace(Dimensions=3, Extents='-10,10,-10,10,-10,10', Names='A,B,C', Units='U,U,U')
+ mdHistoWS=CreateMDHistoWorkspace(Dimensionality=2,Extents='-3,3,-10,10',SignalInput=range(0,100),ErrorInput=range(0,100),\
+ NumberOfBins='10,10',Names='Dim1,Dim2',Units='MomentumTransfer,EnergyTransfer')
+
+ myWorkspaceList = [histoWS,eventWS,svWS,tableWS,mdWS,mdHistoWS]
+ print "MatrixWorkspace?","Type"
+ for ws in myWorkspaceList:
+ print " ", isinstance(ws, MatrixWorkspace), "\t ", ws.id()
+
+
+Output:
+
+.. testoutput:: CheckMatrixWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ histoWS is a Workspace2D and can be treated as a MatrixWorkspace
+
+ For more workspace types
+ MatrixWorkspace? Type
+ True Workspace2D
+ True EventWorkspace
+ True WorkspaceSingleValue
+ False TableWorkspace
+ False MDEventWorkspace<MDLeanEvent,3>
+ False MDHistoWorkspace
+
+Matrix Workspace Properties
+###########################
+
+.. testsetup:: MatrixWorkspaceProperties
+
+ ws = Load("MAR11015")
+
+.. testcode:: MatrixWorkspaceProperties
+
+ # find out the number of histograms on a workspace use getNumberHistograms()
+ print "number of histograms = {0}".format(ws.getNumberHistograms())
+
+ # To find out the number of bins use blocksize()
+ print "number of bins = {0}".format(ws.blocksize())
+ # To find out the bin containing a value use binIndexOf()
+ print "bin index containing 502.2 for a histogram (0 by default) = {0}".format(ws.binIndexOf(502.2))
+ print "bin index containing 997.1 for histogram 272 = {0}".format(ws.binIndexOf(997.1,272))
+
+ # To find a workspace index from a spectrum number
+ print "workspace index for histogram 272 = {0}".format(ws.getIndexFromSpectrumNumber(272))
+ # To get the Run Number use getRunNumber()
+ print "run number = {0}".format(ws.getRunNumber())
+
+Output:
+
+.. testoutput:: MatrixWorkspaceProperties
+
+ number of histograms = 922
+ number of bins = 2663
+ bin index containing 502.2 for a histogram (0 by default) = 19
+ bin index containing 997.1 for histogram 272 = 39
+ workspace index for histogram 272 = 271
+ run number = 11015
+
+Instrument
+^^^^^^^^^^
+
+You can get access to the :ref:`Instrument` for a workspace with
+
+.. testsetup:: MatrixWorkspaceInstrument
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: MatrixWorkspaceInstrument
+
+ instrument = ws.getInstrument()
+
+For the properties and operations of the instrument look at the :ref:`Instrument help <Instrument>`.
+
+Run - to access logs, and other run information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can get access to the :ref:`Run` for a workspace with
+
+.. testsetup:: MatrixWorkspaceRun
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: MatrixWorkspaceRun
+
+ run = ws.getRun()
+
+For the properties and operations of the run object and how to access log data look at the :ref:`Run help <Run>`.
+
+Axes
+^^^^
+
+Axes are used primarily for labeling plots, but are also used as validation criteria for several algorithms.
+You can list out the axes of a workspace using the following code.
+
+.. testcode:: MatrixWorkspaceAxes
+
+ ws = CreateSampleWorkspace()
+ for i in range(ws.axes()):
+ axis = ws.getAxis(i)
+ print "Axis {0} is a {1}{2}{3}".format(i,
+ "Spectrum Axis" if axis.isSpectra() else "",
+ "Text Axis" if axis.isText() else "",
+ "Numeric Axis" if axis.isNumeric() else "")
+
+ unit = axis.getUnit()
+ print "\t caption:{0}".format(unit.caption())
+ print "\t symbol:{0}".format(unit.symbol())
+
+Output:
+
+.. testoutput:: MatrixWorkspaceAxes
+ :options: +NORMALIZE_WHITESPACE
+
+ Axis 0 is a Numeric Axis
+ caption:Time-of-flight
+ symbol:microsecond
+ Axis 1 is a Spectrum Axis
+ caption:Spectrum
+ symbol:
+
+
+
+**Setting the axisLabel**
+
+
+.. testcode:: MatrixWorkspaceAxesLabel
+
+ ws = CreateSampleWorkspace()
+ axis = ws.getAxis(1)
+ # Create a new axis
+ axis.setUnit("Label").setLabel('Temperature', 'K')
+
+ unit = axis.getUnit()
+ print "New caption:{0}".format(unit.caption())
+ print "New symbol:{0}".format(unit.symbol())
+
+Output:
+
+.. testoutput:: MatrixWorkspaceAxesLabel
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ New caption:Temperature
+ New symbol:K
-.. include:: WorkspaceNavigation.txt
-
-More information on working with them: `Interacting with Matrix
-Workspaces <http://www.mantidproject.org/Interacting_with_Workspaces>`__.
+**Replacing the Axis**
+
+.. testsetup:: MatrixWorkspaceAxesReplace
+
+ ws = Load("MAR11015")
+
+.. testcode:: MatrixWorkspaceAxesReplace
+
+ from mantid.api import NumericAxis
+
+ axis = ws.getAxis(1)
+ unit = axis.getUnit()
+ print "Old caption:{0}".format(unit.caption())
+ print "Old symbol:{0}".format(unit.symbol())
+
+ # Create a new axis
+ newAxis = NumericAxis.create(ws.getNumberHistograms())
+ newAxis.setUnit("Label").setLabel('Temperature', 'K')
+
+ # Set the vertical axis values
+ for idx in range(0, ws.getNumberHistograms()):
+ tempValue = idx*3+25 # some made up value
+ newAxis.setValue(idx, tempValue)
+
+ # Replace axis 1 with the new axis
+ ws.replaceAxis(1, newAxis)
+
+ axis = ws.getAxis(1)
+ unit = axis.getUnit()
+ print "New caption:{0}".format(unit.caption())
+ print "New symbol:{0}".format(unit.symbol())
+ print "New values: {0}".format(axis.extractValues())
+
+Output:
+
+.. testoutput:: MatrixWorkspaceAxesReplace
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Old caption:Spectrum
+ Old symbol:
+ New caption:Temperature
+ New symbol:K
+ New values: [ 25. 28. ... 2785. 2788.]
+
+
+
+**Setting the Y Label**
+
+.. figure:: ../images/PlotMatrixWorkspaceYUnitElephants.png
+ :alt: PlotMatrixWorkspaceYUnitElephants.png
+ :align: right
+
+.. testsetup:: MatrixWorkspaceYUnit
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: MatrixWorkspaceYUnit
+
+ print ws.YUnitLabel()
+ ws.setYUnitLabel("Elephants")
+ print ws.YUnitLabel()
+
+Output:
+
+.. testoutput:: MatrixWorkspaceYUnit
+
+ Counts
+ Elephants
+
+Matrix Workspace Operations
+###########################
+
+
+.. testsetup:: MatrixWorkspaceOperations
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: MatrixWorkspaceOperations
+
+ # To create a copy of a workspace
+ wsClone = ws.clone()
+ # or
+ wsClone = CloneWorkspace(ws)
+
+ # To check if two variables point to the same workspace
+ if ws == wsClone:
+ print "They are the same workspace"
+
+ # To check if two workspaces have equal values
+ if ws.equals(wsClone, tolerance = 0.05):
+ print "They have the same data"
+
+ # To create a copy of a workspace
+ wsWavelength = ws.convertUnits(Target="Wavelength")
+ # or
+ wsWavelength = ConvertUnits(ws,Target="Wavelength")
+
+ # To rebin the workspace
+ ws = ws.rebin(Params = 200)
+ # or
+ ws = Rebin(ws, Params = 200)
+
+ # Mask detectors or spectra (or use the MaskDetectors algorithm
+ ws.maskDetectors(SpectraList=[2,3,4])
+ ws.maskDetectors(WorkspaceIndexList=range(101,105))
+ ws.maskDetectors(DetectorList=[150,160,170])
+
+ # To delete the workspace
+ ws.delete()
+ # or
+ DeleteWorkspace(wsClone)
+ # Do not access the python variable again as you will get a RuntimeError
+ # e.g. RuntimeError: Variable invalidated, data has been deleted.
+
+.. testoutput:: MatrixWorkspaceOperations
+ :hide:
+
+ They have the same data
+
+Accessing Data
+##############
+
+A MatrixWorkspace is essentially a 2D list of binned data where a workspace index, starting at 0, gives access to the data fields in each spectra.
+
+
+The data is accessed using the ``readX()``, ``readY()`` and ``readE()`` commands. Each of these commands takes a number that refers to the index on the workspace and returns a list of the data for that workspace index, i.e
+
+.. testsetup:: MatrixWorkspaceData
+
+ ws = Load("MAR11015")
+
+.. testcode:: MatrixWorkspaceData
+
+ # Get the Y vector for the second row of data
+ y_data2 = ws.readY(1)
+ for y in y_data2:
+ print y
+
+ # Or in loop access. Print the first value in all spectra
+ for index in range(0, ws.getNumberHistograms()):
+ #Note the round brackets followed by the square brackets
+ print ws.readY(index)[0]
+
+.. testoutput:: MatrixWorkspaceData
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ 24571.0
+ 13761.0
+ ...
+ 62.0
+ 95.0
+
+There are more examples how to `Extract and manipulate workspace data here <http://www.mantidproject.org/Extracting_And_Manipulating_Data>`_.
+
+Workspace algebra
+#################
+
+MatrixWorkspaces can have algebraic operations applied to them directly without the need to call a specific algorithm, e.g. :ref:`algm-Plus <Plus>`
+
+
+The expected operations of +,-,*,/ are supported with either a single number or another workspace as the second argument, e.g.
+
+.. testsetup:: MatrixWorkspaceAlgebra
+
+ workspace1 = Load("MAR11015")
+ workspace2 = CloneWorkspace(workspace1)
+
+.. testcode:: MatrixWorkspaceAlgebra
+
+ w1 = mtd['workspace1']
+ w2 = mtd['workspace2']
+
+ # Sum the two workspaces and place the output into a third
+ w3 = w1 + w2
+
+ # Multiply the new workspace by 2 and place the output into a new workspace
+ w4 = w3 * 2
+
+It is also possible to replace one of the input workspaces using one of +=,-=,*=,/= e.g.
+
+.. testsetup:: MatrixWorkspaceAlgebra2
+
+ w1= Load("MAR11015")
+ w2= CloneWorkspace(w1)
+
+.. testcode:: MatrixWorkspaceAlgebra2
+
+ # Multiply a workspace by 2 and replace w1 with the output
+ w1 *= 2.0
+
+ # Add 'workspace2' to 'workspace1' and replace 'workspace1' with the output
+ w1 += w2
+
+
+.. include:: WorkspaceNavigation.txt
+
-.. categories:: Concepts
\ No newline at end of file
+.. categories:: Concepts
diff --git a/docs/source/concepts/PropertiesFile.rst b/docs/source/concepts/PropertiesFile.rst
index 7a3d332535971cf791d651cc4efa9de41f5440ec..41e0caf18671dffc0579bcdf180063be2adc5803 100644
--- a/docs/source/concepts/PropertiesFile.rst
+++ b/docs/source/concepts/PropertiesFile.rst
@@ -119,7 +119,7 @@ to alter and those properties are detailed below.
| |will apply. | |
+-------------------------------------------+---------------------------------------------------+-----------------------+
|logging.channels.consoleFilterChannel.level|The lowest level messages to output to the console.|debug, information, |
-| | The default is warning, but this can be |notice, warning, |
+| |The default is warning, but this can be |notice, warning, |
| |lowered to debug for more detailed feedback. The |error, critical |
| |higher level of this and logging.loggers.root.level|or fatal |
| |will apply. | |
diff --git a/docs/source/concepts/Run.rst b/docs/source/concepts/Run.rst
index 0241d53047a51ef59f77432236db01cf6197f76b..312e7a98f2a5a2269c1004d374229c86f5a5dec7 100644
--- a/docs/source/concepts/Run.rst
+++ b/docs/source/concepts/Run.rst
@@ -1,11 +1,16 @@
.. _Run:
+===
Run
===
-What is it?
------------
+.. contents::
+ :local:
+
+What the Run object
+-------------------
+
A Run holds data related to the properties of the experimental run, e.g.
good proton charge, total frames etc. It also holds all of the sample
log files as sets of time-series data. Currently used properties within
@@ -15,6 +20,132 @@ collected. Where an instrument has been modified over time, and multiple
defined for it, this property is used to loads the IDF valid when the
data were collected.
+
+Working with Run object in Python
+---------------------------------
+
+You can look at the :ref:`Run API reference <mantid.api.Run>` for a full list of properties and operations, but here are some of the key ones.
+
+Getting the Run Object from a Workspace
+#######################################
+
+.. testsetup:: WorkspaceRun
+
+ ws = CreateSampleWorkspace()
+
+.. testcode:: WorkspaceRun
+
+ run = ws.getRun()
+
+Run Properties
+##############
+
+.. testsetup:: RunPropertiestest
+
+ ws = Load("MAR11060")
+
+.. testcode:: RunPropertiestest
+
+ from mantid.kernel import DateAndTime
+ run = ws.getRun()
+
+ # Set the start and end time of a run
+ run.setStartAndEndTime(DateAndTime("2015-01-27T11:00:00"),
+ DateAndTime("2015-01-27T11:57:51"))
+
+ # Get the start and end time of a run
+ print run.startTime()
+ print run.endTime()
+
+ # Get the total good proton charge
+ print run.getProtonCharge()
+
+.. testoutput:: RunPropertiestest
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ 2015-01-27T11:00:00
+ 2015-01-27T11:57:51
+ 121...
+
+Accessing Properties
+####################
+
+Listing all properties
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. testcode:: RunListPropertiestest
+
+ ws = Load("MAR11060")
+
+ run = ws.getRun()
+
+ # Get a list of the property names
+ print run.keys()
+
+ # Loop over all of the Properties
+ for prop in run.getProperties():
+ print prop.name, prop.value
+
+.. testoutput:: RunListPropertiestest
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ ['run_header', ... 'run_title']
+ run_header MAR 11060 Vanadium white beam 23-JUN-2005 10:18:46 121.5
+ ...
+ run_title Vanadium white beam jaws=50x50 nim=50 dsc=0
+
+Getting a specific property
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. testcode:: RunGetPropertytest
+
+ ws = CreateSampleWorkspace()
+
+ run = ws.getRun()
+
+ # Check a propetry exists
+ print "Is runstart present: {0}".format(("run_start" in run.keys()))
+ # or
+ print "Is runstart present: {0}".format(run.hasProperty("run_start"))
+
+ #get the Property
+ runStart = run.getProperty("run_start")
+ print "Property name: " + runStart.name
+ print "Property value: " + runStart.value
+
+.. testoutput:: RunGetPropertytest
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Is runstart present: True
+ Is runstart present: True
+ Property name: run_start
+ Property value: 2010-01-01T00:00:00
+
+The Gonioneter
+##############
+
+If the instrument conatains a Goniometer it can be accessed from the run object.
+
+.. testcode:: GetGoniometertest
+
+ wg=CreateSingleValuedWorkspace()
+ AddSampleLog(wg,"Motor1","45.","Number")
+ SetGoniometer(wg,Axis0="Motor1,0,1,0,1",Axis1="5,0,1,0,1")
+
+ print "Goniometer angles: ",wg.getRun().getGoniometer().getEulerAngles('YZY')
+
+.. testoutput:: GetGoniometertest
+ :hide:
+ :options: +NORMALIZE_WHITESPACE
+
+ Goniometer angles: [50,0,0]
+
+Listing all properties
+^^^^^^^^^^^^^^^^^^^^^^
+
What information is stored here?
--------------------------------
@@ -22,7 +153,7 @@ On loading experimental data there is a default set of properties that
are populated within the run. These are as follows:
ISIS (not including ISIS Muon data)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+###################################
- **run\_header** - The complete header for this run
- **run\_title** - The run title
@@ -51,7 +182,7 @@ ISIS (not including ISIS Muon data)
- **rb\_proposal** - The proposal number
ISIS Muon data
-^^^^^^^^^^^^^^
+##############
- **run\_title** - The run title
- **run\_start** - Start date and time. Format: YYYY-MM-DD HH:MM:SS (+)
diff --git a/docs/source/concepts/Sample.rst b/docs/source/concepts/Sample.rst
new file mode 100644
index 0000000000000000000000000000000000000000..e3535d31c575bb9c28ee7e5b846285ed5fd21fc8
--- /dev/null
+++ b/docs/source/concepts/Sample.rst
@@ -0,0 +1,90 @@
+.. _Sample:
+
+======
+Sample
+======
+
+
+.. contents::
+ :local:
+
+What the Sample object
+----------------------
+
+The sample object holds details of the samples in an experiment. While most of the time this will refer to a single sample, it can describe a collection of samples. Specifically this holds information about a samples.
+
+* Material properties and chenmical copmosition
+* Shape and dimensions
+* Crystal Structure
+
+Working with Sample object in Python
+------------------------------------
+
+You can look at the :ref:`Sample API reference <mantid.api.Sample>` for a full list of properties and operations, but here are some of the key ones.
+
+Getting the Sample Object from a Workspace
+##########################################
+
+.. testcode:: WorkspaceSample
+
+ ws=CreateWorkspace(DataX='1,2',DataY='1')
+ s=ws.sample()
+
+
+Sample Properties
+#################
+
+.. testcode:: SamplePropertiestest
+
+ ws = CreateSampleWorkspace("Histogram",NumBanks=1,BankPixelWidth=1)
+ s = ws.sample()
+
+ # Dimensions
+ s.setHeight(0.1)
+ s.setWidth(0.2)
+ s.setThickness(0.3)
+ print "Height:", s.getHeight()
+ print "Width:", s.getWidth()
+ print "Thickness:", s.getThickness()
+
+ # Material
+ SetSampleMaterial(ws,ChemicalFormula="V")
+ m = s.getMaterial()
+ print "Material Name", m.name()
+ print "Total scattering X-Section:", m.totalScatterXSection()
+
+ # Crystal Structure
+ SetUB(ws,a=2,b=3,c=4,alpha=90,beta=90,gamma=90,u="1,0,0",v="0,0,1")
+ ol=s.getOrientedLattice()
+ print "Data lattice parameters are:",ol.a(),ol.b(),ol.c(),ol.alpha(),ol.beta(),ol.gamma()
+
+.. testoutput:: SamplePropertiestest
+ :hide:
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ Height: 0.1
+ Width: 0.2
+ Thickness: 0.3
+ Material Name V
+ Total scattering X-Section: 5.1
+ Data lattice parameters are: 2.0 3.0 4.0 90.0 90.0 90.0
+
+
+Multiple Samples
+################
+
+The ``Sample()`` method actually returns a collection, however if you do not specify which sample you are after you will get he first member of the collection. So
+
+.. testcode:: MultiSample
+
+ ws = CreateSampleWorkspace("Histogram",NumBanks=1,BankPixelWidth=1)
+
+ s = ws.sample()
+ # Is the same as
+ s = ws.sample()[0]
+
+ # You can ask how many samples there are with
+ size = ws.sample().size()
+
+
+.. categories:: Concepts
\ No newline at end of file
diff --git a/docs/source/concepts/TableWorkspaces.rst b/docs/source/concepts/TableWorkspaces.rst
index bbc8852477d41300270dddac91e4ffb676a25d47..9977eed966f37dc6147b056964f3a1ee03165edf 100644
--- a/docs/source/concepts/TableWorkspaces.rst
+++ b/docs/source/concepts/TableWorkspaces.rst
@@ -1,19 +1,135 @@
.. _Table Workspaces:
+================
Table Workspaces
================
-- This page focusses on dealing with Table Workspaces in C++, and is
- aimed at developers. For details on interacting with Table Workspaces
- in Python, please see :py:obj:`this page <mantid.api.ITableWorkspace>`.
+.. contents::
+ :local:
Overview
--------
Table workspaces are general purpose workspaces for storing data of
mixed types. A table workspace is organized in columns. Each column has
-a name and a type - the type of the data in that column. Table wokspaces
-can be created using the workspace factory:
+a name and a type - the type of the data in that column.
+
+
+Working with Table Workspaces in Python
+---------------------------------------
+
+For more details on interacting with Table Workspaces in Python, please see :py:obj:`this page <mantid.api.ITableWorkspace>`.
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to an Table Workspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is an Table Workspace you can use this:
+
+.. testcode:: CheckTableWorkspace
+
+ from mantid.api import ITableWorkspace
+
+ tableWS = CreateEmptyTableWorkspace()
+
+ if tableWS is ITableWorkspace:
+ print tableWS.getName() + " is a " + tableWS.id()
+
+Output:
+
+.. testoutput:: CheckEventWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ tableWS is a TableWorkspace
+
+Creating a Table Workspace in Python
+####################################
+
+Most of the time Table workspaces are the output of certain algorithms, but you can create them yourself should you wish.
+
+.. testcode:: CreateTableWorkspace
+
+ from mantid.kernel import V3D
+
+ # Create PositionTable
+ tableWS = CreateEmptyTableWorkspace()
+
+ # Add some columns, Recognized types are: int,float,double,bool,str,V3D,long64
+ tableWS.addColumn(type="int",name="Detector ID")
+ tableWS.addColumn(type="str",name="Detector Name")
+ tableWS.addColumn(type="V3D",name="Detector Position")
+
+ # Populate the columns for three detectors
+ detIDList = range(1,4)
+ detPosList = [ V3D(9.0,0.0,0.0), V3D(10.0,3.0,0.0), V3D(12.0,3.0,6.0)]
+ for j in range(len(detIDList)):
+ nextRow = { 'Detector ID': detIDList[j],
+ 'Detector Name': "Detector {0}".format(detIDList[j]),
+ 'Detector Position': detPosList[j] }
+ tableWS.addRow ( nextRow )
+
+Table Workspace Properties
+##########################
+
+.. testsetup:: TableWorspaceProperties
+
+ from mantid.kernel import V3D
+
+ # Create PositionTable
+ tableWS = CreateEmptyTableWorkspace()
+
+ # Add some columns
+ tableWS.addColumn(type="int",name="Detector ID")
+ tableWS.addColumn(type="str",name="Detector Name")
+ tableWS.addColumn(type="V3D",name="Detector Position")
+
+ # Populate the columns for three detectors
+ detIDList = range(1,4)
+ detPosList = [ V3D(9.0,0.0,0.0), V3D(10.0,3.0,0.0), V3D(12.0,3.0,6.0)]
+ for j in range(len(detIDList)):
+ nextRow = { 'Detector ID': detIDList[j],
+ 'Detector Name': "Detector {0}".format(detIDList[j]),
+ 'Detector Position': detPosList[j] }
+ tableWS.addRow ( nextRow )
+
+.. testcode:: TableWorspaceProperties
+
+ #setup as above
+
+ # Rows
+ print "Row count:", tableWS.rowCount()
+ print tableWS.row(0) # row values as a dictionary
+ # Resize the table
+ tableWS.setRowCount(4)
+ # Add Rows
+ tableWS.addRow( [2, "new Detector 1", V3D(2,2,2)])
+ # or using a dictionary
+ nextRow = { 'Detector ID': 5,
+ 'Detector Name': "new Detector 2",
+ 'Detector Position': V3D(5,5,5) }
+ tableWS.addRow ( nextRow )
+
+ # Columns
+ print "Column count:", tableWS.columnCount()
+ print "Column names:", tableWS.getColumnNames()
+ columnValuesList = tableWS.column(0)
+ # To remove a column
+ tableWS.removeColumn("Detector Name")
+
+.. testoutput:: TableWorspaceProperties
+ :hide:
+ :options: +NORMALIZE_WHITESPACE
+
+ Row count: 3
+ {'Detector Position': [9,0,0], 'Detector Name': 'Detector 1', 'Detector ID': 1}
+ Column count: 3
+ Column names: ['Detector ID', 'Detector Name', 'Detector Position']
+
+Working with Table Workspaces in C++
+------------------------------------
+
+Table workspaces can be created using the workspace factory:
``ITableWorkspace_sptr table = WorkspaceFactory::Instance().createTable("TableWorkspace");``
@@ -48,7 +164,7 @@ the second argument is the name of the column. The predefined types are:
The data in the table can be accessed in a number of ways. The most
simple way is to call templated method T& cell(row,col), where col is
the index of the column in the workspace and row is the index of the
-cell in the comlumn. Colunms are indexed in the order they are created
+cell in the column. Columns are indexed in the order they are created
with addColumn. There are also specialized methods for four predefined
data types: int& Int(row,col), double& Double(row,col), std::string&
String(row,col), bool& Bool(row,col). Columns use std::vector to store
@@ -58,10 +174,10 @@ column object use getColumn(name).
Only columns of type int, double and str can currently be saved to Nexus
by :ref:`SaveNexus <algm-SaveNexus>` or
:ref:`SaveNexusProcessed <algm-SaveNexusProcessed>`. Columns of other types will
-simply be ommitted from the Nexus file without any error message.
+simply be omitted from the Nexus file without any error message.
Table rows
-----------
+##########
Cells with the same index form a row. TableRow class represents a row.
Use getRow(int) or getFirstRow() to access existing rows. For example:
@@ -85,7 +201,7 @@ TableRow can also be use for writing into a table:
| ``}``
Defining new column types
--------------------------
+#########################
Users can define new data types to be used in TableWorkspace.
TableColumn.h defines macro
@@ -94,8 +210,11 @@ c\_plus\_plus\_type must be a copyable type and operators << and >> must
be defined. There is also DECLARE\_TABLEPOINTERCOLUMN macro for
declaring non-copyable types, but it has never been used.
+
+
+
.. include:: WorkspaceNavigation.txt
-.. categories:: Concepts
\ No newline at end of file
+.. categories:: Concepts
diff --git a/docs/source/concepts/UnitFactory.rst b/docs/source/concepts/UnitFactory.rst
index 9ab93a73903065006f7ac82c524852e4d65948ed..300333779b0c543e37bd86b1390055db8ee805e3 100644
--- a/docs/source/concepts/UnitFactory.rst
+++ b/docs/source/concepts/UnitFactory.rst
@@ -1,16 +1,22 @@
.. _Unit Factory:
-Unit Factory
-============
+=====
+Units
+=====
-What is it?
------------
+.. contents::
+ :local:
+
+What are units?
+---------------
+
+Units are a set of small classes in Mantid that define a unit of measure, and the conversions between various units.
The Unit Factory is a :ref:`Dynamic Factory <Dynamic Factory>` that creates
and hands out instances of Mantid Unit objects.
Available units
-~~~~~~~~~~~~~~~
+---------------
The following units are available in the default Mantid distribution.
@@ -52,15 +58,76 @@ here is the Bragg scattering angle (e.g. half of the
Mantid z-axis)
**Note on Wavelength**: If the emode property in
-`ConvertUnits <http://docs.mantidproject.org/nightly/algorithms/ConvertUnits.html>`__
+:ref: `ConvertUnits <algm-ConvertUnits>`
is specified as inelastic Direct/Indirect (inelastic) then the
conversion to wavelength will take into account the fixed initial/final
energy respectively. Units conversion into elastic momentum transfer
(MomentumTransfer) will throw in elastic mode (emode=0) on inelastic
workspace (when energy transfer is specified along x-axis)
+
+Working with Units in Python
+----------------------------
+
+Accessing units on workspaces
+#############################
+
+Units on MatrixWorkspaces are accessed via the Axis.
+
+.. testcode:: UnitWorkspaceAxes
+
+
+ ws = CreateSampleWorkspace()
+ for i in range(ws.axes()):
+ axis = ws.getAxis(i)
+ print "Axis {0} is a {1}{2}{3}".format(i,
+ "Spectrum Axis" if axis.isSpectra() else "",
+ "Text Axis" if axis.isText() else "",
+ "Numeric Axis" if axis.isNumeric() else "")
+
+ unit = axis.getUnit()
+ print "\t caption:{0}".format(unit.caption())
+ print "\t symbol:{0}".format(unit.symbol())
+
+Output:
+
+.. testoutput:: UnitWorkspaceAxes
+ :options: +NORMALIZE_WHITESPACE
+
+ Axis 0 is a Numeric Axis
+ caption:Time-of-flight
+ symbol:microsecond
+ Axis 1 is a Spectrum Axis
+ caption:Spectrum
+ symbol:
+
+
+Setting the axisLabel to a Label of your choice
+###############################################
+
+
+.. testcode:: UnitAxesLabel
+
+ ws = CreateSampleWorkspace()
+ axis = ws.getAxis(1)
+ # Create a new axis
+ axis.setUnit("Label").setLabel('Temperature', 'K')
+
+ unit = axis.getUnit()
+ print "New caption:{0}".format(unit.caption())
+ print "New symbol:{0}".format(unit.symbol())
+
+Output:
+
+.. testoutput:: UnitAxesLabel
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ New caption:Temperature
+ New symbol:K
+
+
Adding new units
-~~~~~~~~~~~~~~~~
+----------------
Writing and adding a new unit is relatively straightforward.
Instructions will appear here in due course. In the meantime if a unit
diff --git a/docs/source/concepts/Workspace.rst b/docs/source/concepts/Workspace.rst
index a6a452f2ff8045db1c9f34616fbc411e40fd950c..a2d4a91b614349fb6561641da9bd6140e6c19a8f 100644
--- a/docs/source/concepts/Workspace.rst
+++ b/docs/source/concepts/Workspace.rst
@@ -1,10 +1,14 @@
.. _Workspace:
+=========
Workspace
=========
-What are they?
---------------
+.. contents::
+ :local:
+
+What are Workspaces?
+--------------------
Workspaces are the nouns of Mantid (while :ref:`algorithms <algorithm>` are
the verbs). Workspaces hold the data in Mantid.
@@ -54,15 +58,78 @@ Example Workspaces
workspaces. Algorithms given a group as input run sequentially on
each member of the group.
-Writing you own workspace
--------------------------
+Working with Workspaces in Python
+---------------------------------
+
+Workspace is an abstract description of an specific workspace implementation. It provides access to a few common properties without any knowledge of what the type of the workspace.
+
+.. _Workspace-Accessing_Workspaces:
+
+Accessing Workspaces
+####################
+
+You can access workspaces using the ``mtd["worskpace_name"]`` command for a specific workspace, or using the ``mtd.ImportAll()`` to create python variables for every workspace in Mantid. More explanation can be found in `Accessing Workspaces From Python <http://www.mantidproject.org/Accessing_Workspaces_From_Python/>`_.
+
+.. testcode:: AccessingWorkspaces
+
+ # This creates a workspace without explicitly capturing the output
+ CreateSampleWorkspace(OutputWorkspace="MyNewWorkspace")
+
+ # You can get a python variable pointing to the workspace with the command
+ myWS = mtd["MyNewWorkspace"]
+ print "The variable myWS now points to the workspace called ", myWS
+
+ # You can also ask Mantid to create matching python variables for all of it's workspaces
+ mtd.importAll()
+ print "MyNewWorkspace has been created that also points to the workspace called ", MyNewWorkspace
+
+ # You can assign a python variable when calling an algorithm and the workspace will match the variable name
+ myOtherWS = CreateSampleWorkspace()
+ print "myOtherWS now points to the workspace called ", myOtherWS
+
+Output:
+
+.. testoutput:: AccessingWorkspaces
+ :options: +NORMALIZE_WHITESPACE
+
+ The variable myWS now points to the workspace called MyNewWorkspace
+ MyNewWorkspace has been created that also points to the workspace called MyNewWorkspace
+ myOtherWS now points to the workspace called myOtherWS
+
+Workspace Properties
+####################
+
+You can look at the :ref:`Workspace API reference <mantid.api.Workspace>` for a full list of properties, but here are some of the key ones.
+
+.. testcode:: WorkspaceProperties
+
+ myWS = CreateSampleWorkspace()
+ print "name = " + myWS.getName()
+
+ myWS.setTitle("This is my Title")
+ print "getTitle = " + myWS.getTitle()
+
+ myWS.setComment("This is my comment")
+ print "comment = " + myWS.getComment()
+
+ print "id = " + myWS.id()
+
+ print "getMemorySize = " + str(myWS.getMemorySize())
+
+Output:
+
+.. testoutput:: WorkspaceProperties
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ name = myWS
+ getTitle = This is my Title
+ comment = This is my comment
+ id = Workspace2D
+ getMemorySize = ...
-This is perfectly possible, but not as easy as creating your own
-algorithm. Please talk to a member of the development team if you wish
-to implement you own workspace.
Workspace Types
----------------
+^^^^^^^^^^^^^^^
The workspace type id identifies the type (underlying class) of a
Workspace object. These IDs are listed here for ease of reference, so
@@ -101,5 +168,47 @@ createWorkspace if you are writing C++ or Python algorithms.
+-------------------------------+-------------------------------------------+
+Workspace History
+#################
+
+Workspaces keep a track of all of the algorithms used on them, so you can ask a workspace to tell you about it's history. The algorithm :ref:`GeneratePythonScript <algm-GeneratePythonScript>` uses this information to create a python script able to re-run the workspace history.
+
+.. testcode:: WorkspaceHistory
+
+ # Run a few algorithms
+ myWS = CreateSampleWorkspace()
+ myWS = ConvertUnits(myWS,Target="Wavelength")
+ myWS = Rebin(myWS,Params=200)
+
+ # You can access the history using getHistory()
+ history = myWS.getHistory()
+ for algHistory in history.getAlgorithmHistories():
+ print algHistory.name()
+ for property in algHistory.getProperties():
+ if not property.isDefault():
+ print "\t" + property.name() + " = " + property.value()
+
+Output:
+
+.. testoutput:: WorkspaceHistory
+ :options: +ELLIPSIS,+NORMALIZE_WHITESPACE
+
+ CreateSampleWorkspace
+ OutputWorkspace = myWS
+ ConvertUnits
+ InputWorkspace = myWS
+ OutputWorkspace = myWS
+ Target = Wavelength
+ Rebin
+ InputWorkspace = myWS
+ OutputWorkspace = myWS
+ Params = 200
+
+Writing you own workspace
+-------------------------
+
+This is perfectly possible, but not as easy as creating your own
+algorithm. Please talk to a member of the development team if you wish
+to implement you own workspace.
-.. categories:: Concepts
\ No newline at end of file
+.. categories:: Concepts
diff --git a/docs/source/concepts/Workspace2D.rst b/docs/source/concepts/Workspace2D.rst
index d9df4833ae25177c02ec41da13c220bb9ac04d0c..84d9dbda158ccfbd24ef6c9f07ccee6c2f9677b6 100644
--- a/docs/source/concepts/Workspace2D.rst
+++ b/docs/source/concepts/Workspace2D.rst
@@ -1,8 +1,12 @@
.. _Workspace2D:
+===========
Workspace2D
===========
+.. contents::
+ :local:
+
The Workspace2D is a Mantid data type for a
:ref:`MatrixWorkspace <MatrixWorkspace>`.
@@ -18,6 +22,32 @@ histogram (with X,Y,E values) but preserves the underlying event data.
For more information on what a Workspace2D contains, see
:ref:`MatrixWorkspace <MatrixWorkspace>`.
+Working with Workspace2Ds in Python
+-----------------------------------
+
+Workspace2D is a :ref:`MatrixWorkspace <MatrixWorkspace>` and does not offer any functionality above that of a Matrix Workspace.
+
+Accessing Workspaces
+####################
+
+The methods for getting a variable to an EventWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is a Workspace2D you can use this:
+
+.. testcode:: CheckWorkspace2D
+
+ histoWS = CreateSampleWorkspace()
+
+ if histoWS.id() == "Workspace2D":
+ print histoWS.getName() + " is an " + histoWS.id()
+
+Output:
+
+.. testoutput:: CheckWorkspace2D
+ :options: +NORMALIZE_WHITESPACE
+
+ histoWS is an Workspace2D
+
.. include:: WorkspaceNavigation.txt
diff --git a/docs/source/concepts/WorkspaceGroup.rst b/docs/source/concepts/WorkspaceGroup.rst
index d56e64137435d7f69492e4062d8f43632a04d043..d6451f732c4ded3d5fc366f633c0d06cd0b91b24 100644
--- a/docs/source/concepts/WorkspaceGroup.rst
+++ b/docs/source/concepts/WorkspaceGroup.rst
@@ -1,8 +1,13 @@
.. _WorkspaceGroup:
+===============
Workspace Group
===============
+
+.. contents::
+ :local:
+
A WorkspaceGroup is a group of workspaces.
Most algorithms will execute on a WorkspaceGroup by simply executing the
@@ -21,6 +26,114 @@ Un-grouping Workspaces
- Select the WorkspaceGroup and click "Ungroup".
- Use the :ref:`UnGroupWorkspace <algm-UnGroupWorkspace>` algorithm.
+Working with Event Workspaces in Python
+----------------------------------------
+
+Creating and splitting groups
+#############################
+
+.. testcode:: CreatingWorkspaceGroups
+
+ ws1 = CreateSampleWorkspace()
+ ws2 = CreateSampleWorkspace()
+ ws3 = CreateSampleWorkspace()
+
+
+ # Create a group workpace
+ wsList = [ws1,ws2,ws3]
+ wsGroup = GroupWorkspaces(wsList)
+ # or
+ wsGroup = GroupWorkspaces("ws1,ws2,ws3")
+
+ print wsGroup.getNames()
+
+ # Remove the group
+ # The child workspaces will be preserved
+ UnGroupWorkspace(wsGroup)
+ # Using wsGroup now will cause a runtime error
+ # RuntimeError: Variable invalidated, data has been deleted.
+
+
+.. testoutput:: CreatingWorkspaceGroups
+ :hide:
+ :options: +NORMALIZE_WHITESPACE
+
+ ['ws1','ws2','ws3']
+
+Accessing Workspace Groups
+##########################
+
+The methods for getting a variable to an EventWorkspace is the same as shown in the :ref:`Workspace <Workspace-Accessing_Workspaces>` help page.
+
+If you want to check if a variable points to something that is a Workspace Group you can use this:
+
+.. testcode:: CheckGroupWorkspace
+
+ from mantid.api import WorkspaceGroup
+
+ ws1 = CreateSampleWorkspace()
+ ws2 = CreateSampleWorkspace()
+ wsGroup = GroupWorkspaces("ws1,ws2")
+
+ if isinstance(wsGroup, WorkspaceGroup):
+ print wsGroup.getName() + " is an " + wsGroup.id()
+
+Output:
+
+.. testoutput:: CheckGroupWorkspace
+ :options: +NORMALIZE_WHITESPACE
+
+ wsGroup is an WorkspaceGroup
+
+Looping over all of the members of a group
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. testcode:: GroupWorkspaceMembers
+
+ ws1 = CreateSampleWorkspace()
+ ws2 = CreateSampleWorkspace()
+ wsGroup = GroupWorkspaces("ws1,ws2")
+
+ print "Number of members:", wsGroup.getNumberOfEntries()
+ print "List of names:", wsGroup.getNames()
+
+ # Get the member workspaces in a loop
+ for i in range(wsGroup.getNumberOfEntries()):
+ wsLoop = wsGroup.getItem(i)
+ print "Member", i, wsLoop
+
+
+Output:
+
+.. testoutput:: GroupWorkspaceMembers
+ :options: +NORMALIZE_WHITESPACE
+
+ Number of members: 2
+ List of names: ['ws1','ws2']
+ Member 0 ws1
+ Member 1 ws2
+
+Using Workspace Groups in Algorithms
+####################################
+
+You can pass workspace groups into any algorithm and Mantid will run that algorithm for each member of the workspace group.
+
+.. testcode:: CheckGroupWorkspace
+
+ ws1 = CreateSampleWorkspace()
+ ws2 = CreateSampleWorkspace()
+ wsGroup = GroupWorkspaces("ws1,ws2")
+ wsGroup2 = GroupWorkspaces("ws2,ws1")
+
+ # This will add the member workspaces in a pair like manner
+ wsGroup3 = wsGroup + wsGroup2
+
+ # Rebin all of wsGroup
+ wsRebinned = Rebin(wsGroup, Params=200)
+
+ # You can still of course refer to members of a group directly
+ ws1 = Rebin(ws1, Params=100)
+
.. include:: WorkspaceNavigation.txt
diff --git a/docs/source/images/PlotMatrixWorkspaceYUnitElephants.png b/docs/source/images/PlotMatrixWorkspaceYUnitElephants.png
new file mode 100644
index 0000000000000000000000000000000000000000..e8e90bdd1667ba7c37e131f416a4fee98a8d4c23
Binary files /dev/null and b/docs/source/images/PlotMatrixWorkspaceYUnitElephants.png differ
diff --git a/docs/source/interfaces/Engineering_Diffraction.rst b/docs/source/interfaces/Engineering_Diffraction.rst
index 9e372a09396749b826ad9d4c6fcb5672323c95e0..6c1c9f97e8dd1a3b656ee3691ff2054f7c75e536 100644
--- a/docs/source/interfaces/Engineering_Diffraction.rst
+++ b/docs/source/interfaces/Engineering_Diffraction.rst
@@ -93,8 +93,8 @@ For texture focusing, the detector grouping file is a text (csv) file
with one line per bank. Each line must contain at least two numeric
fields, where the first one specifies the bank ID, and the second and
subsequent ones different spectrum numbers or ranges of spectrum
-numbers. For example:
-::
+numbers. For example::
+
# Bank ID, spectrum numbers
1, 205-210
2, 100, 102, 107
diff --git a/docs/source/interfaces/HFIRPowderReduction.rst b/docs/source/interfaces/HFIRPowderReduction.rst
index 44d329777caa023b14f52d84cc08a58a6644051a..10ed6729b421d248b5d02222ef7fd63a02062516 100644
--- a/docs/source/interfaces/HFIRPowderReduction.rst
+++ b/docs/source/interfaces/HFIRPowderReduction.rst
@@ -145,6 +145,7 @@ Raw data correction files
=========================
1. **Detector efficiency**:
+
- File name: *HB2A_exp0IJK__GE_abc_XY_vcorr.txt* where
- IJK is the experiment number
diff --git a/docs/source/interfaces/ISIS_Reflectometry.rst b/docs/source/interfaces/ISIS_Reflectometry.rst
index 0ca729da20217d08270a7e2f8e793d359a157c1d..8b9d64a6bde4728058c1582b316cc1c6bab4628f 100644
--- a/docs/source/interfaces/ISIS_Reflectometry.rst
+++ b/docs/source/interfaces/ISIS_Reflectometry.rst
@@ -128,7 +128,7 @@ The **Reflectometry** menu provides access to the following functionality:
| | by the :ref:`CalculateSlits <algm-CalculateSlits>` |
| | algorithm. |
+------------------+----------------------------------------------------------+
-| Options | Opens the `Options`_ menu. |
+| Options | Opens the `Options <ISIS_Reflectomety-Options>`_ menu. |
+------------------+----------------------------------------------------------+
The **Edit** menu provides access to the same actions found in the tool bar.
@@ -343,9 +343,10 @@ Measure based search transfer uses the log-values within nexus files from the ex
placed into the same group.
- Any runs with the ``same measurement_id`` and the same ``measurement_subid`` logs, will be merged into a single row, with all the runs listed in the **Run(s)** column in the format, ``123+124+125``.
+.. _ISIS_Reflectomety-Options:
Options
-~~~~~~~
+-------
Through the options menu, a small number of options may be configured to adjust
the behaviour of the interface.