8f68f90ce1509f79e9368c65828e8d6a1b636169
[hooke.git] / doc / tutorial.txt
1 ********
2 Tutorial
3 ********
4
5 `A short video showing Hooke in action`_! (courtesy of Fabrizio
6 Benedetti, EPFL, Lausanne)
7
8 .. _A short video showing Hooke in action:
9   https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv
10
11 .. toctree::
12    :maxdepth: 2
13
14    gui.txt
15
16 Introduction
17 ============
18
19 This tutorial will focus on the command-line interface as the most
20 powerful, and leave the GUI interface to another document.
21
22 .. _command-line: `Command-line interface`_
23 .. _GUI: gui.txt
24
25 Installation
26 ============
27
28 See the Installation_ page for details on downloading and installing
29 Hooke.
30
31 .. _Installation: install.txt
32
33
34 Command-line interface
35 ======================
36
37 Running the hooke shell
38 -----------------------
39
40 Hooke has a set of commands that depend on the loaded plugins_.
41 To access these commands, you'll need to run the Hooke shell.::
42
43     $ hooke
44
45 If you are running hooke from the source directory (see
46 Installation_), the equivalent command is::
47
48     $ python bin/hooke
49
50 You may need to give the full path for Python on Windows systems.
51
52 .. _plugins: hooke/hooke.plugin.txt
53
54 As Hooke launches, you should see something like the following in your
55 terminal::
56
57     Starting Hooke.
58     Imported plugin fit
59     Imported plugin procplots
60     Imported plugin flatfilts
61     Imported plugin generalclamp
62     Imported plugin generalvclamp
63     Imported plugin massanalysis
64     Imported plugin macro
65     Imported driver picoforce
66     Imported driver hemingclamp
67     Imported driver csvdriver
68     Imported driver tutorialdriver
69     
70     Warning: Invalid work directory.
71     This is Hooke, version 0.8.0 Seinei
72     (c) Massimo Sandal, 2006. Released under the GNU General Public License Version 2
73     Hooke is Free software.
74     ----
75     hooke>
76
77 The final line, ``hooke>``, is the Hooke prompt.  It allows you to
78 enter commans to interact with the interpreter.
79
80 Help
81 ----
82
83 All commands have help text explaining their purpose and usage.  The
84 text is stored in the code itself, and therefore more likely to be up
85 to date than this tutorial.  You can get a list of commands and topics
86 with::
87
88     hooke> help
89
90 Or see specific help on ``TOPIC`` with::
91
92     hooke> help TOPIC
93
94 for example::
95
96     hooke> help current
97
98 will give help on the ``current`` command.
99
100 Creating a playlist
101 -------------------
102
103 To start analyzing your curves, you first have to build a playlist. The
104 playlist is just an index of the force curve files you want to
105 analyze. Imagine it as a music playlist (that’s why it is called a
106 playlist), but with data files instead of audio files.
107
108 Suppose you have 100 PicoForce curve files in your curves directory,
109 starting from ``mycurve.000`` and ending in ``mycurve.100`` and you
110 want to analyze them all.
111
112 You then can ``cd`` (change directory) to the directory::
113
114     hooke> cd c:\curves
115
116 Type ``pwd`` (print working directory) to check the directory is correct.::
117
118       hooke> pwd
119       c:\curves
120
121 You can list the files in the directory using ``ls`` or ``dir`` (they’re
122 synonyms).::
123
124     hooke> ls
125     [’mycurve.000’, ’mycurve.001’, ...
126     ]
127
128 Now you are ready to generate the playlist. The command to use is
129 ``genlist``.::
130
131     hooke> genlist mycurve.*
132
133 You can also generate a playlist containing all what you find in the
134 directory by typing:
135
136     hooke> genlist c:\curves
137
138 If you want to select what curves to see, based on the filename, you
139 can use wildcards.  For example::
140
141     hooke> genlist mycurve.05*
142
143 will take only curves from mycurve.050 to mycurve.059.
144
145 Note that by using ``genlist`` you just generate the playlist in the
146 local session. To save your playlist to a file for future reuse,
147 type::
148
149     hooke> savelist mylist
150
151 In this example, the list will be saved in the file ``mylist.hkp``.
152 Hooke will add the extension ``.hkp`` (Hooke playlist) to the playlist
153 if you forget to.  The ``.hkp`` file is an XML file you can read and
154 edit with any text editor (i.e. Wordpad), if needed.  If you want to
155 load it, simply issue ``loadlist mylist.hkp`` or ``loadlist mylist``,
156 Hooke will add ``.hkp`` if necessary.
157
158 If, generating the playlist, you are including by chance a non-force
159 curve file that Hooke cannot open, Hooke will print an error and
160 continue on.
161
162 Navigating the playlist
163 -----------------------
164
165 Now you can navigate through your playlist using the commands ``next``
166 and ``previous`` or, their aliases ``n`` and ``p``. You don’t need to
167 type ``n`` every time to run along a list of curves.  If you press
168 Return to an empty prompt, Hooke will repeat the last command you
169 issued explicitly.  You can also navigate through the command history
170 by using the up and down arrows.  From the last curve of your
171 playlist, ``n`` will wrap around to the first curve.  Analogously,
172 issuing ``p`` at the first curve will jump to the last.
173
174 You can also jump to a given curve::
175
176     hooke> jump c:\curves\mycurve.012
177
178 where the path can be either an absolute path, or a path relative to
179 the directory holding the playlist file.
180
181 Taking notes
182 ------------
183
184 You can take notes about the curves you are looking at.  Just type
185 ``note`` followed by the text you want to append to that curve.  Hooke
186 will save the text in your current playlist and in an external log
187 file.  The output will look like this:
188
189 Notes taken at Sun Sep 17 20:42:07 2006
190 /home/cyclopia/work/tris/20060620a.041 |             This is a note
191 /home/cyclopia/work/tris/20060620a.207 |             This is another note
192 /home/cyclopia/work/tris/20060620a.286 |             This is a third one
193
194 The log file name can be configured_, but it defaults to hooke.log.
195
196 .. _configured: config.txt
197
198 Usually curves you annotated are useful later.  You can copy the curves
199 you annotated to a different directory by using the ``copylog``
200 command.
201
202     hooke> copylog c:\nicecurves
203
204 will copy all curves you have annotated to the c:\nicecurves
205 directory.  Make sure that the directory already exists before doing
206 that.  TODO: replace with::
207
208     hooke> copylist --log c:\curves\nice.hkp
209
210 Exporting curves
211 ----------------
212
213 You can export Hooke curves as images and as text columns. To export
214 as images, issue the ``export`` command followed by the filename.
215 Supported formats are PNG (raster) and EPS (Encapsulated Postscript,
216 vectorial).  The export format is determined by the filename
217 extension, so ``export foo.png`` and ``export foo.eps`` will save
218 PNG and EPS files respectively.
219
220 To export as text, use the ``txt`` command, followed by the
221 filename. The output is a text file containing columns (first two are
222 X and Y of extension, second two are X and Y of retraction).
223
224 TODO: multiple cycles?  Solution: blank lines for "breaks", add option
225 to extract specific sections using Python's slice notation.
226
227
228 Interacting with the plot
229 -------------------------
230
231 (no plots in command line mode...)
232
233 Measuring distances and forces
234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235
236 You can easily zoom in the plot by dragging a rectangle on it with the
237 left mouse button.  To zoom out, click the right mouse
238 button. Sometimes by zooming in and out too much, you can lose the
239 picture (this is probably a small bug in Matplotlib).  Just type
240 ``plot`` at the command line and the curve will be refreshed.
241
242 You can measure distances and forces directly in the plot. Just issue
243 the command ``distance``.  You will be asked to click two points.
244 When you click a point, a blue dot should appear.  When you click the
245 second point, the distances (in nanometers and piconewtons) will
246 appear on the command line.  You can use ``delta`` if you prefer,
247 which gives meaningful values for every kind of graph (not only force
248 curves). If you want to know the coordinates of a single point, use
249 ``point``.
250
251 Hooke automatically adjusts the position of the clicked point to the
252 nearest point in the graph, so you will be always measuring distances
253 and forces between points in the graph.
254
255 The commands ``force`` and ``distance`` are present in the
256 ``generalvclamp`` plugin.
257
258 Worm like chain and freely jointed chain fitting
259 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260
261 You can measure by hand the parameters relative to a force peak using
262 a worm-like chain fitting with the ``fit`` command.  The command by
263 default automatically finds the contact point, asks for two points
264 delimiting the portion to fit, and performs a two-variable fit, with
265 contour length, persistence length, and their relative errors as
266 output.  If desired, one can use the ``noauto`` option to manually
267 click the contact point, and/or the ``pl=NUMBER`` options to impose a
268 specific persistence or Kuhn length (in nanometers). You can choose
269 which model to use with ``set fit_function wlc`` or ``set fit_function
270 fjc``.  See the help of the ``fit`` command from the Hooke
271 command line for details.
272
273 Multiple curve fitting and measuring
274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
275
276 You can cycle through all your current playlist obtaining WLC fit, FJC
277 fit, rupture force and slope (loading rate) information from each
278 curve using the ``multifit`` command.  The collected data can be saved
279 in a text file for further analysis in your favourite spreadsheet or
280 statistical program.  If you want to check your parameters on the
281 current curve before fitting all the files in your playlist, use
282 ``multifit justone``.  See the ``multifit`` help for more options.
283
284 Fast curve reviewing and saving
285 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286
287 When automatic routines are not good enough to filter your data, use
288 ``review`` command to cycle through your playlist presenting ten
289 curves in the same graph.  You can then enter the numbers of the
290 interesting curves and automatically save a copy of them into another
291 directory.
292
293 Configuring Hooke
294 -----------------
295
296 You can set environment variables to influence the behaviour of
297 Hooke. The command to use is ``set``.
298
299 You can alter permanently the behaviour of Hooke by setting these
300 variables in a Hooke configuration file.  See the `Configuring Hooke`_
301 section for details.
302
303 .. _Configuring Hooke: config.txt