If you are running hooke from the source directory (see
:doc:`install`), the equivalent command is::
- $ python bin/hooke
+ $ python bin/hk.py
-You may need to give the full path for Python on Windows systems.
+You may need to give the full path for Python on Windows systems, and
+also check that the current working directory (`.`) is in your
+`PYTHONPATH`. See :manpage:`python(1)` for details.
As Hooke launches, you should see something like the following in your
terminal::
- Hooke version 0.8.0 Seinei
+ Hooke version 0.9.0.devel (Kenzo)
- COPYRIGHT
+ Copyright (C) 2006-2010 A. Seeholzer, Alberto Gomez-Casado, Allen
+ Chen, Fabrizio Benedetti, Francesco Musiani, Marco Brucale, Massimo
+ Sandal, Pancaldi Paolo, Richard Naud, Rolf Schmidt, W. Trevor King
+
+ Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU
+ Lesser General Public License. For details, run `license`.
----
hooke>
for example::
- hooke> help current
+ hooke> help load_playlist
+
+will give help on the ``load_playlist`` command.
+
+Leaving Hooke
+-------------
-will give help on the ``current`` command.
+When you're done with an interactive Hooke session, you can close the
+session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is
+the end of the stdin stream, which is Ctrl-d in many shells).
Creating a playlist
-------------------
-To start analyzing your curves, you first have to build a playlist. The
-playlist is just an index of the force curve files you want to
-analyze. Imagine it as a music playlist (that’s why it is called a
+To start analyzing your curves, you first have to build a playlist.
+The playlist is just an index of the force curve files you want to
+analyze. Imagine it as a music playlist (that’s why it is called a
playlist), but with data files instead of audio files.
Suppose you have 100 PicoForce curve files in your curves directory,
You then can ``cd`` (change directory) to the directory::
- hooke> cd c:\curves
+ hooke> cd --path "c:\curves"
-Type ``pwd`` (print working directory) to check the directory is correct.::
+Hooke parses it's commandline using `POSIX rules`_, so you need to
+quote arguments with backslashes to keep them from being expanded as
+escape sequences (e.g. ``\t`` → ``TAB``).
+
+Type ``pwd`` (print working directory) to check the directory is
+correct.::
hooke> pwd
c:\curves
+.. _POSIX rules: http://docs.python.org/library/shlex#parsing-rules
+
You can list the files in the directory using ``ls`` or ``dir``
(they’re synonyms).::
hooke> ls
- [’mycurve.000’, ’mycurve.001’, ...
- ]
+ mycurve.000
+ mycurve.001
+ ...
+
+Now you are ready to generate the playlist. First, create a blank playlist::
+
+ hooke> new_playlist --output_playlist mylist
+
+Ensure that the new playlist is active::
+
+ hooke> jump_to_playlist -- -1
+ hooke> get_playlist
+ <FilePlaylist mylist>
+
+The ``--`` in the ``jump_to_playlist`` command lets
+``jump_to_playlist`` know that ``-1`` is an argument and not an
+option. Using the bare ``--`` is a POSIX specification [#POSIX]_
+supported by the `optparse module`_. You don't need to jump if
+the new playlist is your only loaded playlist.
-Now you are ready to generate the playlist. The command to use is
-``genlist``.::
+.. _optparse module:
+ http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
- hooke> genlist mycurve.*
+.. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
-You can also generate a playlist containing all what you find in the
-directory by typing:
+ "The first ``--`` argument that is not an option-argument should be
+ accepted as a delimiter indicating the end of options. Any
+ following arguments should be treated as operands, even if they
+ begin with the ``-`` character."
- hooke> genlist c:\curves
+Then glob your curves onto the new list::
-If you want to select what curves to see, based on the filename, you
-can use wildcards. For example::
+ hooke> glob_curves_to_playlist mycurve.*
- hooke> genlist mycurve.05*
+You can also be more specific with wildcards. For example::
+
+ hooke> glob_curve_to_playlist mycurve.05*
will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
-Note that by using ``genlist`` you just generate the playlist in the
-local session. To save your playlist to a file for future reuse,
-type::
+Note that by using ``glob_curves_to_playlist`` you just generate the
+playlist in the local session. To save your playlist to a file for
+future reuse, type::
- hooke> savelist mylist
+ hooke> save_playlist --output mylist
In this example, the list will be saved in the file
:file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke
playlist) to the playlist if you forget to. The ``.hkp`` file is an
XML file you can read and edit with any text editor (i.e. Wordpad), if
-needed. If you want to load it, simply issue ``loadlist mylist.hkp``
-or ``loadlist mylist``, Hooke will add ``.hkp`` if necessary.
+needed. If you want to load it, simply issue ``load_playlist
+mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
+necessary.
If, generating the playlist, you are including by chance a non-force
-curve file that Hooke cannot open, Hooke will print an error and
+curve file that Hooke cannot open, Hooke will log a warning and
continue on.
Navigating the playlist
-----------------------
-Now you can navigate through your playlist using the commands `next`
-and `previous` or, their aliases `n` and `p`. You don’t need to
-type `n` every time to run along a list of curves. If you press
-Return to an empty prompt, Hooke will repeat the last command you
-issued explicitly. You can also navigate through the command history
-by using the up and down arrows. From the last curve of your
-playlist, `n` will wrap around to the first curve. Analogously,
-issuing `p` at the first curve will jump to the last.
+Now you can navigate through your playlist using the commands
+``next_curve`` and ``previous_curve``. You don’t need to type
+``next_curve`` every time to run along a list of curves. You can
+navigate through the command history by using the up and down arrows,
+or auto-complete partial commands with TAB. From the last curve of
+your playlist, ``next_curve`` will wrap around to the first curve.
+Analogously, issuing ``previous_curve`` at the first curve will jump
+to the last.
You can also jump to a given curve::
- hooke> jump c:\curves\mycurve.012
+ hooke> jump_to_curve 14
+
+will jump to the 14th curve in the zero-indexed playlist.
+
+.. todo:: ``jump_to_curve <PATH>``, where the path can be either an
+ absolute path or a path relative to the directory holding the
+ playlist file.
+
+Replace ``curve`` with ``playlist`` in the above commands to navigate
+around through the list of loaded playlists.
+
+Because the playlist name is usually saved in the playlist file
+itself, there is a ``name_playlist`` command that allows you to rename
+playlists on the fly.
-where the path can be either an absolute path, or a path relative to
-the directory holding the playlist file.
+ hooke> name_playlist 'my old playlist'
Taking notes
------------
You can take notes about the curves you are looking at. Just type
-`note` followed by the text you want to append to that curve. Hooke
-will save the text in your current playlist and in an external log
-file. The output will look like this::
+``set_note`` followed by the text you want to attach to that curve.
+Hooke will save the text in your current playlist and in an external
+log file.
+
+.. todo:: No external file yet. Is this important?
+
+The output will look like this::
Notes taken at Sun Sep 17 20:42:07 2006
- /home/cyclopia/work/tris/20060620a.041 | This is a note
- /home/cyclopia/work/tris/20060620a.207 | This is another note
- /home/cyclopia/work/tris/20060620a.286 | This is a third one
+ /home/cyclopia/work/tris/20060620a.041 | This is a note
+ /home/cyclopia/work/tris/20060620a.207 | This is another note
+ /home/cyclopia/work/tris/20060620a.286 | This is a third one
The log file name can be configured (:doc:`config`), but it defaults
to :file:`hooke.log`.
-Usually curves you annotated are useful later. You can copy the curves
-you annotated to a different directory by using the ``copylog``
-command.
+Usually curves you annotated are useful later. You can create a
+playlist for only annotated curves with
- hooke> copylog c:\nicecurves
+ hooke> note_filter_playlist --output_playlist nice_list
-will copy all curves you have annotated to the :file:`c:\nicecurves`
-directory. Make sure that the directory already exists before doing
-that. TODO: replace with::
+will create sub-playlist `nice_list`. Remember to save the new list
+if you like it.
- hooke> copylist --log c:\curves\nice.hkp
+If you change your mind about a note, you can remove it by setting a
+blank note string with ``set_note ''``.
Exporting curves
----------------
-You can export Hooke curves as images and as text columns. To export
-as images, issue the ``export`` command followed by the filename.
-Supported formats are PNG (raster) and EPS (Encapsulated Postscript,
-vector). The export format is determined by the filename extension,
-so ``export foo.png`` and ``export foo.eps`` will save PNG and EPS
-files respectively.
+You can export Hooke curves as images and as text columns. To export
+as images or text, use the ``export_block`` command. Supported
+formats are PNG (Portable Network Graphic, raster) and EPS
+(Encapsulated Postscript, vector). The export format is determined by
+the filename extension, so ``export_block --output foo.png``,
+``export_block --output foo.eps``, and ``export_block --output
+foo.txt`` will save PNG, EPS, and TAB-delimited text files
+respectively.
-To export as text, use the ``txt`` command, followed by the
-filename. The output is a text file containing columns (first two are
-X and Y of extension, second two are X and Y of retraction).
+.. todo:: Currently no PNG or EPS output, use the GUI and the plot
+ panel's toolbar for non-text exports.
-TODO: multiple cycles? Solution: blank lines for "breaks", add option
-to extract specific sections using Python's slice notation.
+.. todo:: Multiple cycles in exported data? Solution: blank lines for
+ "breaks", add option to extract specific sections using Python's
+ slice notation.
+If you don't want the entire block, try the ``cut`` command.
-Interacting with the plot
--------------------------
+Analysis
+--------
-(no plots in command line mode...)
+The commands we have covered so far allow basic bookkeeping. The
+point of Hooke, though, is to allow you to easily analyze force
+spectroscopy data. We cover those analysis commands in this section.
Measuring distances and forces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can easily zoom in the plot by dragging a rectangle on it with the
-left mouse button. To zoom out, click the right mouse
-button. Sometimes by zooming in and out too much, you can lose the
-picture (this is probably a small bug in Matplotlib). Just type
-``plot`` at the command line and the curve will be refreshed.
+To measure the distance between points, use the ``delta`` command.
+For example,::
-You can measure distances and forces directly in the plot. Just issue
-the command ``distance``. You will be asked to click two points.
-When you click a point, a blue dot should appear. When you click the
-second point, the distances (in nanometers and piconewtons) will
-appear on the command line. You can use ``delta`` if you prefer,
-which gives meaningful values for every kind of graph (not only force
-curves). If you want to know the coordinates of a single point, use
-``point``.
+ hooke> delta 300 500
-Hooke automatically adjusts the position of the clicked point to the
-nearest point in the graph, so you will be always measuring distances
-and forces between points in the graph.
+will measure the distance between the 300th point and the 500th point.
+One difficulty with the command line interface is that is difficult
+to know which points you're interested without seeing the plot. The
+two ways around this are:
-The commands ``force`` and ``distance`` are present in the
-``generalvclamp`` plugin.
+1) Export the block (with ``export_block``), and graph the exported
+ file with a program of your choice (e.g. Gnuplot_). Use the
+ resulting graph to determine the indices of the points you are
+ interested in.
+2) Run Hooke's GUI instead of the command line when you need to make
+ manual measurements. See :doc:`gui` for details.
+
+.. _Gnuplot: http://gnuplot.sourceforge.net/
Worm like chain and freely jointed chain fitting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-You can measure by hand the parameters relative to a force peak using
-a worm-like chain fitting with the ``fit`` command. The command by
-default automatically finds the contact point, asks for two points
-delimiting the portion to fit, and performs a two-variable fit, with
-contour length, persistence length, and their relative errors as
-output. If desired, one can use the ``noauto`` option to manually
-click the contact point, and/or the ``pl=NUMBER`` options to impose a
-specific persistence or Kuhn length (in nanometers). You can choose
-which model to use with ``set fit_function wlc`` or ``set fit_function
-fjc``. See the help of the ``fit`` command from the Hooke command
-line for details.
-
-Multiple curve fitting and measuring
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can cycle through all your current playlist obtaining WLC fit, FJC
-fit, rupture force and slope (loading rate) information from each
-curve using the ``multifit`` command. The collected data can be saved
-in a text file for further analysis in your favourite spreadsheet or
-statistical program. If you want to check your parameters on the
-current curve before fitting all the files in your playlist, use
-``multifit justone``. See the ``multifit`` help for more options.
-
-Fast curve reviewing and saving
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When automatic routines are not good enough to filter your data, use
-``review`` command to cycle through your playlist presenting ten
-curves in the same graph. You can then enter the numbers of the
-interesting curves and automatically save a copy of them into another
-directory.
+Polymer model fitting is a complicated beast. To correctly fit your
+chosen model (WLC, FJC, etc.), you need to execute a multi-step
+analysis. Hooke provides a flexible chain of curve analyisis commands
+that create new data columns (e.g. `deflection (N)`) or store
+information in a curve's `info` dictionary (e.g. `flat filter peaks`).
+You can, if necessary, adjust the names of input and output columns
+and `info` values to combine the available commands in new and useful
+ways.::
+
+ hooke> zero_surface_contact_point --block retract
+ hooke> flat_filter_peaks --block retract --min_points 1
+ hooke> zero_surface_contact_point --block retract
+ ... --ignore_after_last_peak_info_name 'flat filter peaks'
+ hooke> convert_distance_to_force --block retract
+ ... --deflection_column 'surface deflection (m)'
+ hooke> remove_cantilever_from_extension --block retract
+ hooke> flat_peaks_to_polymer_peaks --block retract
+ hooke> polymer_fit_peaks --block retract
+ hooke> block_info --block retract --output data.yaml name 'polymer peak [0-9]*'
+
+This stores the fit parameters in the block's
+:attr:`~hooke.curve.Data.info` dictionary and also appends them to
+:file:`data.yaml` (see each command's `Help`_ for details). To access
+the parameters, load :file:`data.yaml` with PyYAML_::
+
+ $ python
+ >>> import yaml
+ >>> import hooke.util.yaml
+ >>> data = yaml.load(open('data.yaml', 'r'))
+
+and extract your parameter::
+
+ >>> data['20071120a_i27_t33.100']['retract']['polymer peak 0']['contour length (m)']
+ 2.124...e-08
+
+.. _PyYAML: http://pyyaml.org/
+
+Command stacks
+~~~~~~~~~~~~~~
+
+Since you are likely to apply similar analysis to several curves,
+Hooke provides :mod:`command stacks <hooke.command_stack>` for
+bundling groups of commands.::
+
+ hooke> start_command_capture
+ hooke> zero_surface_contact_point --block retract
+ hooke> flat_filter_peaks --block retract --min_points 1
+ ...
+ hooke> stop_command_capture
+
+You can check the state of the command stack with
+``get_command_stack`` and the state of capture with
+``get_command_capture_state``. If you make mistakes, you can pop
+commands from the stack with ``pop_command_from_stack``. If you stop
+capturing a command stack (e.g. to test a complicated command before
+continuing), you can continue adding to the same stack with
+``restart_command_capture.``
+
+To execute a command stack, run::
+
+ hooke> execute_command_stack
+
+To execute a command stack on every curve in a playlist, run::
+
+ hooke> apply_command_stack_to_playlist
+
+If you decide that there are commands in a curve's stack that you
+don't want, you can clear the stack with::
+
+ hooke> clear_curve_command_stack
+
+You can also save command stacks to disk (and reload them later,
+potentially in a different Hooke session).::
+
+ hooke> save_command_stack --output my_stack
+ hooke> load_command_stack --input my_stack
+
+Multiple curve analysis
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You can analyze multiple curves by combining `Worm like chain and
+freely jointed chain fitting`_ and `Command stacks`_.::
+
+ hooke> start_command_capture
+ hooke> zero_surface_contact_point --block retract
+ hooke> flat_filter_peaks --block retract --min_points 1
+ hooke> zero_surface_contact_point --block retract
+ ... --ignore_after_last_peak_info_name 'flat filter peaks'
+ hooke> convert_distance_to_force --block retract
+ ... --deflection_column 'surface deflection (m)'
+ hooke> remove_cantilever_from_extension --block retract
+ hooke> flat_peaks_to_polymer_peaks --block retract
+ hooke> polymer_fit_peaks --block retract
+ hooke> block_info --block retract --output data.yaml name 'polymer peak [0-9]*'
+ hooke> stop_command_capture
+ hooke> apply_command_stack_to_playlist
Configuring Hooke
-----------------
-You can set environment variables to influence the behaviour of
-Hooke. The command to use is ``set``.
-
-You can alter permanently the behaviour of Hooke by setting these
-variables in a Hooke configuration file. See :doc:`config` for
+You can set environment variables to influence the behaviour of Hooke.
+The command to use is ``set_config``. Use ``get_config`` to read a
+particular option and ``print_config`` to display the entire
+configuration file. To save changes, either run ``save_config`` or
+start Hooke with the ``--save-config`` option. See :doc:`config` for
details.