Add 'docs/python/' from commit '4b2d220e7dc8d1f233d738399b631fbd8d859…

…e9f'

git-subtree-dir: docs/python
git-subtree-mainline: 4e102a9
git-subtree-split: 4b2d220

docs/python/analysis/guitools.rst

@@ -0,0 +1,10 @@
+GUI Analysis Tools
+------------------
+
+.. toctree::
+    :maxdepth: 3
+
+    guitools/funfit.rst
+    guitools/runfit.rst
+    guitools/mulfit.rst
+    guitools/impedancetools.rst

docs/python/analysis/guitools/funfit.rst

@@ -0,0 +1,131 @@
+.. _funfit:
+
+
+FunctionFitter
+--------------
+
+A widget for graphing a parameterized function while exploring parameter 
+variations. Also can adjust the parameters automatically to fit data. 
+Function, parameters, independent variable can be specified by the user. 
+This widget may be saved in a session. 
+
+The FunctionFitter starts out with entries for graphing a single exponential 
+with two parameters.  When a parameter value is changed the graph is replotted. 
+
+Plot
+~~~~
+
+Replots function with current arg values 
+
+Steps
+~~~~~
+
+Number of values of independent variable used in plot 
+
+IndependentVar
+~~~~~~~~~~~~~~
+
+Enter the name of independent variable in a 
+string dialog.
+
+Args
+~~~~
+
+Enter space separated names of parameters in a string dialog. 
+Default value editors for these parameters will appear in the rightmost 
+box. 
+
+Yexpr
+~~~~~
+
+Enter an expression involving the independent variable and the 
+parameters (args). Any valid top level hoc expression is acceptable. 
+
+PraxisFit
+~~~~~~~~~
+
+Starts fitting the function to the data with respect to the DataWeights 
+by adjusting the checked argument values. See :func:`fit_praxis` . 
+
+StopAtNextQuadForm
+~~~~~~~~~~~~~~~~~~
+
+Stop the praxis fitter when it finishes its current/next cycle. 
+At this point it contains a computation of the quadratic form of the parameter 
+phase space (printed in the terminal window). 
+
+Running
+~~~~~~~
+
+Checked when the praxis fitter is executing. 
+
+WatchTheFit
+~~~~~~~~~~~
+
+Plot the function on each call to the error function during fitting. 
+Things are slower if this box is checked. 
+
+RoughFit
+~~~~~~~~
+
+Instead of fitting all the data according to the data weights, use 
+only 5 equally spaced points in each of the two central data regions. 
+Things can be much faster if this box is checked. 
+
+ArgValues
+~~~~~~~~~
+
+The values of the arguments are used in the plot. When a value 
+is changed the function is replotted. When fit data is present, a 
+checkbox is added to the left of each argument button. When the box is checked 
+then the fitter adjusts the value for a best fit. When not checked the parameter 
+is treated as a constant. 
+
+CurrentValuesAsDefault
+======================
+
+Resets the default values of the parameter field editors to their current values. 
+
+
+FittoData
+~~~~~~~~~
+
+
+ReadDataFile
+============
+
+Get data from a file. The format is the number of data points followed 
+by pairs of x,y data. 
+
+CommonFunctionalForms
+=====================
+
+
+FitCriterion
+============
+
+not implemented 
+
+ParameterRangeLimits
+====================
+
+Pops up a panel of parameters with their range limits. When 
+the fitter calls the error function and one of the parameters is 
+outside its range the error function will return a value of 1e6. 
+
+DataWeights
+===========
+
+Pops up a panel of data weight intervals and weights. The first interval 
+ranges from the beginning of the data to the interval 1 endpoint. From 
+the interval3 endpoint to the end of the data, the weight is 0. The entire 
+interval is given the weight indicated. Intervals can be manipulated directly 
+by the :guilabel:`AdjustWeightRegions` tool of the :guilabel:`Graph` menu. 
+
+SaveRestoreFunction
+===================
+
+Arg values and the y-expression can be saved in a list and restored by selection 
+with a browser. 
+
+

docs/python/analysis/guitools/impedancetools.rst

@@ -0,0 +1,71 @@
+.. _attshape:
+
+.. seealso: :ref:`impratio`, :ref:`impedance_impx`, :ref:`impedance_logavsx`, 
+
+
+Impedance Tools
+---------------
+
+These tools plot various functions of :class:`Impedance` vs 
+location and frequency. :ref:`impshape` is described below, but see also:
+
+.. toctree:: :maxdepth: 1
+
+    impratio.rst
+    impedanx.rst
+
+
+Each tool has three panels: The top 
+panel contains button and menu controls specific to the tool. The 
+middle panel displays a picture of the cell and marks the measurement 
+and injection sites. The bottom panel displays the results of the 
+impedance measurements. 
+
+The redraw button in the top panel forces a re-calculation of the results. 
+This is useful if a parameter or state changes in the underlying model 
+of the cell. The :menuselection:`Extras --> MovieMode` menu item recalculated the results 
+for each step during a :ref:`runcontrol_initrun`. When selected, 
+the :menuselection:`Extras --> AutoScale` rescales 
+the results panel after each calculation. 
+
+The :guilabel:`Plot` menu specifies whether to plot log attenuation (default), 
+input impedance, transfer impedance, or ``V(measure)/V(inject)``
+Note: log attenuation is defined as ``ln( V(inject)/V(measure) )``
+Input impedance is plotted with 
+respect to the measurement site and the injection site is unused. 
+
+
+.. _impshape:
+
+ImpShape
+~~~~~~~~
+
+Tool for generating the neuromorphic rendering, a picture of the 
+neuron in which distance is scaled to represent the log of 
+voltage attenuation. In this transform, 
+long distance represents large attenuation. 
+
+The tool consists of three panels. The middle panel shows the normal 
+unscaled shape of the neuron on which the user can select a measurement/injection 
+site (default location is location 0 of the currently accessed section 
+when the ImpShape object was created). The lower panel displays 
+a neuromorphic rendering along with a unit attenuation scale bar. 
+The upper control panel allows selection of the frequency at which to 
+calculate the impedance and the direction of current flow, ``Vin/Vout``, 
+with respect 
+to the measurement/injection site. 
+
+When :guilabel:`Vin` is selected one can imagine that 
+for every point on the cell, that point is voltage clamped to 1 mV and 
+the voltage at the measurement site (0 end of the selected section in 
+the lower panel) is recorded. The shape of the neuron 
+is then plotted so that the distance between the 
+voltage clamp site and the measurement site is the natural 
+log of the attenuation 
+factor, ``ln( V(inject)/V(measure) )``
+
+When :guilabel:`Vout` is selected, one can imagine that the selected position 
+becomes voltage clamped to 1mV and the voltage at every other position 
+on the cell is measured. 
+
+

docs/python/analysis/guitools/impedanx.rst

@@ -0,0 +1,70 @@
+.. _impedanx:
+
+.. _impedance_impx:   
+
+Impx
+----
+
+
+Tool for plotting voltage attenuation at a specific measurement/injection 
+site as 
+a function of selected path along the neuron at each point of which 
+current is injected/measured. 
+
+Frequency (Hz) of injected current is specified in the "frequency" field 
+editor. 
+
+The measurement/injection site is selected by first selecting the 
+:guilabel:`measure/inject` item of the :guilabel:`SelectLocation` menu and then selecting a 
+location on the neuron in the middle panel.  A red dot denotes the 
+measurement (Vin mode) location or the injection location (Vout mode). 
+The end points of the path are selected by first 
+selecting the "path start" or "path end" menu items and then selecting a 
+location on the neuron in the middle panel. 
+
+The Vin and Vout radio buttons select whether the independent variable 
+in the results panel refers to injection position or measurement 
+position along the selected path. 
+The x=0 coordinate in the results section refers to the point on the 
+path that is closest to the root of the cell (The root is normally the 
+soma). Negative abscissa values are on the path start side and 
+positive values are on the path end side. 
+
+This tool uses the :class:`Impedance` class to calculate voltage 
+attenuations. 
+
+
+.. _impedance_logavsx:
+
+LogAvsX
+-------
+
+
+Tool for plotting voltage attenuation at a specific measurement/injection 
+site as a function of Every point on the cell where current is 
+injected/measured. Abscissa in the results panel shows the distance 
+of every point from the root of the cell (usually soma(0)). 
+
+When the Vin radio button is selected the measurement site is fixed 
+(red dot) and the independent variable is the location of the injection 
+site. When Vout is selected, the independent variable is the measurement 
+location and the red dot refers to the fixed injection site. 
+
+In order to identify a particular section in the morphology panel 
+with a particular line segment in the results panel one can: 
+
+1)  In the results panel use the graph menu (right mouse button) to select 
+    the "ShowPosition" item. Then click (left mouse button) near the 
+    beginning, end, or segment center of one of the lines. This will color red both 
+    the line and the corresponding morphology section. 
+
+2)  The meaning of the Section menu item in the morphology panel is 
+    determined by the :guilabel:`ShapeSelectAction` menu item in the control panel. 
+    When :guilabel:`MoveElectrode` is selected (and the Section menu item tool is also selected) 
+    clicking on a section of the cell, changes the location of the 'fixed' 
+    measurement/injection site (red dot). When :guilabel:`ShowPosition` is selected, 
+    clicking on a section will color both the section and the corresponding 
+    line in the results panel. 
+
+.. image:: ../../images/impedanx-logavsx.png
+    :align: center  

docs/python/analysis/guitools/impratio.rst

@@ -0,0 +1,25 @@
+.. _impratio:
+
+
+ImpedanceRatio
+--------------
+
+Tool for plotting voltage attenuation or impedance at a specific measurement and 
+injection site as a function of log frequency from 0.1 to 1000 Hz. 
+
+The measurement site is selected by first selecting the :guilabel:`SelectMeasure` item 
+of the :guilabel:`SelectLocation` menu and then selecting a location on the neuron 
+in the middle panel. A red dot denotes the measurement location. 
+The injection site is selected by via selection of the :guilabel:`SelectInject` menu item. 
+Measurement and injection sites are indicated by red and blue dots respectively. 
+The :guilabel:`SwapMeasure/Inject` menu item swaps the measurement and injection sites. 
+
+The :guilabel:`Plot` menu specifies whether to plot log attenuation (default), 
+input impedance, transfer impedance, or ``V(measure)/V(inject)``. 
+Input impedance is plotted with 
+respect to the measurement site and the injection site is unused. 
+
+This tool uses the :class:`Impedance` 
+class to calculate voltage attenuations. 
+
+