Merge pull request #1527 from jseabold/update-docs

DOCS: Update docs add FAQ page
statsmodels · Mar 28, 2014 · 80f7fa3 · 80f7fa3
2 parents e397e42 + dd3d82f
commit 80f7fa3
Show file tree

Hide file tree

Showing 15 changed files with 137 additions and 229 deletions.
diff --git a/docs/source/about.rst b/docs/source/about.rst
@@ -0,0 +1,57 @@
+.. currentmodule:: statsmodels
+
+*****************
+About Statsmodels
+*****************
+
+Background
+----------
+
+The ``models`` module of ``scipy.stats`` was originally written by Jonathan 
+Taylor. For some time it was part of scipy but was later removed. During
+the Google Summer of Code 2009, ``statsmodels`` was corrected, tested,
+improved and released as a new package. Since then, the statsmodels 
+development team has continued to add new models, plotting tools, and statistical methods.
+
+Testing
+-------
+
+Most results have been verified with at least one other statistical package:
+R, Stata or SAS. The guiding principal for the initial rewrite and for 
+continued development is that all numbers have to be verified. Some 
+statistical methods are tested with Monte Carlo studies. While we strive to
+follow this test driven approach, there is no guarantee that the code is 
+bug-free and always works. Some auxiliary function are still insufficiently 
+tested, some edge cases might not be correctly taken into account, and the 
+possibility of numerical problems is inherent to many of the statistical 
+models. We especially appreciate any help and reports for these kind of 
+problems so we can keep improving the existing models.
+
+Code Stability
+~~~~~~~~~~~~~~
+
+The existing models are mostly settled in their user interface and we do not
+expect many large changes going forward. For the existing code, although 
+there is no guarantee yet on API stability, we have long deprecation periods 
+in all but very special cases, and we try to keep changes that require 
+adjustments by existing users to a minimal level. For newer models we might
+adjust the user interface as we gain more experience and obtain feedback. 
+These changes will always be noted in our release notes available in the
+documentation.
+
+Financial Support
+-----------------
+
+We are grateful for the financial support that we obtained for the
+development of statsmodels:
+
+ Google `www.google.com <http://www.google.com/>`_ : Google Summer of Code
+ (GSOC) 2009-2013.
+
+ AQR `www.aqr.com <http://www.aqr.com/>`_ : financial sponsor for the work on
+ Vector Autoregressive Models (VAR) by Wes McKinney
+
+We would also like to thank our hosting providers, `github
+<http://github.com/>`_ for the public code repository, `sourceforge
+<http://sourceforge.net/>`_ for hosting our documentation and `python.org
+<http://python.org>`_ for making our downloads available on PyPi.
diff --git a/docs/source/anova.rst b/docs/source/anova.rst
@@ -31,7 +31,7 @@ A more detailed example can be found here:
 .. toctree::
   :maxdepth: 1
 
-  examples/generated/example_interactions
+  examples/notebooks/generated/interactions_anova
 
 Module Reference
 ----------------

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -75,8 +75,8 @@
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
-from statsmodels.version import version, full_version
-release = version
+from statsmodels.version import short_version, full_version
+release = short_version
 # The full version, including dev tag.
 version = full_version
 

diff --git a/docs/source/discretemod.rst b/docs/source/discretemod.rst
@@ -31,7 +31,8 @@ Detailed examples can be found here:
 .. toctree::
     :maxdepth: 2
 
-    examples/generated/example_discrete
+    examples/notebooks/generated/discrete_choice_overview
+    examples/notebooks/generated/discrete_choice_example
 
 Technical Documentation
 -----------------------

diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -0,0 +1,39 @@
+:orphan:
+
+.. _faq:
+
+Frequently Asked Question
+-------------------------
+
+.. _endog-exog-faq:
+
+What do endog and exog mean?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+These are shorthand for endogenous and exogenous variables. You might be more comfortable with the common ``y`` and ``X`` notation in linear models. Sometimes the endogenous variable ``y`` is called a dependent variable. Likewise, sometimes the exogenous variables ``X`` are called the independent variables. You can read about this in greater detail at :ref:`endog_exog` 
+
+
+.. _missing-faq:
+
+How does statsmodels handle missing data?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Missing data can be handled via the ``missing`` keyword argument. Every model takes this keyword. You can find more information in the docstring of :class:`statsmodels.base.Model`. 
+
+.. `Model class <http://statsmodels.sourceforge.net/devel/dev/generated/statsmodels.base.model.Model.html#statsmodels.base.model.Model>`_.
+
+.. _build-faq:
+
+Why won't statsmodels build?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you're on Python 3.4, you *must* use Cython 0.20.1. If you're still having problems, try running
+
+.. code-block:: bash
+
+    python setup.py clean
+
+What if my question isn't answered here?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You may find answers for questions that have not yet been added here on GitHub under the `FAQ issues tag <https://github.com/statsmodels/statsmodels/issues?labels=FAQ&page=1&state=open>`_. If not, please ask your question on stackoverflow using the `statsmodels tag <https://stackoverflow.com/questions/tagged/statsmodels>`_ or on the `mailing list <https://groups.google.com/forum/#!forum/pystatsmodels>`_.
diff --git a/docs/source/glm.rst b/docs/source/glm.rst
@@ -29,7 +29,8 @@ Detailed examples can be found here:
 .. toctree::
    :maxdepth: 1
 
-   examples/generated/example_glm
+   examples/notebooks/generated/glm
+   examples/notebooks/generated/glm_formula
 
 Technical Documentation
 -----------------------

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -64,12 +64,12 @@ Basic Documentation
 .. toctree::
     :maxdepth: 3
 
-    introduction
     release/index
     gettingstarted
     example_formulas
     install
     related
+    about
 
 Information about the structure and development of
 statsmodels:

diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst
diff --git a/docs/source/regression.rst b/docs/source/regression.rst
@@ -35,9 +35,9 @@ Detailed examples can be found here:
 .. toctree::
    :maxdepth: 1
 
-   examples/generated/example_ols
-   examples/generated/example_wls
-   examples/generated/example_gls
+   examples/notebooks/generated/ols
+   examples/notebooks/generated/wls
+   examples/notebooks/generated/gls
 
 Technical Documentation
 -----------------------

diff --git a/docs/source/release/version0.6.rst b/docs/source/release/version0.6.rst
@@ -33,21 +33,21 @@ covariates.
 
 .. code-block:: python
 
-import numpy as np
-import pandas as pd
-from statsmodels.genmod.generalized_estimating_equations import GEE
-from statsmodels.genmod.dependence_structures import Independence
-from statsmodels.genmod.families import Poisson
-
-data_url = "http://vincentarelbundock.github.io/Rdatasets/csv/MASS/epil.csv"
-data = pd.read_csv(data_url)
-
-fam = Poisson()
-ind = Independence()
-md1 = GEE.from_formula("y ~ age + trt + base", data, groups=data["subject"],\
-                       covstruct=ind, family=fam)
-mdf1 = md1.fit()
-print mdf1.summary()
+   import numpy as np
+   import pandas as pd
+   from statsmodels.genmod.generalized_estimating_equations import GEE
+   from statsmodels.genmod.dependence_structures import Independence
+   from statsmodels.genmod.families import Poisson
+   
+   data_url = "http://vincentarelbundock.github.io/Rdatasets/csv/MASS/epil.csv"
+   data = pd.read_csv(data_url)
+   
+   fam = Poisson()
+   ind = Independence()
+   md1 = GEE.from_formula("y ~ age + trt + base", data, groups=data["subject"],\
+                          covstruct=ind, family=fam)
+   mdf1 = md1.fit()
+   print mdf1.summary()
 
 
 The dependence structure in a GEE is treated as a nuisance parameter