X-Git-Url: http://git.tremily.us/?p=hooke.git;a=blobdiff_plain;f=doc%2Ftutorial.txt;h=80dfb53bb9e1288165dd1edb17e07d1d741cbe8b;hp=8f68f90ce1509f79e9368c65828e8d6a1b636169;hb=d2f813ccd1b4085484af53a70a18b9485a991847;hpb=7ba5f553f8344edb31a72576d5fbade55516e9b4 diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 8f68f90..80dfb53 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -11,24 +11,20 @@ Benedetti, EPFL, Lausanne) .. toctree:: :maxdepth: 2 - gui.txt + gui Introduction ============ This tutorial will focus on the command-line interface as the most -powerful, and leave the GUI interface to another document. +powerful, and leave the :doc:`gui` interface to another document. .. _command-line: `Command-line interface`_ -.. _GUI: gui.txt Installation ============ -See the Installation_ page for details on downloading and installing -Hooke. - -.. _Installation: install.txt +See :doc:`install` for details on downloading and installing Hooke. Command-line interface @@ -37,45 +33,37 @@ Command-line interface Running the hooke shell ----------------------- -Hooke has a set of commands that depend on the loaded plugins_. -To access these commands, you'll need to run the Hooke shell.:: +Hooke has a set of commands that depend on the loaded +:class:`hooke.plugin.Plugin`\s. To access these commands, you'll need +to run the Hooke shell.:: $ hooke If you are running hooke from the source directory (see -Installation_), the equivalent command is:: - - $ python bin/hooke +:doc:`install`), the equivalent command is:: -You may need to give the full path for Python on Windows systems. + $ python bin/hk.py -.. _plugins: hooke/hooke.plugin.txt +You may need to give the full path for Python on Windows systems, and +also check that the current working directory (`.`) is in your +`PYTHONPATH`. See :manpage:`python(1)` for details. As Hooke launches, you should see something like the following in your terminal:: - Starting Hooke. - Imported plugin fit - Imported plugin procplots - Imported plugin flatfilts - Imported plugin generalclamp - Imported plugin generalvclamp - Imported plugin massanalysis - Imported plugin macro - Imported driver picoforce - Imported driver hemingclamp - Imported driver csvdriver - Imported driver tutorialdriver - - Warning: Invalid work directory. - This is Hooke, version 0.8.0 Seinei - (c) Massimo Sandal, 2006. Released under the GNU General Public License Version 2 - Hooke is Free software. + Hooke version 0.9.0.devel (Kenzo) + + Copyright (C) 2006-2010 A. Seeholzer, Alberto Gomez-Casado, Allen + Chen, Fabrizio Benedetti, Francesco Musiani, Marco Brucale, Massimo + Sandal, Pancaldi Paolo, Richard Naud, Rolf Schmidt, W. Trevor King + + Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU + Lesser General Public License. For details, run `license`. ---- hooke> The final line, ``hooke>``, is the Hooke prompt. It allows you to -enter commans to interact with the interpreter. +enter commands to interact with the interpreter. Help ---- @@ -93,185 +81,236 @@ Or see specific help on ``TOPIC`` with:: for example:: - hooke> help current + hooke> help load_playlist + +will give help on the ``load_playlist`` command. -will give help on the ``current`` command. +Leaving Hooke +------------- + +When you're done with an interactive Hooke session, you can close the +session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is +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, -starting from ``mycurve.000`` and ending in ``mycurve.100`` and you -want to analyze them all. +starting from :file:`mycurve.000` and ending in :file:`mycurve.100` +and you want to analyze them all. You then can ``cd`` (change directory) to the directory:: - hooke> cd c:\curves + hooke> cd --path c:\curves Type ``pwd`` (print working directory) to check the directory is correct.:: - hooke> pwd - c:\curves + hooke> pwd + c:\curves -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).:: hooke> ls - [’mycurve.000’, ’mycurve.001’, ... - ] + mycurve.000 + mycurve.001 + ... + +Now you are ready to generate the playlist. First, create a blank playlist:: + + hooke> new_playlist --output_playlist mylist + +Ensure that the new playlist is active:: + + hooke> jump_to_playlist -- -1 + hooke> get_playlist + -Now you are ready to generate the playlist. The command to use is -``genlist``.:: +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`_. You don't need to jump if +the new playlist is your only loaded playlist. - hooke> genlist mycurve.* +.. _optparse module: + http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments -You can also generate a playlist containing all what you find in the -directory by typing: +.. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 `_ states: - hooke> genlist c:\curves + "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." -If you want to select what curves to see, based on the filename, you -can use wildcards. For example:: +Then glob your curves onto the new list:: - hooke> genlist mycurve.05* + hooke> glob_curves_to_playlist mycurve.* -will take only curves from mycurve.050 to mycurve.059. +You can also be more specific with wildcards. For example:: -Note that by using ``genlist`` you just generate the playlist in the -local session. To save your playlist to a file for future reuse, -type:: + hooke> glob_curve_to_playlist mycurve.05* - hooke> savelist mylist +will take only curves from :file:`mycurve.050` to :file:`mycurve.059`. -In this example, the list will be saved in the file ``mylist.hkp``. -Hooke will add the extension ``.hkp`` (Hooke playlist) to the playlist -if you forget to. The ``.hkp`` file is an XML file you can read and -edit with any text editor (i.e. Wordpad), if needed. If you want to -load it, simply issue ``loadlist mylist.hkp`` or ``loadlist mylist``, -Hooke will add ``.hkp`` if necessary. +Note that by using ``glob_curves_to_playlist`` you just generate the +playlist in the local session. To save your playlist to a file for +future reuse, type:: + + hooke> save_playlist --output mylist + +In this example, the list will be saved in the file +:file:`mylist.hkp`. Hooke will add the extension ``.hkp`` (Hooke +playlist) to the playlist if you forget to. The ``.hkp`` file is an +XML file you can read and edit with any text editor (i.e. Wordpad), if +needed. If you want to load it, simply issue ``load_playlist +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 ----------------------- -Now you can navigate through your playlist using the commands ``next`` -and ``previous`` or, their aliases ``n`` and ``p``. You don’t need to -type ``n`` every time to run along a list of curves. If you press -Return to an empty prompt, Hooke will repeat the last command you -issued explicitly. You can also navigate through the command history -by using the up and down arrows. From the last curve of your -playlist, ``n`` will wrap around to the first curve. Analogously, -issuing ``p`` at the first curve will jump to the last. +Now you can navigate through your playlist using the commands +``next_curve`` and ``previous_curve``. You don’t need to type +``next_curve`` every time to run along a list of curves. You can +navigate through the command history by using the up and down arrows, +or auto-complete partial commands with TAB. From the last curve of +your playlist, ``next_curve`` will wrap around to the first curve. +Analogously, issuing ``previous_curve`` at the first curve will jump +to the last. You can also jump to a given curve:: - hooke> jump c:\curves\mycurve.012 + hooke> jump_to_curve 14 + +will jump to the 14th curve in the zero-indexed playlist. -where the path can be either an absolute path, or a path relative to -the directory holding the playlist file. +.. 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 -``note`` followed by the text you want to append to that curve. Hooke -will save the text in your current playlist and in an external log -file. The output will look like this: +``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? -Notes taken at Sun Sep 17 20:42:07 2006 -/home/cyclopia/work/tris/20060620a.041 | This is a note -/home/cyclopia/work/tris/20060620a.207 | This is another note -/home/cyclopia/work/tris/20060620a.286 | This is a third one +The output will look like this:: -The log file name can be configured_, but it defaults to hooke.log. + Notes taken at Sun Sep 17 20:42:07 2006 + /home/cyclopia/work/tris/20060620a.041 | This is a note + /home/cyclopia/work/tris/20060620a.207 | This is another note + /home/cyclopia/work/tris/20060620a.286 | This is a third one -.. _configured: config.txt +The log file name can be configured (:doc:`config`), but it defaults +to :file:`hooke.log`. -Usually curves you annotated are useful later. You can copy the curves -you annotated to a different directory by using the ``copylog`` -command. +Usually curves you annotated are useful later. You can create a +playlist for only annotated curves with - hooke> copylog c:\nicecurves + hooke> note_filter_playlist --output_playlist nice_list -will copy all curves you have annotated to the c:\nicecurves -directory. Make sure that the directory already exists before doing -that. TODO: replace with:: +will create sub-playlist `nice_list`. Remember to save the new list +if you like it. - hooke> copylist --log c:\curves\nice.hkp +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 -as images, issue the ``export`` command followed by the filename. -Supported formats are PNG (raster) and EPS (Encapsulated Postscript, -vectorial). The export format is determined by the filename -extension, so ``export foo.png`` and ``export foo.eps`` will save -PNG and EPS files respectively. +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 --output foo.png``, +``export_block --output foo.eps``, and ``export_block --output +foo.txt`` will save PNG, EPS, and TAB-delimited text files +respectively. -To export as text, use the ``txt`` command, followed by the -filename. The output is a text file containing columns (first two are -X and Y of extension, second two are X and Y of retraction). +.. 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. +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 @@ -284,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 @@ -293,11 +334,9 @@ directory. Configuring Hooke ----------------- -You can set environment variables to influence the behaviour of -Hooke. The command to use is ``set``. - -You can alter permanently the behaviour of Hooke by setting these -variables in a Hooke configuration file. See the `Configuring Hooke`_ -section for details. - -.. _Configuring Hooke: config.txt +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.