X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=doc%2Ftutorial.txt;h=1e0b95709410e6d451b50dc9d2eed84e1e5fd602;hp=f4746b81d5d2ab85bf4ee770752487cae34cff12;hb=HEAD;hpb=15966e24f41616aeb474a869c1aaa4e80014af3f diff --git a/doc/tutorial.txt b/doc/tutorial.txt index f4746b8..1e0b957 100644 --- 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:: - $ 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 @@ -95,9 +95,9 @@ the end of the stdin stream, which is Ctrl-d in many shells). 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, @@ -106,13 +106,20 @@ and you want to analyze them all. 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).:: @@ -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:: - hooke> new_playlist --name mylist + hooke> new_playlist --output_playlist mylist 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]_ -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 @@ -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 -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 @@ -190,9 +198,20 @@ You can also jump to a given curve:: hooke> jump_to_curve 14 -will jump to the 14th curve in the playlist. TODO: jump_to_curve -, 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 ``, 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 ------------ @@ -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 -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 @@ -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 - 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 ''``. @@ -226,89 +247,159 @@ 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 ` 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``. 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.