Added USAGE file based on http://code.google.com/p/hooke/wiki/BasicAnalysis
authorW. Trevor King <wking@drexel.edu>
Thu, 17 Dec 2009 20:02:55 +0000 (15:02 -0500)
committerW. Trevor King <wking@drexel.edu>
Thu, 17 Dec 2009 20:02:55 +0000 (15:02 -0500)
CHANGELOG
README
doc/USAGE [new file with mode: 0644]

index 318ab34..f71b509 100755 (executable)
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -21,7 +21,7 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
 (2008-04-16)
     PLUGINS:
     generalvclamp.py:
-        fixed autopeak header 
+        fixed autopeak header
         fixed autopeak slope (now unwanted slope values are discarded)
 
 0.8.2
@@ -40,7 +40,7 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
         fixed DeprecationWarning in flatten
     flatfilts.py
         convfilt now working
-        
+
 
 0.8.0:
 (2008-04-04)
@@ -196,7 +196,7 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
     hooke_cli.py:
         fixed error handling in notelog
         smarter handling of directory names in genlist
-        unexpected error handling in do_plot() 
+        unexpected error handling in do_plot()
     hooke.py:
         implemented GetDisplayedPlot event and handlers
     PLUGINS:
@@ -302,14 +302,14 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
     libhooke.py:
         fixed bug that prevented flatfilt to work
         (maybe) fixed memory leak in flatfilt
-    
+
 0.4.0 "Hanzei":
 (2007-02-08)
     general code updating and rewriting due to double plot/force clamp supports
     hooke.py:
         initial dummy menu sketch
     hooke.py, hooke_cli.py:
-        first general support in code for double plot: 
+        first general support in code for double plot:
         - derivplot now in separate plot
         - implemented show and close commands
         - all functions should be double plot-aware
@@ -348,7 +348,7 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
 0.2.1 :
     hooke.py , libhooke.py:
         fixed 'wlc noauto' bug (0012) preventing correct contact point to be used
-0.2.0 : 
+0.2.0 :
     hooke_cli.py:
         implemented getlist (alias of genlist)
         implemented contact (to plot the contact point)
@@ -364,12 +364,12 @@ FROM 0.8.4 ONWARD, DETAILED CHANGELOGS ARE AVAILABLE ON THE HOOKE SUBVERSION REP
     libhooke.py:
         new contact point algorithm (new algorithm)
         wlc fit now uses a fancier domain (from contact point to a bit more than last point); initial chunk preparation section moved from hooke.py
-    
+
 
 OLDER CHANGELOGS:
 
 hooke.py:
-0.1.1   : 
+0.1.1   :
     From now on, all changelog is stored in hooke.py
     hooke_cli.py:
         corrected bug 0010 (addtolist bug), alerts when hitting start/end of playlist
@@ -383,7 +383,7 @@ hooke_cli.py:
 0.1.1 : from now on, all changelog is in hooke.py
 2006_09_15_devel: implemented wlc; 0.1.0 milestone.
 2006_08_28_devel: refactoring of plot interaction
-2006_07_23_devel: implemented note; implemented flatfilt; implemented notelog; exit now warns if playlist/notes 
+2006_07_23_devel: implemented note; implemented flatfilt; implemented notelog; exit now warns if playlist/notes
                   have not been saved.
 2006_07_18_devel: implemented subtplot; bug 0007 ("cd" crashing) fixed
 2006_06_16_devel: moved math helper functions in libhooke.py
diff --git a/README b/README
index 3ab3fa9..df17b2e 100644 (file)
--- a/README
+++ b/README
@@ -8,6 +8,7 @@ requires the analysis of thousands of force curves at a time. As of
 today, there is no standard, free software for the analysis of force
 curves. Hooke aims to solve that.
 
+
 What it does?
 =============
 
@@ -21,6 +22,13 @@ What it does?
 See the Google Code website for more details
   http://code.google.com/p/hooke/
 
+
+How do you make it work?
+========================
+
+See the doc/USAGE file distributed with hooke.
+
+
 Is this published in some peer-reviewed journal?
 ================================================
 
@@ -31,6 +39,7 @@ doi:10.1093/bioinformatics/btp180
 
 Please cite Hooke if you use it.
 
+
 Troubleshooting
 ===============
 
@@ -39,6 +48,7 @@ If you have troubles in using it, before throwing it in the trash:
   2) ask a question in the discussion group!
 http://groups.google.com/group/hookesoftware
 
+
 Disclaimer
 ==========
 
diff --git a/doc/USAGE b/doc/USAGE
new file mode 100644 (file)
index 0000000..785f47d
--- /dev/null
+++ b/doc/USAGE
@@ -0,0 +1,246 @@
+Starting Hooke
+==============
+
+Open a terminal, go to the directory Hooke is installed and type
+python hooke/hooke.py (You may need to give the full path for Python
+on Windows systems).  If everything is OK, Hooke displays a nice
+splashscreen and starts.
+
+Once Hooke is launched from the terminal window, you see a text like
+the following:
+
+  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:
+
+Hooke tells you that plugins and drivers have been loaded, and now
+you’re ready to go. You’re now at the Hooke command line. In the
+meantime, a splashscreen and a window with a dummy force curve should
+appear . At the command line, type "help" or "?" to obtain a list of
+available commands.
+
+hooke: ?
+Documented commands (type help <topic>):
+========================================
+addtolist debug        exit     genlist  ls   notelog previous  set
+cd         derivplot export     getlist  n    p       printlist size
+contact    dir        flatfilt jump      next plateau pwd       subtplot
+current    distance    force    loadlist note plot    savelist  wlc
+Undocumented commands:
+======================
+help
+
+hooke:
+
+
+Begin your analysis
+===================
+
+Create 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 made of data files instead of MP3s (or FLACs :p).
+
+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.
+
+You then can cd to the directory
+
+  hooke: cd c:\curves
+
+Type pwd to check the directory is correct
+
+  hooke: pwd
+  c:\curves
+  hooke:
+
+You can list the files in the directory using ls or dir (they’re synonims)
+
+  hooke: ls
+  [’mycurve.000’, ’mycurve.001’, ...]
+
+Now you are ready to generate the playlist. The command to use is genlist
+
+  hooke: genlist mycurve.*
+
+You can also generate a playlist containing all what you find in the
+directory by typing:
+
+  hooke: genlist c:\curves
+
+If you want to select what curves to see, based on the filename, you
+can use wildcards.
+
+  For example:
+
+  hooke: genlist mycurve.05*
+
+will take only curves from mycurve.050 to mycurve.059.
+
+Saving and loading playlists
+----------------------------
+
+Note that by using genlist you just generate the playlist in the local
+session. To save your playlist to a file, thus avoiding to regenerate
+it, type:
+
+  hooke: savelist mylist
+
+The list will be saved, in this example, in the file mylist.hkp. Hooke
+will add the extension .hkp 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, just issue loadlist
+mylist.hkp or loadlist mylist, Hooke will handle the missing .hkp
+extension. This will load the saved playlist, as if you just generated
+it.
+
+Generating the playlist, you should see the plot of the first curve
+appearing. If, generating the playlist, you are including by chance a
+non-force curve file that Hooke cannot open, it should be (more or
+less) silently ignored. If it gives some error, or it does not plot
+anything, try to navigate forward, and see if the next curve is
+plotted; it is possible you spotted a corrupted file.  Navigate the
+playlist
+
+Navigating playlists
+--------------------
+
+Now you can navigate through your playlist using the command next and
+previous or, more easily, 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.
+
+When arriving to the last curve of your playlist, pressing n will just
+come back to the first. Analogously, pressing p when at the first
+curve will jump to the last.
+
+You can also jump to a given curve, this way:
+
+  hooke: jump c:\curves\mycurve.123
+
+but be careful to tell Hooke the full path to that curve, otherwise it
+will not find it.
+
+
+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 playlis and in an external log file. 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 first time you type note in a session, Hooke will ask you for a
+filename of the log.
+
+Usually curves you annotated are useful later. You can copy the curves
+you annotated in a different directory by using the copylog command,
+
+  hooke: copylog c:\nicecurves
+
+which will copy all curves you have annotated in the c:\nicecurves
+directory. Take care that the directory already exists before doing
+that.
+
+
+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, vector). The export format is determined by the filename
+extension, so export foo.png and export foo.eps will save a PNG and
+EPS file 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, last two are X and Y of retraction).
+
+
+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.
+
+You can measure distances and forces directly in the plot. Just issue
+the command distance. You will be asked to click two points: do
+it. When you click a point, a blue dot should appear. When you click
+the second point, the distance (in nanometers) will apper on the
+command line. force works in the same way. 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 automatically adjusts the position of the clicked point at 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.py
+plugin.
+
+Worm like chain fitting
+-----------------------
+
+You can measure by hand the parameters relative to a force peak using
+a worm-like chain fitting with the wlc 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 and persistence length as output, with relative errors. 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
+length (in nanometers). Please see the help of the wlc command from
+the Hooke command line for details.
+
+Variables
+---------
+
+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 the file conf/hooke.conf. This is a very simple XML file,
+just change the values of the variables with an ASCII text editor (not
+Word or a word processor - on Windows, Wordpad should work). Be
+careful with the correct XML syntax (which you should grasp very
+easily looking at the default configuration file) otherwise Hooke will
+crash on the next startup.
+
+See VariableList for help on individual variables.