QUB Express
    Markov modeling of ion channels (and other molecules)
              www.qub.buffalo.edu

We describe the behavior of a single molecule with boxes and arrows (the Model area, at bottom).
The molecule is in one "state" (box) at any given time, and it will change state along one of the arrows
about once every x seconds, where x is the "rate constant" number written along the arrow.  The molecule
is measured with something like a patch clamp, which reports the amount of current flowing through the
molecule.  If two states in the model have the same color ("Class"), they measure the same.  Black is traditionally
zero/nonconducting/closed.

Above the model, the Tables control everything in the model.  To edit a rate constant, first click
it in the model; it will be highlighted in the Tables. (sometimes you have to click twice)
Then type a new number into the table and press Enter.  In the Classes table, you can change the
amplitude distributions for each color.

The middle panel shows data simulated from the model, or you can use the blue File menu to open a data file.
It's laid out like an oscilloscope.  The controls at top-left can be edited by clicking then typing in
the Tables, or with the scroll wheel.  Magenta is the center value.  Green is the distance per division.
Click '?' to bring all data on-screen.  The tools along the right control the mouse behavior -- by default,
dragging with the mouse will zoom in.

The floating triangles in the Model and Data are menus.  Try clicking on them.

This top panel has various functions:  The Tools tab includes data extractino, CurveFit and Idealization utilities.
The Simulation tab controls the sampling rate and other parameters, and lets you build stimulus protocols.
The Modeling tab idealizes and finds optimal rate constants for the data (see below).  The Figures tab has
visualizations of Data and Tables.  Admin provides Notebook, Plugins, Scripts, and Settings, including custom colors.

Figures:Charts can plot information from the Tables.  You can click to group points by color ("Group" column),
or cluster them automatically with X-Means.  To build a new table, or load it from a file, use the main menu
(triangle at upper-left of the window).  If you have colored the Segments table, use Tools:Extract
to save just one color of segments in a new data file for further analysis.

At top right, the Stop Tasks button glows red when a background task is running.  Below are panes of
context-sensitive info; for example, a list of running tasks, the mouse coordinates in the Data,
and histogram options.

Many panels have a notebook icon.  Clicking it shows a menu of figures for export.  By default,
they are appended to a web-ready HTML file.  Some figures are exported automatically, e.g. after
a computation.  To customize your notebook, use the Admin:Notebook panel.

  * To make a rate constant sensitive to a variable such as Voltage:  click on the rate, and in the table
find the cell for e.g. Voltage and enter a name like "Voltage" or "V".  For Voltage-sensitivity, set k1 nonzero.
Now you can adjust its constant value, under Simulation, or click "[vary]" and set up a protocol.

  * To optimize rate constants, and other model parameters:
      The macroscopic plugin (Modeling:MacRates) can optimize rates, amplitude distributions, and channel count;
      from recordings with at least several dozen molecules.
      Theory here: Milescu LS, Akk G, Sachs F. Maximum likelihood estimation of ion channel kinetics from
                   macroscopic currents. Biophys J. 2005 Apr; 88(4):2494-515.
   - open a data file: .txt, .abf, .qdf, or raw binary, using the file menu (blue triangle) in the data panel
   - set up a simple model, with a rough estimate of channel count, amplitudes etc., and any stimulus dependence
   - look in Modeling:Stimulus, to make sure the model's stimulus is mapped to the correct data channel
   - look at the data panel: if the stimulus isn't well outlined in red, adjust the Stimulus settings
   - go to Modeling:MacRates, and click "Get LL"
   - check "live" to re-do the fit curve and LL each time you change the model
   - click "Optimize" to adjust model parameters to improve the fit
   - adjust optimization parameters, if needed, in the right-hand column
   - to constrain rate(s), e.g. to keep a constant ratio between two rates, right-click a rate and "Add constraint"

   * To optimize rate constants from a single-molecule recording:
       use tools from the single molecule plugin: Modeling:Idealize, Modeling:Rates, and Charts:DurHist
   - open a data file
   - make a new (2 state) model, right-click one of the states, and "Grab all amps";
     (follow the instructions in the Data panel)
   - go to Modeling:Idealize and click Idealize;  make sure the red idealized trace matches the data
   - go to Modeling:Rates and click Optimize
   - refer to Charts:DurHist to see how well the data is fit by the model (pdf fit curve generated from model params)
   - experiment with different numbers of states, and connection schemes, to get the best LL and fit
   - for stimulus-dependent models:
         - before or after idealizing, check Modeling:Stimulus as in the MacRates instructions (above)


Build and install:
    see INSTALL.txt

License:
    GPLv3 -- see LICENSE.txt

If there's a feature you need, please write to qub@www.qubx.buffalo.edu so we can make it a higher priority.
For full source code:

> git clone http://www.qub.buffalo.edu/qub-express.git