test/data/vclamp_jpk/README: Document sample versions

[hooke.git] / doc / tutorial.txt

diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index f4746b81d5d2ab85bf4ee770752487cae34cff12..1e0b95709410e6d451b50dc9d2eed84e1e5fd602 100644 (file)
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -42,7 +42,7 @@ to run the Hooke shell.::
 If you are running hooke from the source directory (see
 :doc:`install`), the equivalent command is::
 
 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, and
 also check that the current working directory (`.`) is in your
 
 You may need to give the full path for Python on Windows systems, and
 also check that the current working directory (`.`) is in your


@@ -95,9 +95,9 @@ 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,


@@ -106,13 +106,20 @@ 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 --path 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
 
 
     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).::
 
 You can list the files in the directory using ``ls`` or ``dir``
 (they’re synonyms).::
 


@@ -123,7 +130,7 @@ You can list the files in the directory using ``ls`` or ``dir``
 
 Now you are ready to generate the playlist.  First, create a blank playlist::
 
 
 Now you are ready to generate the playlist.  First, create a blank playlist::
 

-    hooke> new_playlist --name mylist
+    hooke> new_playlist --output_playlist mylist

 
 Ensure that the new playlist is active::
 
 
 Ensure that the new playlist is active::
 


@@ -134,7 +141,8 @@ Ensure that the new playlist is active::
 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]_
 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`_.
+supported by the `optparse module`_.  You don't need to jump if
+the new playlist is your only loaded playlist.

 
 .. _optparse module:
   http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
 
 .. _optparse module:
   http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments


@@ -171,7 +179,7 @@ mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
 necessary.
 
 If, generating the playlist, you are including by chance a non-force
 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
 continue on.
 
 Navigating the playlist


@@ -190,9 +198,20 @@ You can also jump to a given curve::
 
     hooke> jump_to_curve 14
 
 
     hooke> jump_to_curve 14
 

-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.
+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.
+
+    hooke> name_playlist 'my old playlist'

 
 Taking notes
 ------------
 
 Taking notes
 ------------


@@ -200,8 +219,11 @@ Taking notes
 You can take notes about the curves you are looking at.  Just type
 ``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
 You can take notes about the curves you are looking at.  Just type
 ``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::
+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
 
     Notes taken at Sun Sep 17 20:42:07 2006
     /home/cyclopia/work/tris/20060620a.041 | This is a note


@@ -214,11 +236,10 @@ to :file:`hooke.log`.
 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 create a
 playlist for only annotated curves with
 

-    hooke> note_filter_playlist --name c:\curves\nice.hkp
+    hooke> note_filter_playlist --output_playlist nice_list

 
 

-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 create sub-playlist `nice_list`.  Remember to save the new list
+if you like it.

 
 If you change your mind about a note, you can remove it by setting a
 blank note string with ``set_note ''``.
 
 If you change your mind about a note, you can remove it by setting a
 blank note string with ``set_note ''``.


@@ -226,89 +247,159 @@ blank note string with ``set_note ''``.
 Exporting curves
 ----------------
 
 Exporting curves
 ----------------
 

-You can export Hooke curves as images and as text columns. To export
+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
 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.
+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.
+
+.. 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.
 
 
 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.
-
-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
 -----------------
 
 
 Configuring Hooke
 -----------------
 

-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.  Any changes to the configuration will be saved
-when you exit Hooke, see :doc:`config` for details.
+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.