Update WLC/FJC fitting section of doc/tutorial.txt

[hooke.git] / doc / tutorial.txt

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 8f68f90ce1509f79e9368c65828e8d6a1b636169..80dfb53bb9e1288165dd1edb17e07d1d741cbe8b 100644 (file)
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -11,24 +11,20 @@ Benedetti, EPFL, Lausanne)
 .. toctree::
    :maxdepth: 2
 
 .. toctree::
    :maxdepth: 2
 

-   gui.txt
+   gui

 
 Introduction
 ============
 
 This tutorial will focus on the command-line interface as the most
 
 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`_
 
 .. _command-line: `Command-line interface`_

-.. _GUI: gui.txt

 
 Installation
 ============
 
 
 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
 
 
 Command-line interface


@@ -37,45 +33,37 @@ Command-line interface
 Running the hooke shell
 -----------------------
 
 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
 
     $ hooke
 
 If you are running hooke from the source directory (see

-Installation_), the equivalent command is::
-
-    $ python bin/hooke
+:doc:`install`), the equivalent command is::

 
 

-You may need to give the full path for Python on Windows systems.
+    $ python bin/hk.py

 
 

-.. _plugins: hooke/hooke.plugin.txt
+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::
 
 
 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
     ----
     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
 ----
 
 Help
 ----


@@ -93,185 +81,236 @@ Or see specific help on ``TOPIC`` with::
 
 for example::
 
 
 for example::
 

-    hooke> help current
+    hooke> help load_playlist
+
+will give help on the ``load_playlist`` command.

 
 

-will give help on the ``current`` 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
 -------------------
 
 
 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,
 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::
 
 
 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.::
 
 
 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
 
     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>

 
 

-Now you are ready to generate the playlist. The command to use is
-``genlist``.::
+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.

 
 

-    hooke> genlist mycurve.*
+.. _optparse module:
+  http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments

 
 

-You can also generate a playlist containing all what you find in the
-directory by typing:
+.. [#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 c:\curves
+    "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."

 
 

-If you want to select what curves to see, based on the filename, you
-can use wildcards.  For example::
+Then glob your curves onto the new list::

 
 

-    hooke> genlist mycurve.05*
+    hooke> glob_curves_to_playlist mycurve.*

 
 

-will take only curves from mycurve.050 to mycurve.059.
+You can also be more specific with wildcards.  For example::

 
 

-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_curve_to_playlist mycurve.05*

 
 

-    hooke> savelist mylist
+will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.

 
 

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

 
 

-where the path can be either an absolute path, or a path relative to
-the directory holding the playlist file.
+.. 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.

 
 Taking notes
 ------------
 
 You can take notes about the curves you are looking at.  Just type
 
 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?

 
 

-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 output will look like this::

 
 

-The log file name can be configured_, but it defaults to hooke.log.
+    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

 
 

-.. _configured: config.txt
+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 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
 ----------------
 
 
 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.
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 
 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.
+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> export_block --block retract --output myblock.dat
+
+See each command's `Help`_ for details.
+
+.. todo:: Discuss command stacks and polymer model fitting.

 
 Multiple curve fitting and measuring
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Multiple curve fitting and measuring
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

+.. todo:: Update multiple curve fitting tutorial section.

 
 You can cycle through all your current playlist obtaining WLC fit, FJC
 fit, rupture force and slope (loading rate) information from each
 
 You can cycle through all your current playlist obtaining WLC fit, FJC
 fit, rupture force and slope (loading rate) information from each


@@ -284,6 +323,8 @@ current curve before fitting all the files in your playlist, use
 Fast curve reviewing and saving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Fast curve reviewing and saving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

+.. todo:: Update curve review tutorial section.
+

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


@@ -293,11 +334,9 @@ directory.
 Configuring Hooke
 -----------------
 
 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
+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.