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.9.0.devel (Kenzo)
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
60 Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU
61 Lesser General Public License. For details, run `license`.
65 The final line, ``hooke>``, is the Hooke prompt. It allows you to
66 enter commands to interact with the interpreter.
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
78 Or see specific help on ``TOPIC`` with::
84 hooke> help load_playlist
86 will give help on the ``load_playlist`` command.
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).
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.
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.
107 You then can ``cd`` (change directory) to the directory::
109 hooke> cd --path c:\curves
111 Type ``pwd`` (print working directory) to check the directory is correct.::
116 You can list the files in the directory using ``ls`` or ``dir``
117 (they’re synonyms).::
124 Now you are ready to generate the playlist. First, create a blank playlist::
126 hooke> new_playlist --output_playlist mylist
128 Ensure that the new playlist is active::
130 hooke> jump_to_playlist -- -1
132 <FilePlaylist mylist>
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`_. You don't need to jump if
138 the new playlist is your only loaded playlist.
141 http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
143 .. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
145 "The first ``--`` argument that is not an option-argument should be
146 accepted as a delimiter indicating the end of options. Any
147 following arguments should be treated as operands, even if they
148 begin with the ``-`` character."
150 Then glob your curves onto the new list::
152 hooke> glob_curves_to_playlist mycurve.*
154 You can also be more specific with wildcards. For example::
156 hooke> glob_curve_to_playlist mycurve.05*
158 will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
160 Note that by using ``glob_curves_to_playlist`` you just generate the
161 playlist in the local session. To save your playlist to a file for
164 hooke> save_playlist --output mylist
166 In this example, the list will be saved in the file
167 :file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke
168 playlist) to the playlist if you forget to. The ``.hkp`` file is an
169 XML file you can read and edit with any text editor (i.e. Wordpad), if
170 needed. If you want to load it, simply issue ``load_playlist
171 mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
174 If, generating the playlist, you are including by chance a non-force
175 curve file that Hooke cannot open, Hooke will log a warning and
178 Navigating the playlist
179 -----------------------
181 Now you can navigate through your playlist using the commands
182 ``next_curve`` and ``previous_curve``. You don’t need to type
183 ``next_curve`` every time to run along a list of curves. You can
184 navigate through the command history by using the up and down arrows,
185 or auto-complete partial commands with TAB. From the last curve of
186 your playlist, ``next_curve`` will wrap around to the first curve.
187 Analogously, issuing ``previous_curve`` at the first curve will jump
190 You can also jump to a given curve::
192 hooke> jump_to_curve 14
194 will jump to the 14th curve in the playlist.
196 .. todo:: ``jump_to_curve <PATH>``, where the path can be either an
197 absolute path or a path relative to the directory holding the
203 You can take notes about the curves you are looking at. Just type
204 ``set_note`` followed by the text you want to attach to that curve.
205 Hooke will save the text in your current playlist and in an external
208 .. todo:: No external file yet. Is this important?
210 The output will look like this::
212 Notes taken at Sun Sep 17 20:42:07 2006
213 /home/cyclopia/work/tris/20060620a.041 | This is a note
214 /home/cyclopia/work/tris/20060620a.207 | This is another note
215 /home/cyclopia/work/tris/20060620a.286 | This is a third one
217 The log file name can be configured (:doc:`config`), but it defaults
218 to :file:`hooke.log`.
220 Usually curves you annotated are useful later. You can create a
221 playlist for only annotated curves with
223 hooke> note_filter_playlist --name c:\curves\nice.hkp
225 will create sub-playlist :file:`c:\curves\nice.hkp`. Make sure that
226 the target directory (here :file:`c:\curves\`) already exists before
229 If you change your mind about a note, you can remove it by setting a
230 blank note string with ``set_note ''``.
235 You can export Hooke curves as images and as text columns. To export
236 as images or text, use the ``export_block`` command. Supported
237 formats are PNG (Portable Network Graphic, raster) and EPS
238 (Encapsulated Postscript, vector). The export format is determined by
239 the filename extension, so ``export_block foo.png``, ``export_block
240 foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and
241 TAB-delimited text files respectively.
243 .. todo:: Multiple cycles in exported data? Solution: blank lines for
244 "breaks", add option to extract specific sections using Python's
247 If you don't want the entire block, try the ``cut`` command.
249 Interacting with the plot
250 -------------------------
252 (no plots in command line mode...)
254 Measuring distances and forces
255 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
257 You can move about the plot using its navigation toolbar. See the
258 `Matplotlib manual`_ for details.
260 .. _Matplotlib manual:
261 http://matplotlib.sourceforge.net/users/navigation_toolbar.html
263 You can measure distances and forces directly in the plot. Just issue
264 the command ``delta``. You will be asked to click two points. When
265 you click a point, a blue dot should appear. When you click the
266 second point, the distances will appear in the output panel. If you
267 want to know the coordinates of a single point, left click on it.
269 Hooke automatically adjusts the position of the clicked point to the
270 nearest point in the graph, so you will be always measuring distances
271 and forces between points in the graph.
273 Worm like chain and freely jointed chain fitting
274 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
276 You can measure by hand the parameters relative to a force peak using
277 a worm-like chain fitting with the ``fit`` command. The command by
278 default automatically finds the contact point, asks for two points
279 delimiting the portion to fit, and performs a two-variable fit, with
280 contour length, persistence length, and their relative errors as
281 output. If desired, one can use the ``noauto`` option to manually
282 click the contact point, and/or the ``pl=NUMBER`` options to impose a
283 specific persistence or Kuhn length (in nanometers). You can choose
284 which model to use with ``set fit_function wlc`` or ``set fit_function
285 fjc``. See the help of the ``fit`` command from the Hooke command
288 Multiple curve fitting and measuring
289 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
291 You can cycle through all your current playlist obtaining WLC fit, FJC
292 fit, rupture force and slope (loading rate) information from each
293 curve using the ``multifit`` command. The collected data can be saved
294 in a text file for further analysis in your favourite spreadsheet or
295 statistical program. If you want to check your parameters on the
296 current curve before fitting all the files in your playlist, use
297 ``multifit justone``. See the ``multifit`` help for more options.
299 Fast curve reviewing and saving
300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
302 When automatic routines are not good enough to filter your data, use
303 ``review`` command to cycle through your playlist presenting ten
304 curves in the same graph. You can then enter the numbers of the
305 interesting curves and automatically save a copy of them into another
311 You can set environment variables to influence the behaviour of
312 Hooke. The command to use is ``set_config``. Use ``get_config`` to
313 read a particular option and ``print_config`` to display the entire
314 configuration file. Any changes to the configuration will be saved
315 when you exit Hooke, see :doc:`config` for details.