CLN: Incorrect name in docstrings for generic

[jtratner]

E.g. for reindex on panel

elp on method reindex in module pandas.core.generic:

reindex(self, *args, **kwargs) method of pandas.core.panel.Panel instance
    Conform DataFrame to new index with optional filling logic, placing
    NA/NaN in locations having no value in the previous index. A new object
    is produced unless the new index is equivalent to the current one and
    copy=False

    Parameters
    ----------
    axes : array-like, optional (can be specified in order, or as keywords)
        New labels / index to conform to. Preferably an Index object to
        avoid duplicating data
    method : {'backfill', 'bfill', 'pad', 'ffill', None}, default None
        Method to use for filling holes in reindexed DataFrame
        pad / ffill: propagate last valid observation forward to next valid
        backfill / bfill: use NEXT valid observation to fill gap
    copy : boolean, default True
        Return a new object, even if the passed indexes are the same
    level : int or name
        Broadcast across a level, matching Index values on the
        passed MultiIndex level
    fill_value : scalar, default np.NaN
        Value to use for missing values. Defaults to NaN, but can be any
        "compatible" value
    limit : int, default None
        Maximum size gap to forward or backward fill
    takeable : boolean, default False
        treat the passed as positional values

    Examples
    --------

Functions that need parameters list/explanation:

• swapaxes
• pop [what does 'items' mean?]

Functions that only need list of axes:

• filter [need to check if it should be defined for Series at all]
• fillna [Series, Frame]
• reindex_axis [needs class name + axes]
• rename [might need a bit more logic to do docstring + note that args interpreted like axes??]
• transpose

Functions needing a little work:

• reindex
  • needs to have panel check that both major and major_axis aren't passed, same with minor and minor_axis (like SparsePanel does)
  • would be better if there were individual functions for Series Frame and Panel that explicitly enumerate axes in type signature.

Functions that may not need to be changed:

• align

Functions that could use slight wording tweaks:

• truncate
• where
• mask

[jreback]

prob need wrapper methods (like arith methods), for methods that are now generic

eg reindex,fillna,replace,rename

[jreback]

or first solution is good too

[jtratner]

That's what I was thinking too...I like the second solution better...it's a bit more complicated, but nicer for the end-user / online docs...

[jtratner]

@jreback for some of these, might it make sense to have a front-end around the method that just calls super (which means you'll be able to see the actual type signature for tab completions like in IPython notebook, etc.).

btw - did you mean to change the signature for Series.rename? previously first positional argument was called mapper - now if you try to do that it fails saying you need to use index as keyword argument.

Anyways, this is what I was thinking:

#DataFrame.rename
def rename(self, index=None, columns=None, copy=True, inplace=False):
        """
        Alter index and / or columns using input function or
        functions. Function / dict values must be unique (1-to-1). Labels not
        contained in a dict / Series will be left as-is.

        Parameters
        ----------
        index : dict-like or function, optional
            Transformation to apply to index values
        columns : dict-like or function, optional
            Transformation to apply to column values
        copy : boolean, default True
            Also copy underlying data
        inplace : boolean, default False
            Whether to return a new DataFrame. If True then value of copy is
            ignored.

        See also
        --------
        Series.rename

        Returns
        -------
        renamed : DataFrame (new object)
        """
        return super(self, DataFrame).rename(index=index, columns=columns, copy=copy, inplace=inplace)

And that way, if you're playing with pandas in IPython Notebook, it will complete index=, columns=, etc for you.

[jtratner]

Non-exhaustive, but at least some of the public functions that have shifted from v0.11 to v0.13.

Not necessary (because no docstrings or don't vary by kind, etc.):

• ffill
• bfill
• as_blocks
• convert_objects
• get_dtype_counts
• astype
• copy
• abs
• reindex_like
• replace
• shape

[jreback]

I did change series.rename on purpose as it was inconsistent (and also didn't function properly on multi indices)

[jtratner]

@jreback got it. and obviously not all of those funcs ought to have special names...definitely some of them though.

[jreback]

I don't think h really need to boilerplate as self.class is always correct ; not sure how to get ipython to correctly deal with it though

I agree would be nice to have 'filled' in argument methods - but would require maybe generating these functions

[jreback]

actually the above example is prob not too hard to automatically generate (all of the properties are their to do it, eg class._AXIS_ORDERS) - see top of generic

[jtratner]

actually yeah that's true.

[jtratner]

The problem is you can't copy the function - but I guess they're already *args, **kwargs so may not be a big deal.

[jreback]

I punted on some of these and put a PandasObject as the return type (so maybe should be better)

[jtratner]

@jreback - why doesn't filter document the axis parameter?

[jreback]

because I added it in the refactor (filter was only defined for frame I think, but made sense for panel); not sure if it is relevant for series though

needs docs (and prob some tests), kind of got 'lost'

[jtratner]

@jreback I went through and sorted some things. I think it's really just reindex and rename that could benefit from having separate functions defined (perhaps with a decorator that adds the actual docstring) because they take axes as keyword arguments. Everything else would be fine just with class name and axes order.

[jreback]

@jtratner let's convert the remainder to 0.14?

[jtratner]

Yeah, I think the majority are actually already done (or I realized they
were fine). There is one docstring somewhere (and I don't remember which)
that still ends up with %(na_action) unformatted. I'll try to find it again
because that's worth fixing.

[jreback]

ok.....i'll leave u to it then

[jreback]

@jtratner going to change to 0.14..but close if you can

[jtratner]

good enough for now...will keep things like this in mind for the future.