README: Update to discuss unfold.py script and workflow

The old instructions were from back when I ran unfolding scans from
the IPython prompt.

diff --git a/README b/README
index d96ea2370a1cdf90923dde098ae7d9eab546d893..8b42736c3fe62ed119010dff78c21075bd337fd4 100644 (file)
--- a/README
+++ b/README
@@ -1,52 +1,112 @@
-Unfolding experiment procedure:
-
-At the ipython command line (use -pylab option for easy plotting)
->>> import unfold
->>> u = unfold.unfold(controlTemp=False)
-
-Approach the surface
->>> u.stepApproach(setpoint=1.0)
-Hold down during approach to keep O-ring from lifting the
-head. Diagnose by watching under video-microscope: head movement
-shifts picture.  Alternatively, use the flexible S-crossectioned
-"o-rings" or scrunchies to clamp head on tighter ;).
-
-Wiggle for interference just off the surface
->>> u.stepAway(); u.stepAway(); u.stepAway()
->>> import z_piezo_utils
->>> z_piezo_utils.wiggleForInterferenceMin(u.zp, wig_freq=1.0)
-
-Calibrate
->>> import calibcant.calibrate
->>> calibcant.config.DEFAULT_TEMP = 25 # degrees C
->>> calibcant.calibrate.calib(stepper=u.step, zpiezo=u.zp, push_depth=90)
-push_depth is in nm.  There are a host of other keyword arguments to
-calib.  See them all with
->>> calibcant.calibrate.calib._kwargs(calibcant.calibrate.calib)
-
-Tweak coarse surface position (these are stepper-backlash protected functions)
->>> u.stepCloser()
->>> u.stepAway()
-
-Unfold a protein
->>> u.unfold(rel_setpoint=2, nmDist=1400,...)
-
-There's also a convenience function `loop_rates`
->>> rates = [250, 500, 750, 1000]
->>> unfold.loop_rates(u, rates=rates, num_loops=10, die_file="~/die",
-                      rel_setpoint=1, nmDist=800, sBindTime=2, ...)
-which unfolds at each rate 10 times, unless ~/die exist, in which case
-it stops nicely.  rel_setpoint, nmDist, sBindTime, and other additional
-options are just passed on to unfold.unfold().
-
-Modules :
-see unfold.png
-
-
-Remember,
->>> help(whatever)
-is your friend in Python, and
-$ man whatever
-and
-$ whatever --help
-are your friends in a shell.
+Unfold-protein
+==============
+
+Unfold-protein is a set of tools for controlling velocity-clamp single
+molecule force spectroscopy.  It uses the pyafm_ package for low level
+AFM control.  This package contains the high-level experiment control
+logic.
+
+Packages
+========
+
+Gentoo
+------
+
+I've packaged pyafm for Gentoo.  You need layman_ and my `wtk
+overlay`_.  Install with::
+
+  # emerge -av app-portage/layman
+  # layman --add wtk
+  # emerge -av sci-physics/unfold-protein
+
+Dependencies
+============
+
+Unfold-protein requires the following Python modules:
+
+* Pyafm_
+* Pypiezo_ (required directly, and via ``pyafm``)
+* H5config_ (required directly, and via ``pyafm``)
+* h5py_ (required directly, and via ``h5config``)
+* Matplotlib_
+* NumPy_
+
+Getting the source
+==================
+
+Unfold-protein is available as a Git_ repository::
+
+  $ git clone git://tremily.us/unfold-protein.git
+
+There are also periodic bundled releases.  For example, get version
+0.2 as a gzipped tarball with::
+
+  $ wget 'http://git.tremily.us/?p=unfold-protein.git;a=snapshot;h=v0.2;sf=tgz'
+  $ tar -xzvf unfold-protein-0.2.tar.gz
+
+Installation
+============
+
+After downloading, change to the source directory and run::
+
+  $ python setup.py install
+
+to install unfold-protein.  Run::
+
+  $ python setup.py install --help
+
+to see a list of installation options you may want to configure.
+
+Usage
+=====
+
+The ``unfold.py`` script runs a series of unfolding pulls while
+scanning the pulling velocity and contact position.  It has a few
+command line options; get details with::
+
+  $ unfold.py --help
+
+You can configure the unfolding and scanning behavior using h5config_.
+The configuration is stored in ``~/.config/unfold-default.yaml``.  To
+seed this configuration file before tweaking it, you should configure
+pyafm_ (as described in its ``README``).  Then run::
+
+  >>> import unfold_protein.storage as storage
+  >>> config = storage.get_default_config()
+  >>> storage.save_scan_config(config=config)
+
+to create a configuration using the default settings.  The YAML_
+syntax is plain text, which you can edit as you see fit.  Future runs
+of ``unfold.py`` (and calls to
+``unfold_protein.storage.load_scanner()``) will load this
+configuration by default.
+
+``unfold.py`` saves each unfolding pull in its own timestamped file
+with the unfolding data along with the complete configuration used to
+acquire it.  You can configure the directory where these files are
+stored with the ``unfold/save/base directory`` setting.  You can
+convert the saved unfolding data to PNGs__ with ``plot-unfold.py``.
+For example::
+
+  $ plot-unfold.py ~/rsrch/data/unfold/*.h5
+
+__ PNG_
+
+For more detailed analysis, you may want to use Hooke_.  You may also
+want to use calibcant_ to calibrate your AFM cantilever's bending
+spring constant.
+
+.. _pyafm: http://blog.tremily.us/posts/pyafm/
+.. _layman: http://layman.sourceforge.net/
+.. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
+.. _pyafm: http://blog.tremily.us/posts/pyafm/
+.. _pypiezo: http://blog.tremily.us/posts/pypiezo/
+.. _h5config: http://blog.tremily.us/posts/h5config/
+.. _H5Py: http://code.google.com/p/h5py/
+.. _NumPy: http://numpy.scipy.org/
+.. _Matplotlib: http://matplotlib.sourceforge.net/
+.. _Git: http://git-scm.com/
+.. _YAML: http://www.yaml.org/
+.. _PNG: http://en.wikipedia.org/wiki/Portable_Network_Graphics
+.. _Hooke: http://blog.tremily.us/posts/hooke/
+.. _calibcant: http://blog.tremily.us/posts/calibcant/