5 `A short video showing Hooke in action`_! (courtesy of Fabrizio
6 Benedetti, EPFL, Lausanne)
8 .. _A short video showing Hooke in action:
9 https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv
19 This tutorial will focus on the command-line interface as the most
20 powerful, and leave the :doc:`gui` interface to another document.
22 .. _command-line: `Command-line interface`_
27 See :doc:`install` for details on downloading and installing Hooke.
30 Command-line interface
31 ======================
33 Running the hooke shell
34 -----------------------
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.::
42 If you are running hooke from the source directory (see
43 :doc:`install`), the equivalent command is::
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.
51 As Hooke launches, you should see something like the following in your
54 Hooke version 0.8.0 Seinei
60 The final line, ``hooke>``, is the Hooke prompt. It allows you to
61 enter commands to interact with the interpreter.
66 All commands have help text explaining their purpose and usage. The
67 text is stored in the code itself, and therefore more likely to be up
68 to date than this tutorial. You can get a list of commands and topics
73 Or see specific help on ``TOPIC`` with::
79 hooke> help load_playlist
81 will give help on the ``load_playlist`` command.
86 When you're done with an interactive Hooke session, you can close the
87 session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is
88 the end of the stdin stream, which is Ctrl-d in many shells).
93 To start analyzing your curves, you first have to build a playlist. The
94 playlist is just an index of the force curve files you want to
95 analyze. Imagine it as a music playlist (that’s why it is called a
96 playlist), but with data files instead of audio files.
98 Suppose you have 100 PicoForce curve files in your curves directory,
99 starting from :file:`mycurve.000` and ending in :file:`mycurve.100`
100 and you want to analyze them all.
102 You then can ``cd`` (change directory) to the directory::
104 hooke> cd --path c:\curves
106 Type ``pwd`` (print working directory) to check the directory is correct.::
111 You can list the files in the directory using ``ls`` or ``dir``
112 (they’re synonyms).::
119 Now you are ready to generate the playlist. The command to use is
120 ``glob_curves_to_playlist``.::
122 hooke> glob_curves_to_playlist mycurve.*
124 You can also be more specific with wildcards. For example
126 hooke> glob_curve_to_playlist mycurve.05*
128 will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
130 Note that by using ``glob_curve_to_playlist`` you just generate the
131 playlist in the local session. To save your playlist to a file for
134 hooke> save_playlist --output mylist
136 In this example, the list will be saved in the file
137 :file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke
138 playlist) to the playlist if you forget to. The ``.hkp`` file is an
139 XML file you can read and edit with any text editor (i.e. Wordpad), if
140 needed. If you want to load it, simply issue ``load_playlist
141 mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
144 If, generating the playlist, you are including by chance a non-force
145 curve file that Hooke cannot open, Hooke will print an error and
148 Navigating the playlist
149 -----------------------
151 Now you can navigate through your playlist using the commands
152 ``next_curve`` and ``previous_curve``. You don’t need to type
153 ``next_curve`` every time to run along a list of curves. You can
154 navigate through the command history by using the up and down arrows,
155 or auto-complete partial commands with TAB. From the last curve of
156 your playlist, ``next_curve`` will wrap around to the first curve.
157 Analogously, issuing ``previous_curve`` at the first curve will jump
160 You can also jump to a given curve::
162 hooke> jump_to_curve 14
164 will jump to the 14th curve in the playlist. TODO: jump_to_curve
165 <PATH>, where the path can be either an absolute path or a path
166 relative to the directory holding the playlist file.
171 You can take notes about the curves you are looking at. Just type
172 ``add_note`` followed by the text you want to append to that curve.
173 Hooke will save the text in your current playlist and in an external
174 log file (TODO: no external file yet. Is this important?). The
175 output will look like this::
177 Notes taken at Sun Sep 17 20:42:07 2006
178 /home/cyclopia/work/tris/20060620a.041 | This is a note
179 /home/cyclopia/work/tris/20060620a.207 | This is another note
180 /home/cyclopia/work/tris/20060620a.286 | This is a third one
182 The log file name can be configured (:doc:`config`), but it defaults
183 to :file:`hooke.log`.
185 Usually curves you annotated are useful later. You can create a
186 playlist for only annotated curves with
188 hooke> note_filter_playlist --name c:\curves\nice.hkp
190 will create sub-playlist :file:`c:\curves\nice.hkp`. Make sure that
191 the target directory (here :file:`c:\curves\`) already exists before
194 If you change your mind about a note, you can remove it with
200 You can export Hooke curves as images and as text columns. To export
201 as images or text, use the ``export_block`` command. Supported
202 formats are PNG (Portable Network Graphic, raster) and EPS
203 (Encapsulated Postscript, vector). The export format is determined by
204 the filename extension, so ``export_block foo.png``, ``export_block
205 foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and
206 TAB-delimited text files respectively.
208 TODO: multiple cycles? Solution: blank lines for "breaks", add option
209 to extract specific sections using Python's slice notation.
211 If you don't want the entire block, try the ``cut`` command.
213 Interacting with the plot
214 -------------------------
216 (no plots in command line mode...)
218 Measuring distances and forces
219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
221 You can easily zoom in the plot by dragging a rectangle on it with the
222 left mouse button. To zoom out, click the right mouse
223 button. Sometimes by zooming in and out too much, you can lose the
224 picture (this is probably a small bug in Matplotlib). Just type
225 ``plot`` at the command line and the curve will be refreshed.
227 You can measure distances and forces directly in the plot. Just issue
228 the command ``distance``. You will be asked to click two points.
229 When you click a point, a blue dot should appear. When you click the
230 second point, the distances (in nanometers and piconewtons) will
231 appear on the command line. You can use ``delta`` if you prefer,
232 which gives meaningful values for every kind of graph (not only force
233 curves). If you want to know the coordinates of a single point, use
236 Hooke automatically adjusts the position of the clicked point to the
237 nearest point in the graph, so you will be always measuring distances
238 and forces between points in the graph.
240 The commands ``force`` and ``distance`` are present in the
241 ``generalvclamp`` plugin.
243 Worm like chain and freely jointed chain fitting
244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
246 You can measure by hand the parameters relative to a force peak using
247 a worm-like chain fitting with the ``fit`` command. The command by
248 default automatically finds the contact point, asks for two points
249 delimiting the portion to fit, and performs a two-variable fit, with
250 contour length, persistence length, and their relative errors as
251 output. If desired, one can use the ``noauto`` option to manually
252 click the contact point, and/or the ``pl=NUMBER`` options to impose a
253 specific persistence or Kuhn length (in nanometers). You can choose
254 which model to use with ``set fit_function wlc`` or ``set fit_function
255 fjc``. See the help of the ``fit`` command from the Hooke command
258 Multiple curve fitting and measuring
259 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261 You can cycle through all your current playlist obtaining WLC fit, FJC
262 fit, rupture force and slope (loading rate) information from each
263 curve using the ``multifit`` command. The collected data can be saved
264 in a text file for further analysis in your favourite spreadsheet or
265 statistical program. If you want to check your parameters on the
266 current curve before fitting all the files in your playlist, use
267 ``multifit justone``. See the ``multifit`` help for more options.
269 Fast curve reviewing and saving
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
272 When automatic routines are not good enough to filter your data, use
273 ``review`` command to cycle through your playlist presenting ten
274 curves in the same graph. You can then enter the numbers of the
275 interesting curves and automatically save a copy of them into another
281 You can set environment variables to influence the behaviour of
282 Hooke. The command to use is ``set_config``.
284 You can alter permanently the behaviour of Hooke by setting these
285 variables in a Hooke configuration file. See :doc:`config` for