bea22824b52cb02be324299fcafa8c1ab23ac89e
[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
15
16 Introduction
17 ============
18
19 This tutorial will focus on the command-line interface as the most
20 powerful, and leave the :doc:`gui` interface to another document.
21
22 .. _command-line: `Command-line interface`_
23
24 Installation
25 ============
26
27 See :doc:`install` for details on downloading and installing Hooke.
28
29
30 Command-line interface
31 ======================
32
33 Running the hooke shell
34 -----------------------
35
36 Hooke has a set of commands that depend on the loaded
37 :class:`hooke.plugin.Plugin`\s.  To access these commands, you'll need
38 to run the Hooke shell.::
39
40     $ hooke
41
42 If you are running hooke from the source directory (see
43 :doc:`install`), the equivalent command is::
44
45     $ python bin/hooke
46
47 You may need to give the full path for Python on Windows systems, and
48 also check that the current working directory (`.`) is in your
49 `PYTHONPATH`.  See :manpage:`python(1)` for details.
50
51 As Hooke launches, you should see something like the following in your
52 terminal::
53
54     Hooke version 0.9.0.devel (Kenzo)
55
56     Copyright (C) 2006-2010 A. Seeholzer, Alberto Gomez-Casado, Allen
57     Chen, Fabrizio Benedetti, Francesco Musiani, Marco Brucale, Massimo
58     Sandal, Pancaldi Paolo, Richard Naud, Rolf Schmidt, W. Trevor King
59
60     Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU
61     Lesser General Public License.  For details, run `license`.
62     ----
63     hooke>
64
65 The final line, ``hooke>``, is the Hooke prompt.  It allows you to
66 enter commands to interact with the interpreter.
67
68 Help
69 ----
70
71 All commands have help text explaining their purpose and usage.  The
72 text is stored in the code itself, and therefore more likely to be up
73 to date than this tutorial.  You can get a list of commands and topics
74 with::
75
76     hooke> help
77
78 Or see specific help on ``TOPIC`` with::
79
80     hooke> help TOPIC
81
82 for example::
83
84     hooke> help load_playlist
85
86 will give help on the ``load_playlist`` command.
87
88 Leaving Hooke
89 -------------
90
91 When you're done with an interactive Hooke session, you can close the
92 session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is
93 the end of the stdin stream, which is Ctrl-d in many shells).
94
95 Creating a playlist
96 -------------------
97
98 To start analyzing your curves, you first have to build a playlist. The
99 playlist is just an index of the force curve files you want to
100 analyze. Imagine it as a music playlist (that’s why it is called a
101 playlist), but with data files instead of audio files.
102
103 Suppose you have 100 PicoForce curve files in your curves directory,
104 starting from :file:`mycurve.000` and ending in :file:`mycurve.100`
105 and you want to analyze them all.
106
107 You then can ``cd`` (change directory) to the directory::
108
109     hooke> cd --path c:\curves
110
111 Type ``pwd`` (print working directory) to check the directory is correct.::
112
113     hooke> pwd
114     c:\curves
115
116 You can list the files in the directory using ``ls`` or ``dir``
117 (they’re synonyms).::
118
119     hooke> ls
120     mycurve.000
121     mycurve.001
122     ...
123
124 Now you are ready to generate the playlist.  First, create a blank playlist::
125
126     hooke> new_playlist --name mylist
127
128 Ensure that the new playlist is active::
129
130     hooke> jump_to_playlist -- -1
131     hooke> get_playlist
132     <FilePlaylist mylist>
133
134 The ``--`` in the ``jump_to_playlist`` command lets
135 ``jump_to_playlist`` know that ``-1`` is an argument and not an
136 option.  Using the bare ``--`` is a POSIX specification [#POSIX]_
137 supported by the `optparse module`_.
138
139 .. _optparse module:
140   http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
141
142 .. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
143
144     "The first ``--`` argument that is not an option-argument should be
145     accepted as a delimiter indicating the end of options. Any
146     following arguments should be treated as operands, even if they
147     begin with the ``-`` character."
148
149 Then glob your curves onto the new list::
150
151     hooke> glob_curves_to_playlist mycurve.*
152
153 You can also be more specific with wildcards.  For example::
154
155     hooke> glob_curve_to_playlist mycurve.05*
156
157 will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
158
159 Note that by using ``glob_curves_to_playlist`` you just generate the
160 playlist in the local session. To save your playlist to a file for
161 future reuse, type::
162
163     hooke> save_playlist --output mylist
164
165 In this example, the list will be saved in the file
166 :file:`mylist.hkp`.  Hooke will add the extension ``.hkp`` (Hooke
167 playlist) to the playlist if you forget to.  The ``.hkp`` file is an
168 XML file you can read and edit with any text editor (i.e. Wordpad), if
169 needed.  If you want to load it, simply issue ``load_playlist
170 mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
171 necessary.
172
173 If, generating the playlist, you are including by chance a non-force
174 curve file that Hooke cannot open, Hooke will print an error and
175 continue on.
176
177 Navigating the playlist
178 -----------------------
179
180 Now you can navigate through your playlist using the commands
181 ``next_curve`` and ``previous_curve``. You don’t need to type
182 ``next_curve`` every time to run along a list of curves.  You can
183 navigate through the command history by using the up and down arrows,
184 or auto-complete partial commands with TAB.  From the last curve of
185 your playlist, ``next_curve`` will wrap around to the first curve.
186 Analogously, issuing ``previous_curve`` at the first curve will jump
187 to the last.
188
189 You can also jump to a given curve::
190
191     hooke> jump_to_curve 14
192
193 will jump to the 14th curve in the playlist.  TODO: jump_to_curve
194 <PATH>, where the path can be either an absolute path or a path
195 relative to the directory holding the playlist file.
196
197 Taking notes
198 ------------
199
200 You can take notes about the curves you are looking at.  Just type
201 ``set_note`` followed by the text you want to attach to that curve.
202 Hooke will save the text in your current playlist and in an external
203 log file (TODO: no external file yet.  Is this important?).  The
204 output will look like this::
205
206     Notes taken at Sun Sep 17 20:42:07 2006
207     /home/cyclopia/work/tris/20060620a.041 | This is a note
208     /home/cyclopia/work/tris/20060620a.207 | This is another note
209     /home/cyclopia/work/tris/20060620a.286 | This is a third one
210
211 The log file name can be configured (:doc:`config`), but it defaults
212 to :file:`hooke.log`.
213
214 Usually curves you annotated are useful later.  You can create a
215 playlist for only annotated curves with
216
217     hooke> note_filter_playlist --name c:\curves\nice.hkp
218
219 will create sub-playlist :file:`c:\curves\nice.hkp`.  Make sure that
220 the target directory (here :file:`c:\curves\`) already exists before
221 doing that.
222
223 If you change your mind about a note, you can remove it by setting a
224 blank note string with ``set_note ''``.
225
226 Exporting curves
227 ----------------
228
229 You can export Hooke curves as images and as text columns. To export
230 as images or text, use the ``export_block`` command.  Supported
231 formats are PNG (Portable Network Graphic, raster) and EPS
232 (Encapsulated Postscript, vector).  The export format is determined by
233 the filename extension, so ``export_block foo.png``, ``export_block
234 foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and
235 TAB-delimited text files respectively.
236
237 TODO: multiple cycles?  Solution: blank lines for "breaks", add option
238 to extract specific sections using Python's slice notation.
239
240 If you don't want the entire block, try the ``cut`` command.
241
242 Interacting with the plot
243 -------------------------
244
245 (no plots in command line mode...)
246
247 Measuring distances and forces
248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
249
250 You can move about the plot using its navigation toolbar.  See the
251 `Matplotlib manual`_ for details.
252
253 .. _Matplotlib manual:
254   http://matplotlib.sourceforge.net/users/navigation_toolbar.html
255
256 You can measure distances and forces directly in the plot. Just issue
257 the command ``delta``.  You will be asked to click two points.  When
258 you click a point, a blue dot should appear.  When you click the
259 second point, the distances will appear in the output panel.  If you
260 want to know the coordinates of a single point, left click on it.
261
262 Hooke automatically adjusts the position of the clicked point to the
263 nearest point in the graph, so you will be always measuring distances
264 and forces between points in the graph.
265
266 Worm like chain and freely jointed chain fitting
267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
268
269 You can measure by hand the parameters relative to a force peak using
270 a worm-like chain fitting with the ``fit`` command.  The command by
271 default automatically finds the contact point, asks for two points
272 delimiting the portion to fit, and performs a two-variable fit, with
273 contour length, persistence length, and their relative errors as
274 output.  If desired, one can use the ``noauto`` option to manually
275 click the contact point, and/or the ``pl=NUMBER`` options to impose a
276 specific persistence or Kuhn length (in nanometers). You can choose
277 which model to use with ``set fit_function wlc`` or ``set fit_function
278 fjc``.  See the help of the ``fit`` command from the Hooke command
279 line for details.
280
281 Multiple curve fitting and measuring
282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
283
284 You can cycle through all your current playlist obtaining WLC fit, FJC
285 fit, rupture force and slope (loading rate) information from each
286 curve using the ``multifit`` command.  The collected data can be saved
287 in a text file for further analysis in your favourite spreadsheet or
288 statistical program.  If you want to check your parameters on the
289 current curve before fitting all the files in your playlist, use
290 ``multifit justone``.  See the ``multifit`` help for more options.
291
292 Fast curve reviewing and saving
293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294
295 When automatic routines are not good enough to filter your data, use
296 ``review`` command to cycle through your playlist presenting ten
297 curves in the same graph.  You can then enter the numbers of the
298 interesting curves and automatically save a copy of them into another
299 directory.
300
301 Configuring Hooke
302 -----------------
303
304 You can set environment variables to influence the behaviour of
305 Hooke. The command to use is ``set_config``.  Use ``get_config`` to
306 read a particular option and ``print_config`` to display the entire
307 configuration file.  Any changes to the configuration will be saved
308 when you exit Hooke, see :doc:`config` for details.