/
AlgorithmUsageExamples.html
343 lines (263 loc) · 18.5 KB
/
AlgorithmUsageExamples.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Algorithm Usage Examples</title>
<link rel="stylesheet" href="_static/basic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" type="text/css" />
<link rel="stylesheet" href="_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.12.20180329.1038',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head>
<body role="document">
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org"><img src="_static/Mantid_Logo_Transparent.png">
</a>
<span class="navbar-text navbar-version pull-left"><b>3.12</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="http://www.mantidproject.org">Home</a></li>
<li><a href="http://download.mantidproject.org">Download</a></li>
<li><a href="http://www.mantidproject.org/Documentation">Documentation</a></li>
<li><a href="http://www.mantidproject.org/Contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-12 content">
<div class="section" id="algorithm-usage-examples">
<span id="algorithmusageexamples"></span><h1>Algorithm Usage Examples<a class="headerlink" href="#algorithm-usage-examples" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li>
<li><a class="reference internal" href="#guide" id="id2">Guide</a><ul>
<li><a class="reference internal" href="#using-createsampleworkspace-and-createworkspace" id="id3">Using CreateSampleWorkspace and CreateWorkspace</a></li>
<li><a class="reference internal" href="#when-needing-to-load-a-data-file" id="id4">When needing to load a data file</a></li>
</ul>
</li>
<li><a class="reference internal" href="#running-the-tests" id="id5">Running the Tests</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>A <em>usage example</em> is part of the documentation page of an algorithm.</p>
<p>From a user’s point of view, the main purposes of usage examples are:</p>
<ul class="simple">
<li>Getting started using the algorithm as part of a Python script</li>
<li>Understanding the algorithm</li>
<li>Showing hints/comments etc. that help understand Mantid Python scripting in general</li>
</ul>
<p>The usage examples are written in <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>, which can be converted to HTML and the code in the usage examples can be tested. The image below demonstrates an example of converting reStructuredText to HTML.</p>
</div>
<div class="section" id="guide">
<h2><a class="toc-backref" href="#id2">Guide</a><a class="headerlink" href="#guide" title="Permalink to this headline">¶</a></h2>
<p>The example below show the proposed way to format an usage example in reStructuredText.</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Usage</span>
<span class="gh">-----</span>
<span class="gs">**Example - simple rebin of a histogram workspace:**</span>
<span class="p">..</span> <span class="ow">testcode</span><span class="p">::</span> ExHistSimple
# create histogram workspace
dataX = [0,1,2,3,4,5,6,7,8,9] # or use dataX=range(0,10)
dataY = [1,1,1,1,1,1,1,1,1] # or use dataY=[1]*9
ws = CreateWorkspace(dataX, dataY)
# rebin from min to max with size bin = 2
ws = Rebin(ws, 2)
print "The rebinned X values are: " + str(ws.readX(0))
print "The rebinned Y values are: " + str(ws.readY(0))
Output:
<span class="p">..</span> <span class="ow">testoutput</span><span class="p">::</span> ExHistSimple
The rebinned X values are: [ 0. 2. 4. 6. 8. 9.]
The rebinned Y values are: [ 2. 2. 2. 2. 1.]
</pre></div>
</div>
<p>What is required is:</p>
<ul class="simple">
<li>Short description explaining the example, formatted as shown above, i.e. using <code class="docutils literal"><span class="pre">**</span></code> to embolden the text.</li>
<li>A <code class="docutils literal"><span class="pre">..</span> <span class="pre">testcode::</span></code> section, with a unique ‘namespace’ name, here <code class="docutils literal"><span class="pre">ExHistSimple</span></code>. This ‘namespace’ is not shown when converted to HTML, but is used in testing the code. This section contains the actual Python code demonstrating a usage of the algorithm. This code block contains commented code, finishing with one or more Python <code class="docutils literal"><span class="pre">print</span></code> lines as shown</li>
<li>A <code class="docutils literal"><span class="pre">..</span> <span class="pre">testoutput::</span></code> section. This section must have a matching ‘namespace’ name to the <code class="docutils literal"><span class="pre">..testcode::</span></code> section. It simply contains a copy of the text that is printed out in the <code class="docutils literal"><span class="pre">..testcode::</span></code> section.</li>
<li>Include the “Output:” string above the <code class="docutils literal"><span class="pre">..testoutput::</span></code> directive.</li>
</ul>
<p>What is optional:</p>
<ul class="simple">
<li>A <code class="docutils literal"><span class="pre">..testcleanup::</span></code> section. This section must have a matching ‘namespace’ name to the <code class="docutils literal"><span class="pre">..testcode::</span></code> section. Here, add Python code to do any cleanup of files etc. that were created by the tests. See the notes below for things that are cleaned automatically.</li>
</ul>
<p>Notes:</p>
<ul class="simple">
<li>The configuration has a global “testcleanup” implemented which calls <code class="docutils literal"><span class="pre">FrameworkManager::clear()</span></code> to clear algorithms, workspaces & instruments so these are dealt with automatically.</li>
<li>There must be a clear blank line before the <code class="docutils literal"><span class="pre">..</span> <span class="pre">testcode::</span></code> and <code class="docutils literal"><span class="pre">..</span> <span class="pre">testoutput</span></code> directives or the test is ignored. As with unit tests you should write a failing test first to ensure it is running.</li>
</ul>
<p>What is worth keeping in mind is:</p>
<ul class="simple">
<li><em>Assume the user is new to Python</em>. Consider giving hints to more advanced Python in comments, or introduce a simple example first.</li>
<li>Use comments.</li>
<li>Use Python <code class="docutils literal"><span class="pre">print</span></code> to output results, which, where possible, helps to understand the algorithm.</li>
</ul>
<p>A Jenkins job tests that the usage examples are not broken, i.e. that they continue to provide a working demonstration against the current build. It is vital to stress that the purpose of usage testing is <em>not to replace unit testing</em> (or system testing). The purpose of usage testing (better described as demonstration examples), is to provide some happy-path examples, which, where this is possible, can assist the user understanding of the Python code. This is very different from the purposes of testing in general, see <a class="reference external" href="UnitTestGoodPractice.html">here</a>.</p>
<p>Additional benefits of usage examples:</p>
<ul class="simple">
<li>Quick look-up for developers on how to use a certain algorithm in Python scripting</li>
<li>Allow the user to test that scripts return expected output in their installed Mantid versions</li>
<li>Additional test coverage of Mantid Python API</li>
</ul>
<div class="section" id="using-createsampleworkspace-and-createworkspace">
<h3><a class="toc-backref" href="#id3">Using CreateSampleWorkspace and CreateWorkspace</a><a class="headerlink" href="#using-createsampleworkspace-and-createworkspace" title="Permalink to this headline">¶</a></h3>
<p>There are many ways to create sample workspaces. For example <a class="reference external" href="http://docs.mantidproject.org/nightly/algorithms/CreateMDHistoWorkspace-v1.html#algm-createmdhistoworkspace" title="(in MantidProject v3.12)"><span class="xref std std-ref">CreateMDHistoWorkspace</span></a>, <a class="reference external" href="http://docs.mantidproject.org/nightly/algorithms/CreateSampleWorkspace-v1.html#algm-createsampleworkspace" title="(in MantidProject v3.12)"><span class="xref std std-ref">CreateSampleWorkspace</span></a> and <a class="reference external" href="http://docs.mantidproject.org/nightly/algorithms/CreateWorkspace-v1.html#algm-createworkspace" title="(in MantidProject v3.12)"><span class="xref std std-ref">CreateWorkspace</span></a>. CreateSampleWorkspace creates a fully defined workspace (either event or histogram) but for creating simple histogram workspace CreateWorkspace may be a better option. Above is shown an example where CreateWorkspace is used. Below is a more complex use of CreateSampleWorkspace:</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Usage</span>
<span class="gh">-----</span>
<span class="gs">**Example - Fit a Gaussian to a peak in a spectrum:**</span>
<span class="p">..</span> <span class="ow">testcode</span><span class="p">::</span> ExFitPeak
# create a workspace with a gaussian peak sitting on top of a linear (here flat) background
ws = CreateSampleWorkspace(Function="User Defined", UserDefinedFunction="name=LinearBackground, \
A0=0.3;name=Gaussian, PeakCentre=5, Height=10, Sigma=0.7", NumBanks=1, BankPixelWidth=1, XMin=0, XMax=10, BinWidth=0.1)
# Setup the data to fit:
workspaceIndex = 0 # the spectrum with which WorkspaceIndex to fit
startX = 1 # specify fitting region
endX = 9 #
# Setup the model, here a Gaussian, to fit to data
tryCentre = '4' # A start guess on peak centre
sigma = '1' # A start guess on peak width
height = '8' # A start guess on peak height
myFunc = 'name=Gaussian, Height='+height+', PeakCentre='+tryCentre+', Sigma='+sigma
# here purposely haven't included a linear background which mean fit will not be spot on
# to include a linear background uncomment the line below
#myFunc = 'name=LinearBackground, A0=0.3;name=Gaussian, Height='+height+', PeakCentre='+tryCentre+', Sigma='+sigma
# Do the fitting
fitStatus, chiSq, covarianceTable, paramTable, fitWorkspace = Fit(InputWorkspace='ws', \
WorkspaceIndex=0, StartX = startX, EndX=endX, Output='fit', Function=myFunc)
print "The fit was: " + fitStatus
print("chi-squared of fit is: %.2f" % chiSq)
print("Fitted Height value is: %.2f" % paramTable.column(1)[0])
print("Fitted centre value is: %.2f" % paramTable.column(1)[1])
print("Fitted sigma value is: %.2f" % paramTable.column(1)[2])
# fitWorkspace contains the data, the calculated and the difference patterns
print "Number of spectra in fitWorkspace is: " + str(fitWorkspace.getNumberHistograms())
print("The 20th y-value of the calculated pattern: %.4f" % fitWorkspace.readY(1)[19])
<span class="p">..</span> <span class="ow">testcleanup</span><span class="p">::</span> ExFitPeak
DeleteWorkspace(ws)
Output:
<span class="p">..</span> <span class="ow">testoutput</span><span class="p">::</span> ExFitPeak
The fit was: success
chi-squared of fit is: 0.14
Fitted Height value is: 9.79
Fitted centre value is: 5.05
Fitted sigma value is: 0.77
Number of spectra in fitWorkspace is: 3
The 20th y-value of the calculated pattern: 0.2361
</pre></div>
</div>
<p>For a more simple use of CreateSampleWorkspace see example below (note if no arguments are given then a histogram workspace is created):</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Usage</span>
<span class="gh">-----</span>
<span class="gs">**Example - use option PreserveEvents:**</span>
<span class="p">..</span> <span class="ow">testcode</span><span class="p">::</span> ExEventRebin
# create some event workspace
ws = CreateSampleWorkspace(WorkspaceType="Event")
print "What type is the workspace before 1st rebin: " + str(type(ws))
# rebin from min to max with size bin = 2 preserving event workspace (default behaviour)
ws = Rebin(ws, 2)
print "What type is the workspace after 1st rebin: " + str(type(ws))
ws = Rebin(ws, 2, PreserveEvents=False)
print "What type is the workspace after 2nd rebin: " + str(type(ws))
# note you can also check the type of a workspace using: print isinstance(ws, IEventWorkspace)
<span class="p">..</span> <span class="ow">testcleanup</span><span class="p">::</span> ExEventRebin
DeleteWorkspace(ws)
Output:
<span class="p">..</span> <span class="ow">testoutput</span><span class="p">::</span> ExEventRebin
What type is the workspace before 1st rebin: <class 'mantid.api._api.IEventWorkspace'>
What type is the workspace after 1st rebin: <class 'mantid.api._api.IEventWorkspace'>
What type is the workspace after 2nd rebin: <class 'mantid.api._api.MatrixWorkspace'>
</pre></div>
</div>
</div>
<div class="section" id="when-needing-to-load-a-data-file">
<h3><a class="toc-backref" href="#id4">When needing to load a data file</a><a class="headerlink" href="#when-needing-to-load-a-data-file" title="Permalink to this headline">¶</a></h3>
<p>Instructions to add a new data file to the repository are available <a class="reference external" href="DataFilesForTesting.html">here</a>. Files from the repository will be bundled up into a .zip file, and this .zip made available for download from the Mantid download page.</p>
<p>If you use files you must add the line</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="p">..</span> <span class="ow">include</span><span class="p">::</span> ../usagedata-note.txt
</pre></div>
</div>
<p>as shown in the example below. This will generate a note to the user explaining how to download the UsageData.</p>
<div class="highlight-rest"><div class="highlight"><pre><span></span><span class="gh">Usage</span>
<span class="gh">-----</span>
<span class="p">..</span> <span class="ow">include</span><span class="p">::</span> ../usagedata-note.txt
<span class="gs">**Example - Load ISIS histogram Nexus file:**</span>
(see <span class="na">:ref:</span><span class="nv">`LoadISISNexus <algm-LoadISISNexus>`</span> for more options)
<span class="p">..</span> <span class="ow">testcode</span><span class="p">::</span> ExLoadISISnexusHist
# Load ISIS LOQ histogram dataset
ws = Load('LOQ49886.nxs')
print "The 1st x-value of the first spectrum is: " + str(ws.readX(0)[0])
<span class="p">..</span> <span class="ow">testcleanup</span><span class="p">::</span> ExLoadISISnexusHist
DeleteWorkspace(ws)
Output:
<span class="p">..</span> <span class="ow">testoutput</span><span class="p">::</span> ExLoadISISnexusHist
The 1st x-value of the first spectrum is: 5.0
</pre></div>
</div>
</div>
</div>
<div class="section" id="running-the-tests">
<h2><a class="toc-backref" href="#id5">Running the Tests</a><a class="headerlink" href="#running-the-tests" title="Permalink to this headline">¶</a></h2>
<p>See <a class="reference external" href="DocumentationGuideForDevs.html">here</a> for how to run and test the usage examples locally.</p>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>