From 08d0c6648e124506db9c5fd977a566d1151f38dc Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 12 May 2010 17:39:40 -0400 Subject: [PATCH] Sync doc/tutorial.txt splash text with hooke.ui.UserInterface._splash_text. Also: * Flesh out doc/architecture.txt * Replace a number of '``' escapes with '`'. My reStructuredText was rusty on the first pass through the documentation ;). --- doc/doc.txt | 2 +- doc/hacking.txt | 107 +++++++++++++++++++++++++++++++++++++++---- doc/install.txt | 4 +- doc/testing.txt | 10 ++-- doc/tutorial.txt | 98 +++++++++++++++++---------------------- hooke/ui/__init__.py | 2 +- 6 files changed, 150 insertions(+), 73 deletions(-) diff --git a/doc/doc.txt b/doc/doc.txt index 319fe4d..b81c2ff 100644 --- a/doc/doc.txt +++ b/doc/doc.txt @@ -5,7 +5,7 @@ Producing this documentation This documentation is written in reStructuredText_, and produced using Sphinx_ and the numpydoc_ extension. The documentation source should be fairly readable without processing, but to compile the -documentation, change to the ``doc/`` directory and run:: +documentation, change to the `doc/` directory and run:: $ scons diff --git a/doc/hacking.txt b/doc/hacking.txt index ab8d9dc..5d4eacd 100644 --- a/doc/hacking.txt +++ b/doc/hacking.txt @@ -7,7 +7,7 @@ Hacking Hooke testing.txt -Architecture +Dependencies ============ To clean up the internals, were going to go crazy on the @@ -20,15 +20,13 @@ any dependencies other than the `Python Standard Library`_ and Numpy_ .. _Scipy: http://www.scipy.org/ To make a responsive user interface in parallel with data processing -and possible GUIs, we'll use Python's multiprocessing_ and queue_ -modules. These modules are both new in Python 2.6, but 2.6 usage is -becoming fairly widespread. Certainly more widespread than any -alternative queue module that I know of. Since we're leveraging the -power of the standard library, we use configparser_ for the config -files. +and possible GUIs, we'll use Python's multiprocessing_ module. This +module is new in Python 2.6, but 2.6 usage is becoming fairly +widespread. Certainly more widespread than any alternative queue +module that I know of. Since we're leveraging the power of the +standard library, we use configparser_ for the config files. .. _multiprocessing: http://docs.python.org/dev/library/multiprocessing.html -.. _queue: http://docs.python.org/library/queue.html .. _configparser: http://docs.python.org/library/configparser.html On the testing side, the need to stick to the standard library relaxes @@ -37,3 +35,96 @@ the Testing_ section for more information. .. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.3/ .. _Testing: testing.txt + + +Architecture +============ + +Hooke's main entry point is :class:`hooke.hooke.Hooke`. `Hooke` reads +in the configuration files and loads Plugins_ and Drivers_. Then it +forks off a :class:`hooke.engine.CommandEngine` instance to execute +Commands_, and a :class:`hooke.ui.UserInterface` instance to connect +the `CommandEngine` with the user. The `CommandEngine` runs in a +subprocess, which allows command execution to occur in parallel with +`UserInterface` interaction. The two processes communicate via two +:class:`multiprocessing.Queue`\s. + +There are a number of special classes availiable to structure queue +communications. See :mod:`hooke.interaction` and +:class:`hooke.command.CommandExit` for details. + +Plugins +------- + +:class:`hooke.plugin.Plugin`\s contain bundles of Commands_, +representing the various operations a user can carry out through the +Hooke interface. + +`Plugin`\s can depend on other `Plugin`\s, so you shouldn't need to +repeat code. One central `Plugin` can provide useful functionality +to several dependent `Plugin`\s. + +There is a `Plugin` subtype :class:`hooke.plugin.Builtin` which is +just like a `Plugin`, but is considered fundamental enough to not be +optional. `Builtin`\s are always loaded. + +Commands +~~~~~~~~ + +:class:`hooke.command.Command`\s specify user-actions in an +interface-agnostic manner. This makes writing +:class:`hooke.ui.UserInterface`\s easier, because you don't need to +know anything about particular `Plugin`\s or `Command`\s, you just +need to be able to explain the base classes for you user and then +speak the language of :mod:`hooke.interaction` and +:class:`hooke.command.CommandExit` with the +:class:`hooke.engine.CommandEngine` process. + +Drivers +------- + +:class:`hooke.driver.Driver`\s are responsible for reading assorted +data files into Hooke's Data_ structure. + +Data +---- + +Experiments +~~~~~~~~~~~ + +Force spectroscopy experiments come in several major flavors. Each +flavor gets its own subclass of :class:`hooke.experiment.Experiment` +in :mod:`hooke.experiment`. For example, force clamp experiments are +:class:`hooke.experiment.ForceClamp`. This gives Drivers_ a way to +tag experimental data so Commands_ know what they are working with. + +Curves +~~~~~~ + +Experiments_ tags need a data-holding container to tag, and +:class:`hooke.curve.Curve`\s are that container. Each `Curve` can +hole several blocks of :class:`hooke.curve.Data` (for example approach +and retract curves in a :class:`hooke.experiment.VelocityClamp` +experiment would be seperate blocks). `Curve`\s also have an +:attr:`~hooke.curve.Curve.info` attribute for persistently storing +arbitrary data. + +Playlists +~~~~~~~~~ + +Normally you'll want to analyze multiple Curves_ in one session. +:class:`hooke.playlist.Playlist`\s provide a convenient container for +Curves_, and the subclass :class:`hooke.playlist.FilePlaylist` add +persistant file backing (save, load, etc.). + +Utilities +--------- + +There are a number of general coding features we need for Hooke that +are not provided by Python's standard library. We factor those +features out into :mod:`hooke.utils`. + +There are also a number of features who's standard library support +changes with different versions of Python. :mod:`hooke.compat` +provides a uniform interface to those tools so that Hooke will work +with several Python versions. diff --git a/doc/install.txt b/doc/install.txt index 96d07d0..c61dcf1 100644 --- a/doc/install.txt +++ b/doc/install.txt @@ -30,9 +30,9 @@ Hooke_ is available as an Subversion_ repository:: $ svn checkout http://hooke.googlecode.com/svn/trunk/ hooke -There is also a `GUI fork`_ (Rolf Schmidt):: +.. There is also a `GUI fork`_ (Rolf Schmidt):: - $ svn checkout http://hooke.googlecode.com/svn/trunk/ hooke +.. $ svn checkout http://hooke.googlecode.com/svn/trunk/ hooke And a `fork`_ versioned in Git_ (W. Trevor King):: diff --git a/doc/testing.txt b/doc/testing.txt index 1f5ded4..736d9ca 100644 --- a/doc/testing.txt +++ b/doc/testing.txt @@ -3,11 +3,11 @@ Testing Hooke ************* Hooke's test framework is build using doctest_, unittest_, and nose_. -``nosetests`` (from the ``nose`` package) scans through the source +`nosetests` (from the `nose` package) scans through the source tree, searching out the various tests and running them. If you aren't -familiar with ``nose``, there is excellent documentation on its home -page. We use ``nose`` because its auto-discovery allows us to avoid -collecting all of our assorted tests into ``unittest.TestSuite``\s and +familiar with `nose`, there is excellent documentation on its home +page. We use `nose` because its auto-discovery allows us to avoid +collecting all of our assorted tests into `unittest.TestSuite`\s and running them by hand. To run the test suite from the Hooke installation directory, just use:: @@ -22,4 +22,4 @@ To run the test suite from the Hooke installation directory, just use:: Adding tests to modules ----------------------- -Just go crazy with doctests and unittests; ``nose`` will find them. +Just go crazy with doctests and unittests; `nose` will find them. diff --git a/doc/tutorial.txt b/doc/tutorial.txt index 8f68f90..c36b4f6 100644 --- a/doc/tutorial.txt +++ b/doc/tutorial.txt @@ -54,27 +54,13 @@ You may need to give the full path for Python on Windows systems. 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.8.0 Seinei + + COPYRIGHT ---- hooke> -The final line, ``hooke>``, is the Hooke prompt. It allows you to +The final line, `hooke>`, is the Hooke prompt. It allows you to enter commans to interact with the interpreter. Help @@ -87,7 +73,7 @@ with:: hooke> help -Or see specific help on ``TOPIC`` with:: +Or see specific help on `TOPIC` with:: hooke> help TOPIC @@ -95,7 +81,7 @@ for example:: hooke> help current -will give help on the ``current`` command. +will give help on the `current` command. Creating a playlist ------------------- @@ -106,19 +92,19 @@ 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 +starting from `mycurve.000` and ending in `mycurve.100` and you want to analyze them all. -You then can ``cd`` (change directory) to the directory:: +You then can `cd` (change directory) to the directory:: hooke> cd c:\curves -Type ``pwd`` (print working directory) to check the directory is correct.:: +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 +You can list the files in the directory using `ls` or `dir` (they’re synonyms).:: hooke> ls @@ -126,7 +112,7 @@ synonyms).:: ] Now you are ready to generate the playlist. The command to use is -``genlist``.:: +`genlist`.:: hooke> genlist mycurve.* @@ -142,18 +128,18 @@ can use wildcards. For example:: will take only curves from mycurve.050 to mycurve.059. -Note that by using ``genlist`` you just generate the playlist in the +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> savelist mylist -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 +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. +load it, simply issue `loadlist mylist.hkp` or `loadlist 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 @@ -162,14 +148,14 @@ 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 +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. +playlist, `n` will wrap around to the first curve. Analogously, +issuing `p` at the first curve will jump to the last. You can also jump to a given curve:: @@ -182,7 +168,7 @@ 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 +`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: @@ -196,7 +182,7 @@ The log file name can be configured_, but it defaults to hooke.log. .. _configured: config.txt Usually curves you annotated are useful later. You can copy the curves -you annotated to a different directory by using the ``copylog`` +you annotated to a different directory by using the `copylog` command. hooke> copylog c:\nicecurves @@ -211,13 +197,13 @@ 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. +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 +extension, so `export foo.png` and `export foo.eps` will save PNG and EPS files respectively. -To export as text, use the ``txt`` command, followed by the +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). @@ -237,37 +223,37 @@ 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. +`plot` at the command line and the curve will be refreshed. You can measure distances and forces directly in the plot. Just issue -the command ``distance``. You will be asked to click two points. +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, +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``. +`point`. 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. -The commands ``force`` and ``distance`` are present in the -``generalvclamp`` plugin. +The commands `force` and `distance` are present in the +`generalvclamp` plugin. 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 +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 +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 +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 @@ -275,17 +261,17 @@ 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 +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. +`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 +`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. @@ -294,7 +280,7 @@ Configuring Hooke ----------------- You can set environment variables to influence the behaviour of -Hooke. The command to use is ``set``. +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`_ diff --git a/hooke/ui/__init__.py b/hooke/ui/__init__.py index 0912edc..7836d3a 100644 --- a/hooke/ui/__init__.py +++ b/hooke/ui/__init__.py @@ -74,7 +74,7 @@ class UserInterface (object): def _splash_text(self): return (""" -This is Hooke, version %s +Hooke version %s COPYRIGHT ---- -- 2.26.2