Flesh out examples included in docstrings

[bmu]

.../pandas$ nosetests -v --with-doctest -I .*test
/.../.virtualenvs/myenv/local/lib/python2.7/site-packages/scikits/statsmodels/__init__.py:2: UserWarning: scikits.statsmodels namespace is deprecated and will be removed in 0.5, please use statsmodels instead
  warnings.warn('scikits.statsmodels namespace is deprecated and will be '
/.../.virtualenvs/myenv/local/lib/python2.7/site-packages/scikits/statsmodels/regression/__init__.py:2: UserWarning: scikits.statsmodels namespace is deprecated and will be removed in 0.5, please use statsmodels instead
  warnings.warn('scikits.statsmodels namespace is deprecated and will be '
Doctest: pandas.compat.scipy.percentileofscore ... ok
Doctest: pandas.compat.scipy.rankdata ... FAIL
Doctest: pandas.compat.scipy.scoreatpercentile ... FAIL
Doctest: pandas.core.algorithms.quantile ... ok
Doctest: pandas.core.common.iterpairs ... FAIL
Doctest: pandas.core.common.split_ranges ... ok
Doctest: pandas.core.format.EngFormatter.__call__ ... FAIL
Doctest: pandas.core.frame.DataFrame.__init__ ... FAIL
Doctest: pandas.core.frame.DataFrame.apply ... FAIL
Doctest: pandas.core.frame.DataFrame.combine_first ... FAIL
Doctest: pandas.core.frame.DataFrame.merge ... FAIL
Doctest: pandas.core.frame.DataFrame.pivot ... FAIL
Doctest: pandas.core.frame.DataFrame.reindex ... FAIL
Doctest: pandas.core.frame.DataFrame.reindex_axis ... FAIL
Doctest: pandas.core.frame.DataFrame.set_index ... FAIL
Doctest: pandas.core.frame.DataFrame.sort ... FAIL
Doctest: pandas.core.frame.DataFrame.sort_index ... FAIL
Doctest: pandas.core.frame.DataFrame.stack ... FAIL
Doctest: pandas.core.frame.DataFrame.to_excel ... FAIL
Doctest: pandas.core.frame.DataFrame.unstack ... FAIL
Doctest: pandas.core.frame.DataFrame.xs ... FAIL
Doctest: pandas.core.generic.PandasObject.groupby ... FAIL
Doctest: pandas.core.groupby.NDFrameGroupBy.transform ... FAIL
Doctest: pandas.core.groupby.SeriesGroupBy.aggregate ... FAIL
Doctest: pandas.core.groupby.SeriesGroupBy.transform ... FAIL
Doctest: pandas.core.index.Index.diff ... FAIL
Doctest: pandas.core.index.Index.get_indexer ... FAIL
Doctest: pandas.core.index.MultiIndex.get_indexer ... FAIL
Doctest: pandas.core.indexing._SeriesIndexer ... FAIL
Doctest: pandas.core.panel.WidePanel.transpose ... FAIL
Doctest: pandas.core.panel.panel_index ... FAIL
Doctest: pandas.core.reshape._Unstacker ... FAIL
Doctest: pandas.core.reshape.lreshape ... FAIL
Doctest: pandas.core.reshape.melt ... FAIL
Doctest: pandas.core.series.Series.map ... FAIL
Doctest: pandas.core.series.Series.rename ... FAIL
Doctest: pandas.core.series.Series.sort_index ... FAIL
Doctest: pandas.core.series.Series.unstack ... FAIL
Doctest: pandas.core.strings.StringMethods ... FAIL
Failure: ImportError (No module named httplib2) ... ERROR
Doctest: pandas.io.data.Options ... FAIL
Doctest: pandas.io.data.Options.get_call_data ... FAIL
Doctest: pandas.io.data.Options.get_options_data ... FAIL
Doctest: pandas.io.data.Options.get_put_data ... FAIL
Failure: ImportError (No module named httplib2) ... ERROR
Doctest: pandas.io.pytables.HDFStore ... FAIL
Doctest: pandas.io.pytables.get_store ... FAIL
Doctest: pandas.io.sql.sequence2dict ... ok
Failure: ImportError (No module named util) ... ERROR
Failure: ImportError (No module named rpy2.robjects.packages) ... ERROR
Failure: ImportError (No module named util) ... ERROR
Failure: ImportError (cannot import name WLS) ... ERROR
Doctest: pandas.tools.merge.merge ... FAIL
Doctest: pandas.tools.merge.ordered_merge ... FAIL
Doctest: pandas.tools.pivot.crosstab ... FAIL
Doctest: pandas.tools.pivot.pivot_table ... FAIL
Doctest: pandas.tools.plotting.boxplot_frame_groupby ... FAIL
Doctest: pandas.tools.plotting.parallel_coordinates ... FAIL
Doctest: pandas.tools.plotting.scatter_matrix ... FAIL
Doctest: pandas.tools.tile.cut ... FAIL
Doctest: pandas.tseries.period.Period.strftime ... FAIL
Doctest: pandas.tseries.period.PeriodIndex ... FAIL
Doctest: pandas.util.compat._Counter ... ok
Doctest: pandas.util.compat._Counter.__add__ ... ok
Doctest: pandas.util.compat._Counter.__and__ ... ok
Doctest: pandas.util.compat._Counter.__init__ ... ok
Doctest: pandas.util.compat._Counter.__or__ ... ok
Doctest: pandas.util.compat._Counter.__sub__ ... ok
Doctest: pandas.util.compat._Counter.elements ... ok
Doctest: pandas.util.compat._Counter.most_common ... ok
Doctest: pandas.util.compat._Counter.update ... ok
Doctest: pandas.util.counter.Counter ... ok
Doctest: pandas.util.counter.Counter.__add__ ... ok
Doctest: pandas.util.counter.Counter.__and__ ... ok
Doctest: pandas.util.counter.Counter.__init__ ... ok
Doctest: pandas.util.counter.Counter.__or__ ... ok
Doctest: pandas.util.counter.Counter.__sub__ ... ok
Doctest: pandas.util.counter.Counter.elements ... ok
Doctest: pandas.util.counter.Counter.most_common ... ok
Doctest: pandas.util.counter.Counter.subtract ... ok
Doctest: pandas.util.counter.Counter.update ... ok
...
Ran 81 tests in 4.671s

FAILED (errors=6, failures=52)

From the Messages (not included in the code snippet above) one can see that most errors result from ImportErrors, so maybe the problem is only that the imports are not in the docstring.

Those are code examples utilizing the familiar ">>>", not doctests per se.
Practically all those methods are covered by the test suite, which is where testing
is done in pandas.

Thanks, closing.

[bmu]

@y-p I'm not really happy with closing this ticket.

I think if there are examples, they should work. I think it is useful to have examples in the docstrings especially in ipython, where you can copy and paste them into the console and try some things with the objects created from pasting the examples.

An example is numpy, where examples are given in the same way, but they work (they are using ">>>" to and I think this is no problem, it's even given in the documentation of the doctest module as an example, you can paste in the examples with the prompt into ipython and its ignoring the prompt). Numpy and matplotlib also use the "default" import names (numpy as np, matplotlib.pyplot as plt) which makes the users familiar with these shortcuts.

sure it is right, that the testing in pandas is done by the unittests, but if there are examples in the docstrings I think they should be tested to and they should work.

[wesm]

Not sure how this would be possible with pandas the the repr for objects cannot be used typically to reconstruct the object for comparison.

Looking at the actual docstrings, these are examples of invocation/signature not full blown doctests
(they use nonexistent variables for example, and there's no expected result).

also note that numpydoc docstrings use >>> to annotate something for syntax highlighting,
not necessarily as doctest.

Since they weren't written as doctests, nose --with-doctest failing isn't really a "failing test",
but PRs are welcome naturally.

[bmu]

@wesm I don't mean the repr but the object itself created by the example code.

As an example, in the docs of the DataFrame class definition there are the lines

>>> df3 = DataFrame(np.random.randn(10, 5),                                                               
...                 columns=['a', 'b', 'c', 'd', 'e'])            

If I paste them into ipython I have a DataFrame with named columns, which maybe useful for a beginner as he can further inspect the dataframe (attribute access of the cols, ...) and you don't have to write this code yourself. It's not a big thing, but I did this with numpy and especially with matplotlib where you have more complicated objects with man attributes/methods. Maybe others do this too.

@y-p ok, so perhaps the title of this ticket is wrong: most examples are not working as they are. It wasn't really meant to report "failing tests", but failing examples (and doctest is a method to test examples in this way).

as I said, PRs welcome.

[bmu]

Just found an for a "failing doctest" on on SO.

The asker is expecting the output of the docstring, however he gets a different result.

[hayd]

@bmu It's slightly different (he's tweaked the input arrays), basically OP wants the MultiIndex to include empty columns. The example in the docstring has no empty columns.

I think that's a feature request (#3820) rather than a docstring bug?

[bmu]

@hayd I see, you are rigth. However in the example section of the crosstab docstring a multi index is returned, while the output you get, if you execute the statement is different.