Merge pull request #2789 from ericmjl/patch-1

Parameterization docs fix for precision/standard deviations.

Author: fonnesbeck

pymc3/distributions/continuous.py

@@ -269,9 +269,17 @@ class Normal(Continuous):
     mu : float
         Mean.
     sd : float
-        Standard deviation (sd > 0).
+        Standard deviation (sd > 0) (only required if tau is not specified).
     tau : float
-        Precision (tau > 0).
+        Precision (tau > 0) (only required if sd is not specified).
+        
+    Examples
+    --------
+    with pm.Model():
+        x = pm.Normal('x', mu=0, sd=10)
+        
+    with pm.Model():
+        x = pm.Normal('x', mu=0, tau=1/23)
     """
 
     def __init__(self, mu=0, sd=None, tau=None, **kwargs):
@@ -348,9 +356,17 @@ class HalfNormal(PositiveContinuous):
     Parameters
     ----------
     sd : float
-        Standard deviation (sd > 0).
+        Standard deviation (sd > 0) (only required if tau is not specified).
     tau : float
-        Precision (tau > 0).
+        Precision (tau > 0) (only required if sd is not specified).
+        
+    Examples
+    --------
+    with pm.Model():
+        x = pm.HalfNormal('x', sd=10)
+    
+    with pm.Model():
+        x = pm.HalfNormal('x', tau=1/15)
     """
 
     def __init__(self, sd=None, tau=None, *args, **kwargs):
@@ -838,8 +854,19 @@ class Lognormal(PositiveContinuous):
     ----------
     mu : float
         Location parameter.
+    sd : float
+        Standard deviation. (sd > 0). (only required if tau is not specified).
     tau : float
-        Scale parameter (tau > 0).
+        Scale parameter (tau > 0). (only required if sd is not specified).
+        
+    Example
+    -------
+    # Example to show that we pass in only `sd` or `tau` but not both.
+    with pm.Model():
+        x = pm.Lognormal('x', mu=2, sd=30)
+
+    with pm.Model():
+        x = pm.Lognormal('x', mu=2, tau=1/100)
     """
 
     def __init__(self, mu=0, sd=None, tau=None, *args, **kwargs):
@@ -930,8 +957,18 @@ class StudentT(Continuous):
         Degrees of freedom, also known as normality parameter (nu > 0).
     mu : float
         Location parameter.
+    sd : float
+        Standard deviation (sd > 0) (only required if lam is not specified)
     lam : float
-        Scale parameter (lam > 0).
+        Precision (lam > 0) (only required if sd is not specified)
+        
+    Examples
+    --------
+    with pm.Model():
+        x = pm.StudentT('x', nu=15, mu=0, sd=10)
+        
+    with pm.Model():
+        x = pm.StudentT('x', nu=15, mu=0, lam=1/23)
     """
 
     def __init__(self, nu, mu=0, lam=None, sd=None, *args, **kwargs):
@@ -1589,9 +1626,19 @@ class HalfStudentT(PositiveContinuous):
         Degrees of freedom, also known as normality parameter (nu > 0).
     sd : float
         Scale parameter (sd > 0). Converges to the standard deviation as nu
-        increases
+        increases. (only required if lam is not specified)
     lam : float
-        Scale parameter (lam > 0). Converges to the precision as nu increases
+        Scale parameter (lam > 0). Converges to the precision as nu
+        increases. (only required if sd is not specified)
+        
+    Examples
+    --------
+    # Only pass in one of lam or sd, but not both.
+    with pm.Model():
+        x = pm.HalfStudentT('x', sd=10, nu=10)
+ 
+    with pm.Model():
+        x = pm.HalfStudentT('x', lam=4, nu=10)
     """
     def __init__(self, nu=1, sd=None, lam=None, *args, **kwargs):
         super(HalfStudentT, self).__init__(*args, **kwargs)

pymc3/distributions/timeseries.py

@@ -81,9 +81,9 @@ class AR(distribution.Continuous):
     rho : tensor
         Vector of autoregressive coefficients.
     sd : float
-        Standard deviation of innovation (sd > 0).
+        Standard deviation of innovation (sd > 0). (only required if tau is not specified)
     tau : float
-        Precision of innovation (tau > 0).
+        Precision of innovation (tau > 0). (only required if sd is not specified)
     constant: bool (optional, default = False)
         Whether to include a constant.
     init : distribution
@@ -137,12 +137,12 @@ class GaussianRandomWalk(distribution.Continuous):
 
     Parameters
     ----------
-    tau : tensor
-        tau > 0, innovation precision
-    sd : tensor
-        sd > 0, innovation standard deviation (alternative to specifying tau)
     mu: tensor
         innovation drift, defaults to 0.0
+    sd : tensor
+        sd > 0, innovation standard deviation (only required if tau is not specified)
+    tau : tensor
+        tau > 0, innovation precision (only required if sd is not specified)
     init : distribution
         distribution for initial value (Defaults to Flat())
     """