\(\renewcommand\AA{\unicode{x212B}}\)
A WorkspaceGroup is a group of workspaces. The WorkspaceGroup object does not hold any data itself, but instead holds a list of Workspace objects. They appear as an expandable list of workspaces in the Workspaces Toolbox in the main window (the list of workspaces is also called the ADS or AnalysisDataService). Thus, workspace groups add structure to the ADS and make it more readable and also allow algorithms to be executed over a list of workspaces contained within the group but passing the group to the algorithm.
Most algorithms can be passed a WorkspaceGroup in place of a normal workspace input, and will simply execute the algorithm on each workspace contained within the group.
Workspace groups can be created through the MantidWorkbench interface;
Workspace groups can be created in a more flexible way in the Python script window using the Python API. Groups may be created via the GroupWorkspaces algorithm, This will place a workspace group directly into the ADS, and requires at least one workspace to be added to the group.
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.
Output:
['ws1','ws2','ws3']
To avoid interaction with the ADS, a WorkspaceGroup object can be instantiated using
import mantid.api as api
ws_group = api.WorkspaceGroup()
This will not be automatically added to the ADS, to do so, use the following line
AnalysisDataService.add("name", ws_group)
the group should then appear in the ADS with the given name. Using direct instantiation; groups can be added to the ADS and then workspaces added to the group via their name and the add method;
from mantid.api import WorkspaceGroup
ws1 = CreateSampleWorkspace()
ws2 = CreateSampleWorkspace()
ws3 = CreateSampleWorkspace()
# Create a group workspace and add to the ADS
ws_group = WorkspaceGroup()
mtd.add("group1", ws_group)
ws_group.add("ws1")
ws_group.add("ws2")
ws_group.add("ws3")
print(ws_group.getNames())
Output:
['ws1','ws2','ws3']
Alternatively, workspace group objects can be fed workspaces which are not in the ADS (in this case the addWorkspace method is used rather than add because add requires a name, and since the workspaces are not in the ADS they may not have a name)
from mantid.api import WorkspaceGroup
ws1 = WorkspaceFactory.create("Workspace2D", 2, 2, 2)
ws2 = WorkspaceFactory.create("Workspace2D", 2, 2, 2)
ws3 = WorkspaceFactory.create("Workspace2D", 2, 2, 2)
# Create a group workspace
ws_group = WorkspaceGroup()
ws_group.addWorkspace(ws1)
ws_group.addWorkspace(ws2)
ws_group.addWorkspace(ws3)
print(ws_group.getNames())
mtd.add("group1", ws_group)
print(ws_group.getNames())
Output:
['','','']
['group1_1','group1_2','group1_3']
when adding the group to the ADS, the workspaces will also be added, and given default names. It is not recommended to add workspace to groups in this way, as much of the functionality of groups depends on workspaces having names; for example the “in” keyword.
The methods for getting a variable to a WorkspaceGroup is the same as shown in the Workspace help page.
If you want to check if a variable points to something that is a Workspace Group you can use this:
from mantid.api import WorkspaceGroup
ws1 = CreateSampleWorkspace()
ws2 = CreateSampleWorkspace()
wsGroup = GroupWorkspaces("ws1,ws2")
if isinstance(wsGroup, WorkspaceGroup):
print(wsGroup.name() + " is an " + wsGroup.id())
Output:
wsGroup is an WorkspaceGroup
ws1 = CreateSampleWorkspace()
ws2 = CreateSampleWorkspace()
wsGroup = GroupWorkspaces("ws1,ws2")
print("Number of members: " + str(wsGroup.getNumberOfEntries()))
print("List of names: " + str(wsGroup.getNames()))
# Get the member workspaces in a loop
for i in range(wsGroup.getNumberOfEntries()):
wsLoop = wsGroup.getItem(i)
print("Member {0} {1}".format(i, wsLoop.name()))
Output:
Number of members: 2
List of names: ['ws1','ws2']
Member 0 ws1
Member 1 ws2
You can pass workspace groups into any algorithm and Mantid will run that algorithm for each member of the workspace group.
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)
ws1 = CreateSampleWorkspace()
ws2 = CreateSampleWorkspace()
wsGroup = GroupWorkspaces("ws1,ws2")
for ws in list(wsGroup):
DeleteWorkspace(ws)
otherwise indexing will be confused by each deletion.
ws1 = CreateSampleWorkspace()
ws2 = CreateSampleWorkspace()
wsGroup = GroupWorkspaces("ws1,ws2")
DeleteWorkspace(wsGroup)
Category: Concepts