X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=doc%2Ftutorial.txt;h=80dfb53bb9e1288165dd1edb17e07d1d741cbe8b;hp=302fa6931254b5dcbea610179f747a51c3e68c54;hb=d2f813ccd1b4085484af53a70a18b9485a991847;hpb=a39a8233d7ba34ea31df3d1cc93451782a703e97 diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 302fa69..80dfb53 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, @@ -123,7 +123,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:: @@ -133,18 +133,19 @@ 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 [#]_ supported -by the `optparse module`_. +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. .. _optparse module: http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments -.. [#]: `Guideline 10 of POSIX:2008's section 12.2 ` states: +.. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 `_ states: - "The first -- argument that is not an option-argument should be + "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." + begin with the ``-`` character." Then glob your curves onto the new list:: @@ -171,7 +172,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,18 +191,26 @@ 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. Taking notes ------------ You can take notes about the curves you are looking at. Just type -``add_note`` followed by the text you want to append to that curve. +``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,78 +223,94 @@ 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 with -``clear_note``. +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: multiple cycles? Solution: blank lines for "breaks", add option -to extract specific sections using Python's slice notation. +.. todo:: Currently no PNG or EPS output, use the GUI and the plot + panel's toolbar for non-text exports. + +.. 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,:: + + hooke> delta 300 500 -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``. +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: -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. +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. -The commands ``force`` and ``distance`` are present in the -``generalvclamp`` plugin. +.. _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. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. 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 @@ -298,6 +323,8 @@ current curve before fitting all the files in your playlist, use 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 @@ -307,9 +334,9 @@ directory. 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.