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.
99 The 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 Hooke parses it's commandline using `POSIX rules`_, so you need to
112 quote arguments with backslashes to keep them from being expanded as
113 escape sequences (e.g. ``\t`` → ``TAB``).
115 Type ``pwd`` (print working directory) to check the directory is
121 .. _POSIX rules: http://docs.python.org/library/shlex#parsing-rules
123 You can list the files in the directory using ``ls`` or ``dir``
124 (they’re synonyms).::
131 Now you are ready to generate the playlist. First, create a blank playlist::
133 hooke> new_playlist --output_playlist mylist
135 Ensure that the new playlist is active::
137 hooke> jump_to_playlist -- -1
139 <FilePlaylist mylist>
141 The ``--`` in the ``jump_to_playlist`` command lets
142 ``jump_to_playlist`` know that ``-1`` is an argument and not an
143 option. Using the bare ``--`` is a POSIX specification [#POSIX]_
144 supported by the `optparse module`_. You don't need to jump if
145 the new playlist is your only loaded playlist.
148 http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
150 .. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
152 "The first ``--`` argument that is not an option-argument should be
153 accepted as a delimiter indicating the end of options. Any
154 following arguments should be treated as operands, even if they
155 begin with the ``-`` character."
157 Then glob your curves onto the new list::
159 hooke> glob_curves_to_playlist mycurve.*
161 You can also be more specific with wildcards. For example::
163 hooke> glob_curve_to_playlist mycurve.05*
165 will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
167 Note that by using ``glob_curves_to_playlist`` you just generate the
168 playlist in the local session. To save your playlist to a file for
171 hooke> save_playlist --output mylist
173 In this example, the list will be saved in the file
174 :file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke
175 playlist) to the playlist if you forget to. The ``.hkp`` file is an
176 XML file you can read and edit with any text editor (i.e. Wordpad), if
177 needed. If you want to load it, simply issue ``load_playlist
178 mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
181 If, generating the playlist, you are including by chance a non-force
182 curve file that Hooke cannot open, Hooke will log a warning and
185 Navigating the playlist
186 -----------------------
188 Now you can navigate through your playlist using the commands
189 ``next_curve`` and ``previous_curve``. You don’t need to type
190 ``next_curve`` every time to run along a list of curves. You can
191 navigate through the command history by using the up and down arrows,
192 or auto-complete partial commands with TAB. From the last curve of
193 your playlist, ``next_curve`` will wrap around to the first curve.
194 Analogously, issuing ``previous_curve`` at the first curve will jump
197 You can also jump to a given curve::
199 hooke> jump_to_curve 14
201 will jump to the 14th curve in the zero-indexed playlist.
203 .. todo:: ``jump_to_curve <PATH>``, where the path can be either an
204 absolute path or a path relative to the directory holding the
207 Replace ``curve`` with ``playlist`` in the above commands to navigate
208 around through the list of loaded playlists.
210 Because the playlist name is usually saved in the playlist file
211 itself, there is a ``name_playlist`` command that allows you to rename
212 playlists on the fly.
214 hooke> name_playlist 'my old playlist'
219 You can take notes about the curves you are looking at. Just type
220 ``set_note`` followed by the text you want to attach to that curve.
221 Hooke will save the text in your current playlist and in an external
224 .. todo:: No external file yet. Is this important?
226 The output will look like this::
228 Notes taken at Sun Sep 17 20:42:07 2006
229 /home/cyclopia/work/tris/20060620a.041 | This is a note
230 /home/cyclopia/work/tris/20060620a.207 | This is another note
231 /home/cyclopia/work/tris/20060620a.286 | This is a third one
233 The log file name can be configured (:doc:`config`), but it defaults
234 to :file:`hooke.log`.
236 Usually curves you annotated are useful later. You can create a
237 playlist for only annotated curves with
239 hooke> note_filter_playlist --output_playlist nice_list
241 will create sub-playlist `nice_list`. Remember to save the new list
244 If you change your mind about a note, you can remove it by setting a
245 blank note string with ``set_note ''``.
250 You can export Hooke curves as images and as text columns. To export
251 as images or text, use the ``export_block`` command. Supported
252 formats are PNG (Portable Network Graphic, raster) and EPS
253 (Encapsulated Postscript, vector). The export format is determined by
254 the filename extension, so ``export_block --output foo.png``,
255 ``export_block --output foo.eps``, and ``export_block --output
256 foo.txt`` will save PNG, EPS, and TAB-delimited text files
259 .. todo:: Currently no PNG or EPS output, use the GUI and the plot
260 panel's toolbar for non-text exports.
262 .. todo:: Multiple cycles in exported data? Solution: blank lines for
263 "breaks", add option to extract specific sections using Python's
266 If you don't want the entire block, try the ``cut`` command.
271 The commands we have covered so far allow basic bookkeeping. The
272 point of Hooke, though, is to allow you to easily analyze force
273 spectroscopy data. We cover those analysis commands in this section.
275 Measuring distances and forces
276 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
278 To measure the distance between points, use the ``delta`` command.
283 will measure the distance between the 300th point and the 500th point.
284 One difficulty with the command line interface is that is difficult
285 to know which points you're interested without seeing the plot. The
286 two ways around this are:
288 1) Export the block (with ``export_block``), and graph the exported
289 file with a program of your choice (e.g. Gnuplot_). Use the
290 resulting graph to determine the indices of the points you are
292 2) Run Hooke's GUI instead of the command line when you need to make
293 manual measurements. See :doc:`gui` for details.
295 .. _Gnuplot: http://gnuplot.sourceforge.net/
297 Worm like chain and freely jointed chain fitting
298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
300 Polymer model fitting is a complicated beast. To correctly fit your
301 chosen model (WLC, FJC, etc.), you need to execute a multi-step
302 analysis. Hooke provides a flexible chain of curve analyisis commands
303 that create new data columns (e.g. `deflection (N)`) or store
304 information in a curve's `info` dictionary (e.g. `flat filter peaks`).
305 You can, if necessary, adjust the names of input and output columns
306 and `info` values to combine the available commands in new and useful
309 hooke> zero_surface_contact_point --block retract
310 hooke> flat_filter_peaks --block retract --min_points 1
311 hooke> zero_surface_contact_point --block retract
312 ... --ignore_after_last_peak_info_name 'flat filter peaks'
313 hooke> convert_distance_to_force --block retract
314 ... --deflection_column 'surface deflection (m)'
315 hooke> remove_cantilever_from_extension --block retract
316 hooke> flat_peaks_to_polymer_peaks --block retract
317 hooke> polymer_fit_peaks --block retract
318 hooke> block_info --block retract --output data.yaml name 'polymer peak [0-9]*'
320 This stores the fit parameters in the block's
321 :attr:`~hooke.curve.Data.info` dictionary and also appends them to
322 :file:`data.yaml` (see each command's `Help`_ for details). To access
323 the parameters, load :file:`data.yaml` with PyYAML_::
327 >>> import hooke.util.yaml
328 >>> data = yaml.load(open('data.yaml', 'r'))
330 and extract your parameter::
332 >>> data['20071120a_i27_t33.100']['retract']['polymer peak 0']['contour length (m)']
335 .. _PyYAML: http://pyyaml.org/
340 Since you are likely to apply similar analysis to several curves,
341 Hooke provides :mod:`command stacks <hooke.command_stack>` for
342 bundling groups of commands.::
344 hooke> start_command_capture
345 hooke> zero_surface_contact_point --block retract
346 hooke> flat_filter_peaks --block retract --min_points 1
348 hooke> stop_command_capture
350 You can check the state of the command stack with
351 ``get_command_stack`` and the state of capture with
352 ``get_command_capture_state``. If you make mistakes, you can pop
353 commands from the stack with ``pop_command_from_stack``. If you stop
354 capturing a command stack (e.g. to test a complicated command before
355 continuing), you can continue adding to the same stack with
356 ``restart_command_capture.``
358 To execute a command stack, run::
360 hooke> execute_command_stack
362 To execute a command stack on every curve in a playlist, run::
364 hooke> apply_command_stack_to_playlist
366 If you decide that there are commands in a curve's stack that you
367 don't want, you can clear the stack with::
369 hooke> clear_curve_command_stack
371 You can also save command stacks to disk (and reload them later,
372 potentially in a different Hooke session).::
374 hooke> save_command_stack --output my_stack
375 hooke> load_command_stack --input my_stack
377 Multiple curve analysis
378 ~~~~~~~~~~~~~~~~~~~~~~~
380 You can analyze multiple curves by combining `Worm like chain and
381 freely jointed chain fitting`_ and `Command stacks`_.::
383 hooke> start_command_capture
384 hooke> zero_surface_contact_point --block retract
385 hooke> flat_filter_peaks --block retract --min_points 1
386 hooke> zero_surface_contact_point --block retract
387 ... --ignore_after_last_peak_info_name 'flat filter peaks'
388 hooke> convert_distance_to_force --block retract
389 ... --deflection_column 'surface deflection (m)'
390 hooke> remove_cantilever_from_extension --block retract
391 hooke> flat_peaks_to_polymer_peaks --block retract
392 hooke> polymer_fit_peaks --block retract
393 hooke> block_info --block retract --output data.yaml name 'polymer peak [0-9]*'
394 hooke> stop_command_capture
395 hooke> apply_command_stack_to_playlist
400 You can set environment variables to influence the behaviour of Hooke.
401 The command to use is ``set_config``. Use ``get_config`` to read a
402 particular option and ``print_config`` to display the entire
403 configuration file. To save changes, either run ``save_config`` or
404 start Hooke with the ``--save-config`` option. See :doc:`config` for