-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathQuick-Start-Existing-Scripts.html
473 lines (357 loc) · 18.3 KB
/
Quick-Start-Existing-Scripts.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
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="scripts/mystyles.css">
<script src="global_funcs.js" type="text/javascript"></script>
</head>
<body>
<div class="container-master">
<div class="container-full-width">
<header>
<h1>luaXroot Wiki</h1>
</header>
</div>
<div class="container-content">
<nav>
<iframe src="sidebar.html" style="border:none;" onload="SetSidebarHeight(this);"></iframe>
</nav>
<article>
<p>This section assume that you already have cloned, built and installed <b>luaXroot</b> using the <a href="https://github.com/zupalex/luaXroot#luaxroot">instructions provided by the README.md</a>.</p>
<h1 id="intro">Index of the Quick Start section:</h1>
<ul>
<li><h3><a href ="#the-command-interpreter">The command interpreter</a></h3></li>
<li><h3><a href ="#loading-a-script">Loading a script</a></h3></li>
<li><h3><a href ="#displaying-histograms-and-graphs">Displaying histograms and graphs</a></h3></li>
<li><h3><a href ="#graphical-cut">Graphical cut</a></h3></li>
<li><h3><a href ="#interacting-with-a-running-task">Interacting with a running task</a></h3></li>
<li><h3><a href ="#exiting-the-process">Exiting the process</a></h3></li>
</ul>
<hr>
<h2 id="the-command-interpreter">The command interpreter</h2>
<b>luaXroot</b> can be started very easily from anywhere (assuming you followed the few steps described in the
<a href="https://github.com/zupalex/luaXroot#luaxroot">instructions provided by the README.md</a>). To start it, simply type in the terminal</p>
<pre class="prettyprint">
luaXroot
</pre>
<p>This will start the Lua command interpreter, the background task loading the ROOT TApplication that will take care of the display events, and load and setup all the standard <b>luaXroot</b>
libraries and packages. You should see something like the following:</p>
<img src="images/luaXroot-startup.png" alt="luaXroot-startup" style="max-width:100%;">
<p>The command interpreter supports moving the prompt with the left and right arrow keys.</p>
<p><b>luaXroot</b> also offers a command history using the <a href="https://tiswww.case.edu/php/chet/readline/rltop.html">readline libraries</a>. The history can be navigated using the up and down arrow
keys.</p>
<p>Another useful feature is the autocompletion using the tab key. Similarly to a shell autocompletion, if the user starts to type a command and presses the Tab key, that command will be autocompleted if
only one match is found. If several commands match the user input, pressing Tab a second time will display the list of all possible commands.</p>
<p>The interpreter can be used to perform basic operations like additions, multiplications, bit masking, bit shifting, etc...</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> 5 + 9
14
> 3^2
6
> 15%4
3
</pre>
<p>The command interpreter also enables direct definition of functions. The Lua command interpreter evaluates each line and detects if a command is incomplete. In such case it offers a
double prompt on the next line to allow the user to finish the command:</p>
<img src="images/luaXroot-functiondef.png" alt="luaXroot-functiondef" style="max-width:100%;">
<hr>
<h2 id="loading-a-script">Loading a script</h2>
<p>Loading a script can be done in 2 different ways. The preferred way is to call <i>require</i>. The other way is to call <i>dofile</i>. More details
<a href="The-Lua-Scripting-Language.html#mods-and-packs">available here</a>.</p>
<h4>require</h4>
<p><i>require</i> will look for a script with the requested name in specific locations and try to load it. Scripts loaded this way are tracked and any subsequent calls to <i>require</i> the same
script won't load it again. This is the safest way to load a script but it requires that the script is placed in a location known by <b>luaXroot</b>. These known locations are by default</p>
<ul>
<li><i>< path/to/luaXroot ></i>/scripts</li>
<li><i>< path/to/luaXroot ></i>/scripts/lua_modules</li>
<li><i>< path/to/luaXroot ></i>/user</li>
</ul>
<p>The user should not add scripts in the first 2 paths. The \"user\" folder is here for that.</p>
<p>Additional libraries/module locations can be specified. This is <a href="Functionalities.html#the-userlogon">discussed here</a>.</p>
<pre class="prettyprint">
[ assuming we have a script MonitorTimeDrift.lua in a known location ]
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> require("MonitorTimeDrift")
</pre>
<h4>dofile</h4>
<p><i>dofile</i> will execute the script passed as an argument. Unlike <i>require</i>, <i>dofile</i> does not have any search location and it just uses the path given.</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> dofile("/home/evildrpain/luascripts/MonitorTimeDrift.lua")
</pre>
<p>It is also possible to specify a script or a command to execute on startup</p>
<pre class="prettyprint">
luaXroot "/home/evildrpain/luascripts/MonitorTimeDrift.lua"
</pre>
<p>In this case, the script is simply loaded by an automatic call to <i>dofile</i> once <b>luaXroot</b> has finished its startup tasks.</p>
<pre class="prettyprint">
luaXroot -l MonitorTimeDrift
</pre>
<p>In this case, the script is loaded by an automatic call to <i>require</i> once <b>luaXroot</b> has finished its startup tasks. It implies that the script has to be in one of <b>luaXroot</b> known
location.</p>
<pre class="prettyprint">
luaXroot -e "require('MonitorTimeDrift'); StartMonitoring();"
</pre>
<p>In this case, the command specified inside the quotation marks is executed once <b>luaXroot</b> has finish its startup tasks.</p>
<p><a href="#intro">go back to top</a></p>
<hr>
<h2 id="displaying-histograms-and-graphs">Displaying histograms and graphs</h2>
<p><b>luaXroot</b> provides "binders" to several ROOT classes, among which TGraphErrors, TH1D and TH2D. The full documentation for these binders can be <a href="ROOT-Libraries-Binders.html">found
here</a>.</p>
<p>TGraphErrors, are used to display graphs with or without error bars and are manipulated using the Lua binder <i>TGraph</i>.<br/>
1D and 2D histograms are handled by TH1D and TH2D objects. The Lua binders for these objects are <i>TH1</i> and <i>TH2</i>.</p>
<p>The examples below give the basic functionalities of these binders</p>
<p><b>Creating a graph and displaying it:</b></p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> gr = TGraph(5) <= the argument is the amount of points in our graph
>
> gr:SetPoint(1, 5, 7)
> gr:SetPoint(2, 8, 12)
> gr:SetPoint(3, 13, 24)
> gr:SetPoint(4, 15, 29)
> gr:SetPoint(5, 21, 38)
>
> gr:Draw("AP") <= "AP" are options requesting that the graph is display with points
>
</pre>
<img src="images/luaXroot-creategraph.png" alt="luaXroot-creategraph" style="max-width:100%;">
<p><a href="#intro">go back to top</a></p>
<p id="updating-a-canvas"><b>Updating canvas after a modification:</b></p>
<p>By default, a canvas will not reflect the latest changes unless clicked to trigger a refresh of the display. This is not a very convenient method to update a canvas when displaying a lot of
graphs/histograms at once. To effectively update an object or all the active canvases, the user can invoke <i>Update</i> or <i>theApp:Update()</i> respectively.</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
>
> h1 = TH1("test", "test hist", 10, 0, 10)
> h1:Fill(4)
>
> h2 = TH1("test2", "test hist 2", 10, 0, 10)
> h2:Fill(7)
>
> h1:Draw()
> h2:Draw()
>
> h1:Fill(3)
> h2:Fill(1) <= These changes will not be reflected on the displayed graph
>
> theApp:Update() <= All the histograms will be updated (here h1 and h2)
>
> h1:Fill(9)
> h2:Fill(8)
>
> h1:Update() <= Only h1 will be updated and show 3 counts. h2 will still show 2 counts
>
</pre>
<p><a href="#intro">go back to top</a></p>
<p><b>Dividing a canvas into sub-canvases:</b></p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> can = TCanvas()
>
> h1 = TH1("test", "test hist", 10, 0, 10)
> h1:Fill(4)
>
> h2 = TH1("test2", "test hist 2", 10, 0, 10)
> h2:Fill(7)
>
> can:Divide(1, 2) <= Divides the canvas into 1 row and 2 columns
>
> can:Draw(h1, "", 1, 1)
> can:Draw(h2, "", 1, 2)
>
</pre>
<img src="images/luaXroot-canvasdivide.png" alt="luaXroot-canvasdivide" style="max-width:100%;">
<p>Double clicking on a sub-canvas clones and opens it in a new canvas, allowing to display it bigger. Please note that this cloned canvas won't get updated if the original canvas gets modified. In this
case, the user would need to close the clone and open a new one.</p>
<p><a href="#intro">go back to top</a></p>
<p><b>Zooming or changing the binning:</b></p>
<p>First, let's enable the "editor"</p>
<img src="images/luaXroot-enableeditor.gif" alt="luaXroot-enableeditor" style="max-width:100%;">
<p>Toggling log/linear scale</p>
<img src="images/luaXroot-logscale.gif" alt="luaXroot-logscale" style="max-width:100%;">
<p>Rebinning the histogram</p>
<img src="images/luaXroot-rebin.gif" alt="luaXroot-rebin" style="max-width:100%;">
<p>Zooming on the X or Y axis</p>
<img src="images/luaXroot-zoom.gif" alt="luaXroot-zoom" style="max-width:100%;">
<p><a href="#intro">go back to top</a></p>
<p><b>Fitting a graph:</b></p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> gr = TGraph(5)
>
> gr:SetPoint(1, 5, 7)
> gr:SetPoint(2, 8, 12)
> gr:SetPoint(3, 13, 24)
> gr:SetPoint(4, 15, 29)
> gr:SetPoint(5, 21, 38)
>
> gr:Draw("AP")
>
> poly1 = function(x, a, b)
>> return a*x+b
>> end
>
> fitfunc = TF1("fitfunc", poly1, 0, 30, 2)
>
> gr:Fit({fn=fitfunc})
>
</pre>
<img src="images/luaXroot-fitgraph.png" alt="luaXroot-fitgraph" style="max-width:100%;">
<p>In this example the function is defined in the Lua interpreter. This is not the most efficient way to do things though. It would be better to define that function in a script loaded at launch.<br/>
Please also note that the commonly used functions are already defined. They can be accessed using their names:</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
> gr = TGraph(5)
>
> gr:SetPoint(1, 5, 7)
> gr:SetPoint(2, 8, 12)
> gr:SetPoint(3, 13, 24)
> gr:SetPoint(4, 15, 29)
> gr:SetPoint(5, 21, 38)
>
> gr:Draw("AP")
>
> fitfunc = TF1("fitfunc", "pol1", 0, 30, 2)
>
> gr:Fit({fn=fitfunc})
>
</pre>
<p>The names for polynomial functions are simply "poln" where <i>n</i> has to be replaced by the order of the polynome.<br/>
The name for a gaussian function is "gauss".</p>
<p><a href="#intro">go back to top</a></p>
<hr>
<h2 id="graphical-cut">Graphical cuts</h2>
<p>It is often useful to create a selection from a 2D plot and use it to constrain the data used to populate a histogram. ROOT provides a class for this type of operations: TCutG.<br/>
The user will interact with this ROOT class using the <b>luaXroot</b> binder with the same name <a href="ROOT-Libraries-Binders.html#tcutg"><i>TCutG</i></a>.</p>
<p>Graphical cut can be drawn directly on a 2D histogram and saved in a file. The step-by-step process is shown in the GIF below. The commands used in the interpreter to retrieve the cut after draing it
are given below the GIF.</p>
<img src="images/luaXroot-graphicalcut.gif" alt="luaXroot-graphicalcut" style="max-width:100%;">
<p>This cut can be saved to a file:</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
>
[ ... do stuffs to produce some histograms ... ]
> h_123456_resisitive_3:Draw("colz") <= When drawing a 2D histogram, specify "colz" to plot it with colors
>
> cut1 = GetObject("TCutG", "lower_band")
>
> cutfile = TFile("mycuts.root", "recreate")
>
> cut1:Write()
>
> cutfile:Close()
>
</pre>
<p>This cut can later be retrieved in a script or using the command line:</p>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
>
> file = TFile("mycuts.root", "read")
>
> cut1 = file:GetObject("TCutG", "lower_band")
>
</pre>
<p>If the user wants to fill a histogram with values <i>val</i> only when <i>x</i> and <i>y</i> are inside this cut, simply check</p>
<pre class="prettyprint">
-- [ ... assuming a histogram <i>hist</i> has been defined earlier in the script ... ]
if cut1:IsInside(x, y) then
hist:Fill(val)
end
</pre>
<p><a href="#intro">go back to top</a></p>
<hr>
<h2 id="interacting-with-a-running-task">Interacting with a running task</h2>
<p>Often the user will want to start a task without losing the ability the interact with the <b>luaXroot</b> session and would rather run it in the background instead.
For this instance, the helper function <a href="Helper-Functions#startnewtask"><i>StartNewTask</i></a> can be used to create a new thread that will run the requested task in the background while the
user can still interact with the Lua command prompt to perform other operations. To interact with a running task, the user should call <a href="Helper-Functions#sendsignal"><i>SendSignal</i></a>
with an appropriate signal.</p>
<p>By default, 3 signals will always be implemented when starting a new task:</p>
<ul>
<li><b>wait</b> signal will pause the execution of the task.</li>
<li><b>resume</b> signal will resume the execution of a paused task.</li>
<li><b>stop</b> signal will terminate the execution of the task.</li>
</ul>
<p>More signals can be implemented with <a href="Helper-Functions#addsignal"><i>AddSignal</i></a> and any script might implement additional signals with their own functionalities.</p>
<pre class="prettyprint">
-- This is in a user script called "monitor_sx3.lua"
--
-- [ ... assuming we loaded a script implementing a signal "Display" ... ]
function MonitorSX3(sx3_ids)
-- [ ... do stuffs in this function to monitor the energy gathered by the
-- SuperX3 detectors with IDs matching the ones provided in the table sx3_ids ]
-- we will fill histograms with the names "h_sx3_X" where the last X is the SuperX3 ID.
end
-- This function will start a new background task to monitor SuperX3 number 0, 1, 5, 12 and 19
StartNewTask("task1", "Monitor", { 0, 1, 5, 12, 19 })
</pre>
<pre class="prettyprint">
Lua 5.3.4 Copyright (C) 1994-2017 Lua.org, PUC-Rio
ROOT 6.11/03 http://root.cern.ch The ROOT Team
luaXroot https://github.com/zupalex/luaXroot Alexandre Lepailleur ([email protected])
------------------------------------------------------------------------------------------------
>
> dofile("./monitor_sx3.lua") <= the <i>Monitor</i> function is running in the background.
Our script is done and we now return to interpreter mode.
>
> SendSignal("task1", "Display", "h_sx3_12") <= This line send a signal to the background task
requesting the display of the histogram h_sx3_12
>
> SendSignal("task1", "wait") <= The execution of task1 is now paused
>
[ ... The user can perform operations here ... ]
>
> SendSignal("task1", "resume") <= task1 is resumed
>
> SendSignal("task1", "stop") <= task1 is stopped. It cannot receive any other signal after this point.
</pre>
<p><a href="#intro">go back to top</a></p>
<hr>
<h2 id="exiting-the-process">Exiting the process</h2>
<p>To exit <b>luaXroot</b> the user can either.</p>
<ul>
<li>type <i>q()</i> or <i>exit()</i>. This makes sure that the clean-up tasks are triggered.</li>
<li>issue a CTRL+C input. This method is not very elegant but should still trigger the clean-up tasks.</p>
</ul>
<p>The first method is the prefered one. The second method should be called only when stuck in a loop or if calling <i>q()</i> or <i>exit()</i> is not possible.</li></p>
<p><a href="#intro">go back to top</a></p>
<hr>
</article>
</div>
<div class="container-full-width">
<footer><a href="https://github.com/zupalex/luaXroot">https://github.com/zupalex/luaXroot</a></footer>
</div>
</div>
<script src="https://cdn.rawgit.com/google/code-prettify/master/loader/run_prettify.js"></script>
</body>
</html>