DOCS: Update docs add FAQ page #1527

Merged
merged 5 commits into from Mar 28, 2014

Projects

None yet

2 participants

@jseabold
Member

This will close #1311, #1450, and #1526.

I added an FAQ page. I updated the introduction page and removed the redundant and out of date stuff. It seems more like an about page, so I renamed it.

Fixed some broken links and formatting issues.

@josef-pkt josef-pkt commented on an outdated diff Mar 28, 2014
docs/source/faq.rst
+-------------------------
+
+.. _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 te ``missing`` keyword argument. Every model takes this keyword. You can find more information in the docstring of :class:`statsmodels.base.Model`.
@josef-pkt
josef-pkt Mar 28, 2014 Member

te -> the

@josef-pkt josef-pkt commented on an outdated diff Mar 28, 2014
docs/source/faq.rst
+
+.. _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 there or on the `mailing list <https://groups.google.com/forum/#!forum/pystatsmodels>`_.
@josef-pkt
josef-pkt Mar 28, 2014 Member

please ask your question there might misuse our issue tracker
It would be good to have a central location for frequently asked question, but basic usage questions would be better on stackoverflow or the mailing list.

@josef-pkt josef-pkt commented on an outdated diff Mar 28, 2014
docs/source/about.rst
+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. 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.
@josef-pkt
josef-pkt Mar 28, 2014 Member

I'm not sure this doesn't sound to strong.

I think we are not at the stage of scipy, where Ralf enforces immediate deprecation requirement for any new code.

I had added this before

New models that have just been
 -included might require adjustments as we gain more experience and obtain
 -feedback by users. As we expand the range of models, we keep improving the
 -framework for different estimators and statistical tests, so further changes
 -will be necessary.

???

@josef-pkt josef-pkt commented on an outdated diff Mar 28, 2014
docs/source/about.rst
+~~~~~~~~~~~~~~
+
+The existing models are mostly settled in their user interface and we do not
+expect many large changes going forward. 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.
+
+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-2014
@josef-pkt
josef-pkt Mar 28, 2014 Member

2009-2013 we don't have 2014 yet (but I think we will)

@josef-pkt
Member

looks good

my comment for #1526 was "I'm in favor of radical trimming, and update what's left over."
since I didn't hit enter it's already done before my comment

One thought I had was to turn "about" into something that could go into a press release or Wikipedia, but without the duplicated table of content (that you deleted).
code stability could go somewhere else, maybe

eventually some place with a list of users of statsmodels would also be good. (only we don't know much who does)

@jseabold
Member

On Thu, Mar 27, 2014 at 8:51 PM, Josef Perktold notifications@github.comwrote:

eventually some place with a list of users of statsmodels would also be
good. (only we don't know much who does)

We should definitely solicit quotes from industry types who are using. I
know there are some that I've spoken too. I'll be giving some talks here in
DC on statsmodels in April. I'll ask people to let us know.

@jseabold
Member

Addressed comments.

@jseabold
Member

It occurred to me that we'll eventually need an FAQ by topic. E.g., causes of estimation difficulties in ARMA. P-values in RLM, etc.

@jseabold
Member

Merging this.

@jseabold jseabold merged commit 80f7fa3 into statsmodels:master Mar 28, 2014

1 check passed

default The Travis CI build passed
Details
@jseabold jseabold deleted the jseabold:update-docs branch Mar 28, 2014
@josef-pkt josef-pkt added the PR label Apr 14, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment