Docstring shift
State: closed

- [x] closes #20492
- [x] tests passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=h1) Report
> Merging [#21039](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0828c25913b5862d70322471a6ee4fa11d8f890d?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/21039/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=tree)

```diff
@@           Coverage Diff           @@
##           master   #21039   +/-   ##
=======================================
  Coverage   91.99%   91.99%           
=======================================
  Files         167      167           
  Lines       50578    50578           
=======================================
  Hits        46530    46530           
  Misses       4048     4048
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.4% <ø> (ø)` | :arrow_up: |
| #single | `42.17% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/21039/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.47% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=footer). Last update [0828c25...888b97b](https://codecov.io/gh/pandas-dev/pandas/pull/21039?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@TomAugspurger @jreback for a check if you have the chance
I think this is missing the main purpose of that thread, namely that shift will not do any implicit inference of ordering or continuity for you. 

While the solution you provided "answers" that question, I think it would be more appropriate to document shift with / without reindexing prior to the fact to contrast the difference
@WillAyd  Thanks for the feedback.

I am not sure how I could document the case without re-indexing without resulting in an error. I decided to print the intermediary result in an attempt to make this clear. Do you suggest I show the column with the shift applied instead of having it hide behind the lambda operation?
I don't think whatever you show should have any lambda (UDFs should typically be a "last resort").

I would suggest doing a shift with the base frame, pointing out that values from 06-06 simply get moved down to 06-08 without any regard for the fact that there is a two day gap in between those. Then contrast that by reindexing then shifting to show how to move from 06-06 to 06-07
Okay - will change this to remove usage of lambda.

Doing a shift with the base frame without any re-indexing _data.shift(1, pd.Timedelta('1 days')))_ moves values from 06 to 07 but I believe the re-indexing and left join is needed because of the grouping and the mismatch of indexing between the original and resulting dataframe as a result of the shift.

Hello @PyJay! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on July 22, 2018 at 22:04 Hours UTC
@TomAugspurger I have updated the docs as per the feedback.
I still think this is missing the point. Can you show:

 - The "as is shift", calling out that the values are simply moved down (i.e. 06-06 value goes to 06-08) 
 - A reindexed version where the value from 06-06 subsequently moves to 06-07

Please remove the use of the anonymous function
@WillAyd I have updated to address to your first two points. I am still unsure about removing the lambda since the only alternative I can think of is having a one line function customized to the use case to do the same. Maybe I'm missing a  better way here?
@WillAyd @TomAugspurger Changes made as per feedback.
Ahh thanks for the feedback @WillAyd I realise this has dragged on a bit! Will hopefully be able to finalise this weekend. @datapythonista were you thinking of taking this work over?
Duplicate of #20472