******** Tutorial ******** `A short video showing Hooke in action`_! (courtesy of Fabrizio Benedetti, EPFL, Lausanne) .. _A short video showing Hooke in action: https://documents.epfl.ch/users/f/fb/fbenedet/www/hooke_short_demostration.ogv .. toctree:: :maxdepth: 2 gui Introduction ============ This tutorial will focus on the command-line interface as the most powerful, and leave the :doc:`gui` interface to another document. .. _command-line: `Command-line interface`_ Installation ============ See :doc:`install` for details on downloading and installing Hooke. Command-line interface ====================== Running 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 :doc:`install`), the equivalent command is:: $ 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 `PYTHONPATH`. See :manpage:`python(1)` for details. As Hooke launches, you should see something like the following in your terminal:: 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 commands to interact with the interpreter. Help ---- All commands have help text explaining their purpose and usage. The text is stored in the code itself, and therefore more likely to be up to date than this tutorial. You can get a list of commands and topics with:: hooke> help Or see specific help on ``TOPIC`` with:: hooke> help TOPIC for example:: hooke> help load_playlist will give help on the ``load_playlist`` 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 playlist), but with data files instead of audio files. Suppose you have 100 PicoForce curve files in your curves directory, 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 --path c:\curves Type ``pwd`` (print working directory) to check the directory is correct.:: hooke> pwd c:\curves You can list the files in the directory using ``ls`` or ``dir`` (they’re synonyms).:: hooke> ls mycurve.000 mycurve.001 ... Now you are ready to generate the playlist. First, create a blank playlist:: hooke> new_playlist --name mylist Ensure that the new playlist is active:: hooke> jump_to_playlist -- -1 hooke> get_playlist 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`_. .. _optparse module: http://docs.python.org/library/optparse.html#callback-example-6-variable-arguments .. [#POSIX] `Guideline 10 of POSIX:2008's section 12.2 `_ states: "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." Then glob your curves onto the new list:: hooke> glob_curves_to_playlist mycurve.* You can also be more specific with wildcards. For example:: hooke> glob_curve_to_playlist mycurve.05* will take only curves from :file:`mycurve.050` to :file:`mycurve.059`. 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 continue on. Navigating the playlist ----------------------- 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_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. 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:: 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 log file name can be configured (:doc:`config`), but it defaults 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 will create sub-playlist :file:`c:\curves\nice.hkp`. Make sure that the target directory (here :file:`c:\curves\`) already exists before doing that. 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 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. .. 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 ------------------------- (no plots in command line mode...) Measuring distances and forces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can move about the plot using its navigation toolbar. See the `Matplotlib manual`_ for details. .. _Matplotlib manual: http://matplotlib.sourceforge.net/users/navigation_toolbar.html You can measure distances and forces directly in the plot. Just issue the command ``delta``. 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 will appear in the output panel. If you want to know the coordinates of a single point, left click on it. 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. 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. 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.