.. _A short video showing Hooke in action:
https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv
+.. toctree::
+ :maxdepth: 2
+
+ gui
+
Introduction
============
This tutorial will focus on the command-line interface as the most
-powerful, and leave the GUI interface to another document.
+powerful, and leave the :doc:`gui` interface to another document.
.. _command-line: `Command-line interface`_
-.. _GUI: gui.txt
Installation
============
-See the Installation_ page for details on downloading and installing
-Hooke.
-
-.. _Installation: install.txt
+See :doc:`install` for details on downloading and installing Hooke.
Command-line interface
Running the hooke shell
-----------------------
-Hooke has a set of commands that depend on the loaded plugins_.
-To access these commands, you'll need to run the Hooke shell.::
+Hooke has a set of commands that depend on the loaded
+:class:`hooke.plugin.Plugin`\s. To access these commands, you'll need
+to run the Hooke shell.::
$ hooke
If you are running hooke from the source directory (see
-Installation_), the equivalent command is::
+:doc:`install`), the equivalent command is::
$ python bin/hooke
-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::
- Starting Hooke.
- Imported plugin fit
- Imported plugin procplots
- Imported plugin flatfilts
- Imported plugin generalclamp
- Imported plugin generalvclamp
- Imported plugin massanalysis
- Imported plugin macro
- Imported driver picoforce
- Imported driver hemingclamp
- Imported driver csvdriver
- Imported driver tutorialdriver
-
- Warning: Invalid work directory.
- This is Hooke, version 0.8.0 Seinei
- (c) Massimo Sandal, 2006. Released under the GNU General Public License Version 2
- Hooke is Free software.
+ Hooke version 0.9.0.devel (Kenzo)
+
+ 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>
The final line, ``hooke>``, is the Hooke prompt. It allows you to
-enter commans to interact with the interpreter.
+enter commands to interact with the interpreter.
Help
----
for example::
- hooke> help current
+ hooke> help load_playlist
-will give help on the ``current`` command.
+will give help on the ``load_playlist`` command.
+
+Leaving Hooke
+-------------
+
+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
-------------------
playlist), but with data files instead of audio files.
Suppose you have 100 PicoForce curve files in your curves directory,
-starting from ``mycurve.000`` and ending in ``mycurve.100`` and you
-want to analyze them all.
+starting from :file:`mycurve.000` and ending in :file:`mycurve.100`
+and you want to analyze them all.
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> pwd
- c:\curves
+ hooke> pwd
+ c:\curves
-You can list the files in the directory using ``ls`` or ``dir`` (they’re
-synonyms).::
+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 --name mylist
-Now you are ready to generate the playlist. The command to use is
-``genlist``.::
+Ensure that the new playlist is active::
- hooke> genlist mycurve.*
+ hooke> jump_to_playlist -- -1
+ hooke> get_playlist
+ <FilePlaylist mylist>
-You can also generate a playlist containing all what you find in the
-directory by typing:
+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`_.
- hooke> genlist c:\curves
+.. _optparse module:
+ http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
-If you want to select what curves to see, based on the filename, you
-can use wildcards. For example::
+.. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
- hooke> genlist mycurve.05*
+ "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."
-will take only curves from mycurve.050 to mycurve.059.
+Then glob your curves onto the new list::
-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::
+ hooke> glob_curves_to_playlist mycurve.*
- hooke> savelist mylist
+You can also be more specific with wildcards. For example::
-In this example, the list will be saved in the 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.
+ hooke> glob_curve_to_playlist mycurve.05*
+
+will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
+
+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> 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 ``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
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
-where the path can be either an absolute path, or a path relative to
-the directory holding the playlist file.
+will jump to the 14th curve in the 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.
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
+ 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
-The log file name can be configured_, but it defaults to hooke.log.
+The log file name can be configured (:doc:`config`), but it defaults
+to :file:`hooke.log`.
-.. _configured: config.txt
+Usually curves you annotated are useful later. You can create a
+playlist for only annotated curves with
-Usually curves you annotated are useful later. You can copy the curves
-you annotated to a different directory by using the ``copylog``
-command.
+ hooke> note_filter_playlist --name c:\curves\nice.hkp
- hooke> copylog c:\nicecurves
+will create sub-playlist :file:`c:\curves\nice.hkp`. Make sure that
+the target directory (here :file:`c:\curves\`) already exists before
+doing that.
-will copy all curves you have annotated to the c:\nicecurves
-directory. Make sure that the directory already exists before doing
-that. TODO: replace with::
-
- 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,
-vectorial). The export format is determined by the filename
-extension, so ``export foo.png`` and ``export foo.eps`` will save
-PNG and EPS 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).
+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 foo.png``, ``export_block
+foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and
+TAB-delimited text files respectively.
TODO: multiple cycles? 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 (no plots in command line mode...)
+Interacting with the plot
-------------------------
+(no plots in command line mode...)
+
Measuring distances and forces
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
+fjc``. See the help of the ``fit`` command from the Hooke command
+line for details.
Multiple curve fitting and measuring
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-----------------
You can set environment variables to influence the behaviour of
-Hooke. The command to use is ``set``.
+Hooke. The command to use is ``set_config``.
You can alter permanently the behaviour of Hooke by setting these
-variables in a Hooke configuration file. See the `Configuring Hooke`_
-section for details.
-
-.. _Configuring Hooke: config.txt
+variables in a Hooke configuration file. See :doc:`config` for
+details.