doc changes

Author: jsalvatier

pymc/model.py

@@ -39,6 +39,22 @@ def get_context(cls):
             raise TypeError("No context on context stack")
 
 def withcontext(contexttype, argname):
+    """
+    Returns a decorator for wrapping functions so they look for an argument in a specific argument slot. 
+    If not found, the decorated function searches the for a context and inserts it in that slot. 
+
+    Parameters
+    ----------
+    contexttype : type
+        The type of context to search for
+    argname : string
+        The name of the argument slot where the context should go
+
+    Returns 
+    -------
+    decorator function
+
+    """
     def decorator(fn):
         n = list(fn.func_code.co_varnames).index(argname)
 
@@ -83,20 +99,25 @@ def logp(model):
 
     @property
     def logpc(model): 
+        """Compiled log probability density function"""
         return compilef(model.logp)
 
     def dlogpc(model, vars = None): 
+        """Compiled log probability density gradient function"""
         return compilef(gradient(model.logp, vars))
 
     def d2logpc(model, vars = None):
+        """Compiled log probability density hessian function"""
         return compilef(hessian(model.logp, vars))
 
     @property
     def test_point(self):
+        """Test point used to check that the model doesn't generate errors"""
         return Point(self, ((var, var.tag.test_value) for var in self.vars))
 
     @property
     def cont_vars(model):
+        """All the continuous variables in the model"""
         return typefilter(model.vars, continuous_types) 
 
     """
@@ -144,6 +165,18 @@ def Point(model, *args,**kwargs):
 
 
 def compilef(outs, mode = None):
+    """
+    Compiles a Theano function which returns `outs` and takes the variable ancestors of `outs` as inputs.
+
+    Parameters
+    ----------
+    outs : Theano variable or iterable of Theano variables
+    mode : Theano compilation mode
+    
+    Returns
+    -------
+    Compiled Theano function
+    """
     return PointFunc(
                 function(inputvars(outs), outs, 
                          allow_input_downcast = True, 

pymc/sample.py

@@ -18,6 +18,7 @@ def sample(model, draws, step, start = None, trace = None, track_progress = True
     Parameters
     ----------
         
+    model : Model (optional if in `with` context)
     draws : int  
         The number of samples to draw
     step : function

pymc/tuning/scaling.py

@@ -10,23 +10,23 @@
 __all__ = ['approx_hess', 'find_hessian', 'trace_cov']
 
 @withmodel
-def approx_hess(model, start, vars=None):
+def approx_hess(model, point, vars=None):
     """
     Returns an approximation of the Hessian at the current chain location.
     
     Parameters
     ----------
-    model : Model
-    start : dict
-    vars : list or array
+    model : Model (optional if in `with` context)
+    point : dict
+    vars : list 
         Variables for which Hessian is to be calculated.
     """
     if vars is None :
         vars = model.cont_vars
 
-    start = Point(model, start)
+    point = Point(model, point)
 
-    bij = DictToArrayBijection(ArrayOrdering(vars), start)
+    bij = DictToArrayBijection(ArrayOrdering(vars), point)
     dlogp = bij.mapf(model.dlogpc(vars))
 
 
@@ -38,18 +38,39 @@ def grad_logp(point):
     this should be the Hessian; invert it to find the approximate 
     covariance matrix.
     '''
-    return -nd.Jacobian(grad_logp)(bij.map(start))
+    return -nd.Jacobian(grad_logp)(bij.map(point))
 
 @withmodel
 def find_hessian(model, point, vars = None): 
+    """
+    Returns Hessian of logp at the point passed.
+    
+    Parameters
+    ----------
+    model : Model (optional if in `with` context)
+    point : dict
+    vars : list 
+        Variables for which Hessian is to be calculated.
+    """
     H = model.d2logpc(vars)
     return H(Point(model, point))
 
 def trace_cov(trace, vars = None):
     """
     Calculate the flattened covariance matrix using a sample trace
 
-    Useful if you want to base your covariance on some initial samples.
+    Useful if you want to base your covariance matrix for further sampling on some initial samples.
+
+    Parameters
+    ----------
+    trace : Trace 
+    vars : list 
+        variables for which to calculate covariance matrix
+
+    Returns 
+    -------
+    r : array (n,n)
+        covariance matrix
     """
 
     if vars is None: 

pymc/tuning/starting.py

@@ -20,9 +20,9 @@ def find_MAP(model, start = None, vars=None, fmin = optimize.fmin_bfgs, return_r
     
     Parameters
     ----------
-    model : Model
+    model : Model (optional if in `with` context)
     start : dict of parameter values (Defaults to model.test_point)
-    vars : list or array
+    vars : list 
         List of variables to set to MAP point (Defaults to all continuous).
     fmin : function
         Optimization algorithm (Defaults to `scipy.optimize.fmin_l_bfgs_b`).