doc/tutorial.txt

   1 ********
   2 Tutorial
   3 ********
   4
   5 `A short video showing Hooke in action`_! (courtesy of Fabrizio
   6 Benedetti, EPFL, Lausanne)
   7
   8 .. _A short video showing Hooke in action:
   9   https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv
  10
  11 .. toctree::
  12    :maxdepth: 2
  13
  14    gui
  15
  16 Introduction
  17 ============
  18
  19 This tutorial will focus on the command-line interface as the most
  20 powerful, and leave the :doc:`gui` interface to another document.
  21
  22 .. _command-line: `Command-line interface`_
  23
  24 Installation
  25 ============
  26
  27 See :doc:`install` for details on downloading and installing Hooke.
  28
  29
  30 Command-line interface
  31 ======================
  32
  33 Running the hooke shell
  34 -----------------------
  35
  36 Hooke has a set of commands that depend on the loaded
  37 :class:`hooke.plugin.Plugin`\s.  To access these commands, you'll need
  38 to run the Hooke shell.::
  39
  40     $ hooke
  41
  42 If you are running hooke from the source directory (see
  43 :doc:`install`), the equivalent command is::
  44
  45     $ python bin/hooke
  46
  47 You may need to give the full path for Python on Windows systems, and
  48 also check that the current working directory (`.`) is in your
  49 `PYTHONPATH`.  See :manpage:`python(1)` for details.
  50
  51 As Hooke launches, you should see something like the following in your
  52 terminal::
  53
  54     Hooke version 0.9.0.devel (Kenzo)
  55
  56     Copyright (C) 2006-2010 A. Seeholzer, Alberto Gomez-Casado, Allen
  57     Chen, Fabrizio Benedetti, Francesco Musiani, Marco Brucale, Massimo
  58     Sandal, Pancaldi Paolo, Richard Naud, Rolf Schmidt, W. Trevor King
  59
  60     Hooke comes with ABSOLUTELY NO WARRANTY and is licensed under the GNU
  61     Lesser General Public License.  For details, run `license`.
  62     ----
  63     hooke>
  64
  65 The final line, ``hooke>``, is the Hooke prompt.  It allows you to
  66 enter commands to interact with the interpreter.
  67
  68 Help
  69 ----
  70
  71 All commands have help text explaining their purpose and usage.  The
  72 text is stored in the code itself, and therefore more likely to be up
  73 to date than this tutorial.  You can get a list of commands and topics
  74 with::
  75
  76     hooke> help
  77
  78 Or see specific help on ``TOPIC`` with::
  79
  80     hooke> help TOPIC
  81
  82 for example::
  83
  84     hooke> help load_playlist
  85
  86 will give help on the ``load_playlist`` command.
  87
  88 Leaving Hooke
  89 -------------
  90
  91 When you're done with an interactive Hooke session, you can close the
  92 session with ``exit`` or its aliases ``quit`` and ``EOF`` (``EOF`` is
  93 the end of the stdin stream, which is Ctrl-d in many shells).
  94
  95 Creating a playlist
  96 -------------------
  97
  98 To start analyzing your curves, you first have to build a playlist. The
  99 playlist is just an index of the force curve files you want to
 100 analyze. Imagine it as a music playlist (that’s why it is called a
 101 playlist), but with data files instead of audio files.
 102
 103 Suppose you have 100 PicoForce curve files in your curves directory,
 104 starting from :file:`mycurve.000` and ending in :file:`mycurve.100`
 105 and you want to analyze them all.
 106
 107 You then can ``cd`` (change directory) to the directory::
 108
 109     hooke> cd --path c:\curves
 110
 111 Type ``pwd`` (print working directory) to check the directory is correct.::
 112
 113     hooke> pwd
 114     c:\curves
 115
 116 You can list the files in the directory using ``ls`` or ``dir``
 117 (they’re synonyms).::
 118
 119     hooke> ls
 120     mycurve.000
 121     mycurve.001
 122     ...
 123
 124 Now you are ready to generate the playlist.  First, create a blank playlist::
 125
 126     hooke> new_playlist --name mylist
 127
 128 Ensure that the new playlist is active::
 129
 130     hooke> jump_to_playlist -- -1
 131     hooke> get_playlist
 132     <FilePlaylist mylist>
 133
 134 The ``--`` in the ``jump_to_playlist`` command lets
 135 ``jump_to_playlist`` know that ``-1`` is an argument and not an
 136 option.  Using the bare ``--`` is a POSIX specification [#POSIX]_
 137 supported by the `optparse module`_.
 138
 139 .. _optparse module:
 140   http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments
 141
 142 .. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 <http://www.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html#tag_12_02>`_ states:
 143
 144     "The first ``--`` argument that is not an option-argument should be
 145     accepted as a delimiter indicating the end of options. Any
 146     following arguments should be treated as operands, even if they
 147     begin with the ``-`` character."
 148
 149 Then glob your curves onto the new list::
 150
 151     hooke> glob_curves_to_playlist mycurve.*
 152
 153 You can also be more specific with wildcards.  For example::
 154
 155     hooke> glob_curve_to_playlist mycurve.05*
 156
 157 will take only curves from :file:`mycurve.050` to :file:`mycurve.059`.
 158
 159 Note that by using ``glob_curves_to_playlist`` you just generate the
 160 playlist in the local session. To save your playlist to a file for
 161 future reuse, type::
 162
 163     hooke> save_playlist --output mylist
 164
 165 In this example, the list will be saved in the file
 166 :file:`mylist.hkp`.  Hooke will add the extension ``.hkp`` (Hooke
 167 playlist) to the playlist if you forget to.  The ``.hkp`` file is an
 168 XML file you can read and edit with any text editor (i.e. Wordpad), if
 169 needed.  If you want to load it, simply issue ``load_playlist
 170 mylist.hkp`` or ``load_playlist mylist``, Hooke will add ``.hkp`` if
 171 necessary.
 172
 173 If, generating the playlist, you are including by chance a non-force
 174 curve file that Hooke cannot open, Hooke will print an error and
 175 continue on.
 176
 177 Navigating the playlist
 178 -----------------------
 179
 180 Now you can navigate through your playlist using the commands
 181 ``next_curve`` and ``previous_curve``. You don’t need to type
 182 ``next_curve`` every time to run along a list of curves.  You can
 183 navigate through the command history by using the up and down arrows,
 184 or auto-complete partial commands with TAB.  From the last curve of
 185 your playlist, ``next_curve`` will wrap around to the first curve.
 186 Analogously, issuing ``previous_curve`` at the first curve will jump
 187 to the last.
 188
 189 You can also jump to a given curve::
 190
 191     hooke> jump_to_curve 14
 192
 193 will jump to the 14th curve in the playlist.  TODO: jump_to_curve
 194 <PATH>, where the path can be either an absolute path or a path
 195 relative to the directory holding the playlist file.
 196
 197 Taking notes
 198 ------------
 199
 200 You can take notes about the curves you are looking at.  Just type
 201 ``set_note`` followed by the text you want to attach to that curve.
 202 Hooke will save the text in your current playlist and in an external
 203 log file (TODO: no external file yet.  Is this important?).  The
 204 output will look like this::
 205
 206     Notes taken at Sun Sep 17 20:42:07 2006
 207     /home/cyclopia/work/tris/20060620a.041 | This is a note
 208     /home/cyclopia/work/tris/20060620a.207 | This is another note
 209     /home/cyclopia/work/tris/20060620a.286 | This is a third one
 210
 211 The log file name can be configured (:doc:`config`), but it defaults
 212 to :file:`hooke.log`.
 213
 214 Usually curves you annotated are useful later.  You can create a
 215 playlist for only annotated curves with
 216
 217     hooke> note_filter_playlist --name c:\curves\nice.hkp
 218
 219 will create sub-playlist :file:`c:\curves\nice.hkp`.  Make sure that
 220 the target directory (here :file:`c:\curves\`) already exists before
 221 doing that.
 222
 223 If you change your mind about a note, you can remove it by setting a
 224 blank note string with ``set_note ''``.
 225
 226 Exporting curves
 227 ----------------
 228
 229 You can export Hooke curves as images and as text columns. To export
 230 as images or text, use the ``export_block`` command.  Supported
 231 formats are PNG (Portable Network Graphic, raster) and EPS
 232 (Encapsulated Postscript, vector).  The export format is determined by
 233 the filename extension, so ``export_block foo.png``, ``export_block
 234 foo.eps``, and ``export_block foo.txt`` will save PNG, EPS, and
 235 TAB-delimited text files respectively.
 236
 237 TODO: multiple cycles?  Solution: blank lines for "breaks", add option
 238 to extract specific sections using Python's slice notation.
 239
 240 If you don't want the entire block, try the ``cut`` command.
 241
 242 Interacting with the plot
 243 -------------------------
 244
 245 (no plots in command line mode...)
 246
 247 Measuring distances and forces
 248 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 249
 250 You can move about the plot using its navigation toolbar.  See the
 251 `Matplotlib manual`_ for details.
 252
 253 .. _Matplotlib manual:
 254   http://matplotlib.sourceforge.net/users/navigation_toolbar.html
 255
 256 You can measure distances and forces directly in the plot. Just issue
 257 the command ``delta``.  You will be asked to click two points.  When
 258 you click a point, a blue dot should appear.  When you click the
 259 second point, the distances will appear in the output panel.  If you
 260 want to know the coordinates of a single point, left click on it.
 261
 262 Hooke automatically adjusts the position of the clicked point to the
 263 nearest point in the graph, so you will be always measuring distances
 264 and forces between points in the graph.
 265
 266 Worm like chain and freely jointed chain fitting
 267 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 268
 269 You can measure by hand the parameters relative to a force peak using
 270 a worm-like chain fitting with the ``fit`` command.  The command by
 271 default automatically finds the contact point, asks for two points
 272 delimiting the portion to fit, and performs a two-variable fit, with
 273 contour length, persistence length, and their relative errors as
 274 output.  If desired, one can use the ``noauto`` option to manually
 275 click the contact point, and/or the ``pl=NUMBER`` options to impose a
 276 specific persistence or Kuhn length (in nanometers). You can choose
 277 which model to use with ``set fit_function wlc`` or ``set fit_function
 278 fjc``.  See the help of the ``fit`` command from the Hooke command
 279 line for details.
 280
 281 Multiple curve fitting and measuring
 282 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 283
 284 You can cycle through all your current playlist obtaining WLC fit, FJC
 285 fit, rupture force and slope (loading rate) information from each
 286 curve using the ``multifit`` command.  The collected data can be saved
 287 in a text file for further analysis in your favourite spreadsheet or
 288 statistical program.  If you want to check your parameters on the
 289 current curve before fitting all the files in your playlist, use
 290 ``multifit justone``.  See the ``multifit`` help for more options.
 291
 292 Fast curve reviewing and saving
 293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 294
 295 When automatic routines are not good enough to filter your data, use
 296 ``review`` command to cycle through your playlist presenting ten
 297 curves in the same graph.  You can then enter the numbers of the
 298 interesting curves and automatically save a copy of them into another
 299 directory.
 300
 301 Configuring Hooke
 302 -----------------
 303
 304 You can set environment variables to influence the behaviour of
 305 Hooke. The command to use is ``set_config``.  Use ``get_config`` to
 306 read a particular option and ``print_config`` to display the entire
 307 configuration file.  Any changes to the configuration will be saved
 308 when you exit Hooke, see :doc:`config` for details.