From 707f96bc87b758b38d09b0bdf91c7f8fa1d6f3df Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Thu, 17 Dec 2009 15:02:55 -0500 Subject: [PATCH] Added USAGE file based on http://code.google.com/p/hooke/wiki/BasicAnalysis --- CHANGELOG | 18 ++-- README | 10 +++ doc/USAGE | 246 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 265 insertions(+), 9 deletions(-) create mode 100644 doc/USAGE diff --git a/CHANGELOG b/CHANGELOG index 318ab34..f71b509 100755 --- 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 --- 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 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 ): +======================================== +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. -- 2.26.2