What goes in statsmodels.formula.api?

[jseabold]

Should we split the API into statsmodels the helpers and statsmodels the models?

This would mean that statsmodels/api.py is

from statsmodels._helper_api import *
from statsmodels._model_api import *

and statsmodels/formula/api.py is

# the usual formula wrappers
from statsmodels._helper_api import *

I ask because we have a notebook right now that has

import statsmodels.formula.api as sm

As soon as I start to do sm.data<TAB> I realized the issue here. Mostly we've just been explicitly import from statsmodels.formula.api, but this might get tedious. Thoughts?

[jseabold]

Alternatively, we bite the bullet and put all the formula stuff in the main api with the convention that lowercase is formula uppercase is y/X.

[jseabold]

I don't think this has been publicly exposed, but this is actually what it's documented to be here:

http://nbviewer.ipython.org/urls/raw.github.com/statsmodels/statsmodels/master/examples/ipynb/example_formulas.ipynb

[josef-pkt]

We never really discussed formula.api.

(repeating you since I didn't see your comment initially)
Currently there is no overlap in the names, upper case/capitalized versus lower case
If we stick with non-overlapping names, then we could just import the formula models into the statsmodels.api
I think this will work, and be the most convenient for users

The example_formulas.ipynb needs to be changed.
I often use smxxx to indicate an imported subpackage, so maybe we could change the recommended import to smf (if we want an explicit list of formula models, additional to having them in the statsmodels.api)

import statsmodels.api as sm
import statsmodels.formula.api as smf

[jseabold]

Yeah I'm cleaning up that notebook now. Somewhat Devil's advocate. I still kind of like the formula signpost, so maybe even

import statsmodels.api as sm
sm.formula.ols(...)

?

[jseabold]

Actually, I think that's my vote now. So we leave the status quo, but also import formula.api as formula into statsmodels.api?

[josef-pkt]

It would be more explicit (and I like explicitness), but I guess it won't survive in practise because it's too wordy for basic, very frequently used functions.

Even if it's easy to get with tab completion, it would also look wordy in documentation, examples, blog posts, ...

Trying to explain the difference between lower and upper case names might not be trivial either.

[jseabold]

Yeah I'm trying to imagine being a new user and I don't like ols and OLS living side by side. I think sm.formula works since you can still import directly from formula.api (or just import this as smf) if it's too wordy. I think it's okay if we just document a few easy to remember conventions like this.

[josef-pkt]

(Internet explorer doesn't autoupdate, so I'm always running behind your comments)

Actually, I think that's my vote now. So we leave the status quo, but also import formula.api as formula into statsmodels.api?

Fine with me, but change the notebook to import statsmodels.formula.api as smf to establish a convention ?

[jseabold]

Sounds good. You should look into a modern browser ;)

[josef-pkt]

http://www.youtube.com/watch?v=-ZxHAZChcYU

[josef-pkt]

I have IIE, FF and Chrome open, but FF which is my _over_used browser is embarrassed "Well, this is embarrassing."