X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=doc%2Ftutorial.txt;h=89a1919a1e09ddcb7b21aca2ad2a37f047ac75c4;hp=58cb57f3bbfb847aafbc0441a55a96265226812c;hb=efb1f76427c4d4dfd950cf7ed6643808693c4022;hpb=f62e16fe46b8f19137120a10332a64569ba3a3ad diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 58cb57f..89a1919 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:: @@ -134,7 +134,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 +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,9 +191,14 @@ 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 ------------ @@ -200,8 +206,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 +223,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,16 +234,21 @@ 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. @@ -247,31 +260,30 @@ Interacting with the plot 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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. todo:: Update WLC fitting tutorial section. + 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 @@ -279,13 +291,14 @@ 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 +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. 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 +311,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 +322,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.