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
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 --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
+.. _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).::
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::
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
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
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
------------
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
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 ''``.
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
-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.
-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_config``.
-
-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.
projects / hooke.git / blobdiff