-
Notifications
You must be signed in to change notification settings - Fork 0
/
IndexProperty.html
236 lines (186 loc) · 17.4 KB
/
IndexProperty.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
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Index Property</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css?v=fadd4351" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=77160d70" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Adding a new fitting function to IDA" href="IndirectDataAnalysisAddingFitType.html" />
<link rel="prev" title="Handling XML" href="HandlingXML.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>
<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">
</a>
<span class="navbar-text navbar-version pull-left"><b>main</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="https://download.mantidproject.org">Download</a></li>
<li><a href="https://docs.mantidproject.org">User 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>
<p>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="nav-item nav-item-0"><a href="index.html">Documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Index Property</a></li>
</ul>
</div> </p>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<section id="index-property">
<span id="indexproperty"></span><h1>Index Property<a class="headerlink" href="#index-property" title="Link to this heading">¶</a></h1>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#why-indexproperty" id="id5">Why IndexProperty?</a></p></li>
<li><p><a class="reference internal" href="#how-to-use-the-indexproperty" id="id6">How to use the IndexProperty</a></p></li>
</ul>
</nav>
<section id="why-indexproperty">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Why IndexProperty?</a><a class="headerlink" href="#why-indexproperty" title="Link to this heading">¶</a></h2>
<p>In many cases, indices are captured from the user with the <code class="docutils literal notranslate"><span class="pre">ArrayProperty<int></span></code> property type. However, this lacks a few key behaviours which
a property collecting workspace index information should have. Firstly, there is no automatic validation of the indices with respect to
the workspace itself. Therefore users could enter invalid input e.g negative numbers, or numbers outside of
the range of spectra held by the workspace, unless bounded validators or used. Finally, any conversion between “index types” i.e. conversion from
spectrum numbers to workspace indices (also known as spectrum indices) must be managed by the algorithm developer. This style
of development is very error prone and could lead to inconsitencies across algorithms as
each developer may have a different approach to addressing the aforementioned issues.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">IndexProperty</span></code> in Mantid provides a consistent interface for algorithms
which need to access a subset of the workspace spectra for processing.The <code class="docutils literal notranslate"><span class="pre">IndexProperty</span></code> facilitates
the retrieval of a set of workspace indices, called a <code class="docutils literal notranslate"><span class="pre">SpectrumIndexSet</span></code>, once provided with a set of workspace indices or
spectrum numbers <a class="footnote-reference brackets" href="#id2" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a>. Therefore algorithm developers do not need to perform any conversions manually.</p>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id2" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>
<p>Not specifying any indices/spectrum numbers results in the processing of the entire workspace.</p>
</aside>
</aside>
</section>
<section id="how-to-use-the-indexproperty">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">How to use the IndexProperty</a><a class="headerlink" href="#how-to-use-the-indexproperty" title="Link to this heading">¶</a></h2>
<p>Unlike other property types in Mantid, the <code class="docutils literal notranslate"><span class="pre">IndexProperty</span></code> is designed to be used in conjunction with other properties
which define the workspace and the input type of the indices which represent
the subset of the data. However, developers do not need to concern themselves
with maintaining these properties on their own. There are few special methods in
<code class="docutils literal notranslate"><span class="pre">Algorithm</span></code> which handle this. Namely, <code class="docutils literal notranslate"><span class="pre">Algorithm::declareWorkspaceInputProperties</span></code>,
<code class="docutils literal notranslate"><span class="pre">Algorithm::setWorkspaceInputProperties</span></code> and <code class="docutils literal notranslate"><span class="pre">Algorithm::getWorkspaceAndIndices</span></code> <a class="footnote-reference brackets" href="#id4" id="id3" role="doc-noteref"><span class="fn-bracket">[</span>2<span class="fn-bracket">]</span></a>.</p>
<p>Property declaration is as shown below:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="cp">#include</span><span class="w"> </span><span class="cpf">"MantidAPI/Algorithm.tcc"</span>
<span class="c1">// Declare property with default settings</span>
<span class="c1">// IndexType::WorkspaceIndex is default</span>
<span class="n">declareWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="o">></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span>
<span class="w"> </span><span class="s">"This is an input workspace with associated index handling"</span><span class="p">);</span>
<span class="c1">// Declare all arguments</span>
<span class="n">declareWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="p">,</span>
<span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">SpectrumNum</span><span class="w"> </span><span class="o">|</span><span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">WorkspaceIndex</span><span class="o">></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span>
<span class="w"> </span><span class="s">"This is an input workspace with associated index handling"</span>
<span class="w"> </span><span class="cm">/* optional PropertyMode, LockMode, and validator forwarded to WorkspaceProperty */</span><span class="p">);</span>
</pre></div>
</div>
<p>Internally, a <code class="docutils literal notranslate"><span class="pre">WorkspaceProperty</span></code> is created along with an <code class="docutils literal notranslate"><span class="pre">IndexTypeProperty</span></code> for
managing the workspace and the type of user-defined input index list respectively. Their names are
automatically generated based on the property name in the declaration.
A toy example algorithm dialog in the GUI would have the following inputs defined:</p>
<a class="reference internal image-reference" href="_images/IndexPropertyDialogExample.png"><img alt="Toy Example of an Algorithm Dialog using IndexProperty" src="_images/IndexPropertyDialogExample.png" style="height: 300px;" />
</a>
<p>After properties have been set, client code can retrieve the values of interest from
within the algorithm as follows:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">//Declare workspace and index set</span>
<span class="n">MatrixWorkspace_sptr</span><span class="w"> </span><span class="n">inputWs</span><span class="p">;</span>
<span class="n">SpectrumIndexSet</span><span class="w"> </span><span class="n">indexSet</span><span class="p">;</span>
<span class="c1">//Method returns a tuple of the workspace</span>
<span class="c1">//and index set simultaneously</span>
<span class="n">std</span><span class="o">::</span><span class="n">tie</span><span class="p">(</span><span class="n">inputWs</span><span class="p">,</span><span class="w"> </span><span class="n">indexSet</span><span class="p">)</span><span class="w"> </span><span class="o">=</span>
<span class="w"> </span><span class="n">getWorkspaceAndIndices</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="o">></span><span class="p">(</span><span class="s">"InputWorkspace"</span><span class="p">);</span>
<span class="k">for</span><span class="p">(</span><span class="k">auto</span><span class="w"> </span><span class="n">index</span><span class="o">:</span><span class="w"> </span><span class="n">indexSet</span><span class="p">){</span>
<span class="w"> </span><span class="k">auto</span><span class="w"> </span><span class="o">&</span><span class="n">spec</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">inputWs</span><span class="o">-></span><span class="n">getSpectrum</span><span class="p">(</span><span class="n">index</span><span class="p">);</span>
<span class="w"> </span><span class="c1">//do something with spectrum.</span>
<span class="p">}</span>
</pre></div>
</div>
<p>For setting the property values, there are 4 valid options:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="c1">//Set Property with workspace_sptr and string of indices</span>
<span class="n">setWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span><span class="w"> </span><span class="n">ws</span><span class="p">,</span><span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">WorkspaceIndex</span><span class="p">,</span><span class="w"> </span><span class="s">"1:5"</span><span class="p">)</span>
<span class="c1">//Set Property with workspace name and string of indices</span>
<span class="n">setWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">string</span><span class="o">></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span><span class="w"> </span><span class="s">"ws"</span><span class="p">,</span><span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">WorkspaceIndex</span><span class="p">,</span><span class="w"> </span><span class="s">"1:5"</span><span class="p">)</span>
<span class="c1">//Set Property with workspace_sptr and vector of indices</span>
<span class="n">setWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">>></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span><span class="w"> </span><span class="n">ws</span><span class="p">,</span><span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">WorkspaceIndex</span><span class="p">,</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">})</span>
<span class="c1">//Set Property with workspace name and vector of indices</span>
<span class="n">setWorkspaceInputProperties</span><span class="o"><</span><span class="n">MatrixWorkspace</span><span class="p">,</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">>></span><span class="p">(</span>
<span class="w"> </span><span class="s">"InputWorkspace"</span><span class="p">,</span><span class="w"> </span><span class="s">"ws"</span><span class="p">,</span><span class="w"> </span><span class="n">IndexType</span><span class="o">::</span><span class="n">WorkspaceIndex</span><span class="p">,</span>
<span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o"><</span><span class="kt">int</span><span class="o">></span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">})</span>
</pre></div>
</div>
<aside class="footnote-list brackets">
<aside class="footnote brackets" id="id4" role="doc-footnote">
<span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id3">2</a><span class="fn-bracket">]</span></span>
<p>It is important to note that any attempt to access the <code class="docutils literal notranslate"><span class="pre">IndexProperty</span></code> or the <code class="docutils literal notranslate"><span class="pre">WorkspaceProperty</span></code> in isolation will fail. Once defined using the <code class="docutils literal notranslate"><span class="pre">Algorithm::declareWorkspaceInputProperties</span></code> method, all access must be via the three methods mentioned above.</p>
</aside>
</aside>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="HandlingXML.html" title="Previous Chapter: Handling XML"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Handling XML</span>
</a>
</li>
<li>
<a href="IndirectDataAnalysisAddingFitType.html" title="Next Chapter: Adding a new fitting function to IDA"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Adding a new ... »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>