A number of minor documentation cleanups.

[hooke.git] / doc / tutorial.txt

********
Tutorial
********

`A short video showing Hooke in action`_! (courtesy of Fabrizio
Benedetti, EPFL, Lausanne)

.. _A short video showing Hooke in action:
  https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv

.. toctree::
   :maxdepth: 2

   gui.txt

Introduction
============

This tutorial will focus on the command-line interface as the most
powerful, and leave the 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


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

If you are running hooke from the source directory (see
Installation_), the equivalent command is::

    $ python bin/hooke

You may need to give the full path for Python on Windows systems.

.. _plugins: hooke/hooke.plugin.txt

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>

The final line, ``hooke>``, is the Hooke prompt.  It allows you to
enter commans to interact with the interpreter.

Help
----

All commands have help text explaining their purpose and usage.  The
text is stored in the code itself, and therefore more likely to be up
to date than this tutorial.  You can get a list of commands and topics
with::

    hooke> help

Or see specific help on ``TOPIC`` with::

    hooke> help TOPIC

for example::

    hooke> help current

will give help on the ``current`` command.

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
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.

You then can ``cd`` (change directory) to the directory::

    hooke> cd c:\curves

Type ``pwd`` (print working directory) to check the directory is correct.::

      hooke> pwd
      c:\curves

You can list the files in the directory using ``ls`` or ``dir`` (they’re
synonyms).::

    hooke> ls
    [’mycurve.000’, ’mycurve.001’, ...
    ]

Now you are ready to generate the playlist. The command to use is
``genlist``.::

    hooke> genlist mycurve.*

You can also generate a playlist containing all what you find in the
directory by typing:

    hooke> genlist c:\curves

If you want to select what curves to see, based on the filename, you
can use wildcards.  For example::

    hooke> genlist mycurve.05*

will take only curves from mycurve.050 to 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::

    hooke> savelist mylist

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.

If, generating the playlist, you are including by chance a non-force
curve file that Hooke cannot open, Hooke will print an error 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.

You can also jump to a given curve::

    hooke> jump c:\curves\mycurve.012

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:

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.

.. _configured: config.txt

Usually curves you annotated are useful later.  You can copy the curves
you annotated to a different directory by using the ``copylog``
command.

    hooke> copylog c:\nicecurves

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

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).

TODO: multiple cycles?  Solution: blank lines for "breaks", add option
to extract specific sections using Python's slice notation.


Interacting with the plot
-------------------------

(no plots in command line mode...)

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.

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 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.

The commands ``force`` and ``distance`` are present in the
``generalvclamp`` plugin.

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.

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 the `Configuring Hooke`_
section for details.

.. _Configuring Hooke: config.txt