DOC: Updated the DataFrame.assign docstring
State: closed

Updated the DataFrame.assign docstring example to use np.arange instead of np.random.randn to pass the validation test.

Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21917?src=pr&el=h1) Report
> Merging [#21917](https://codecov.io/gh/pandas-dev/pandas/pull/21917?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0480f4c183a95712cb8ceaf5682c5b8dd02e0f21?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #21917      +/-   ##
==========================================
+ Coverage   92.18%   92.18%   +<.01%     
==========================================
  Files         169      169              
  Lines       50804    50810       +6     
==========================================
+ Hits        46833    46839       +6     
  Misses       3971     3971
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.6% <ø> (ø)` | :arrow_up: |
| #single | `42.37% <ø> (+0.04%)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21917?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/21917/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.2% <ø> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/21917/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.67% <0%> (ø)` | :arrow_up: |
| [pandas/io/formats/excel.py](https://codecov.io/gh/pandas-dev/pandas/pull/21917/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZXhjZWwucHk=) | `97.4% <0%> (ø)` | :arrow_up: |
| [pandas/core/arrays/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/21917/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lbGlrZS5weQ==) | `95.53% <0%> (+0.02%)` | :arrow_up: |
| [pandas/io/parquet.py](https://codecov.io/gh/pandas-dev/pandas/pull/21917/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnF1ZXQucHk=) | `73.72% <0%> (+0.68%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21917?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/21917?src=pr&el=footer). Last update [0480f4c...ecfaf47](https://codecov.io/gh/pandas-dev/pandas/pull/21917?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks for the fix, that's much better than using random.

What would you think about simplifying the example even further? I don't think we need 10 rows to show what assign does. And using a "simpler" function than log (e.g. `lambda x: x ** 2`) would probably help users understand the example faster.
I agree with the number of rows, but `np.log` is also nice in that it does not use "lambda" IMO
Thanks @datapythonista and @jorisvandenbossche! I'll shorten the table(s) to hold only 2 rows.
lgtm. @aeltanawy normally don't put 2 commits like this together (e.g. the statsmodels change is already in master)
> I agree with @jorisvandenbossche that not using lambda would be better.

Ah, yes, missed that the `np.log` example was also using `lambda` .. Indeed not easy to avoid in this case.
> @aeltanawy normally don't put 2 commits like this together (e.g. the statsmodels change is already in master)

Ah! Sorry for that, I messed up my branch when fetching upstream then rebasing. Hopefully all sorted out now.

@datapythonista inspired by your example, how about using simply temperatures in Celsius and Fahrenheit indexed with cities? 
Sure, I just gave an example to illustrate my point, and not leave an abstract comment. But feel free to use the example that you find more useful/clear for users.
I apologize for adding already committed commits, again! Anyone willing to show me what I'm doing wrong? (please let me know if this is not the place to ask)

My workflow is as follows:
1. edit the script in my local branch (doc)
2. git add, the git commit
3. then git pull origin doc
4. then git push origin doc
@aeltanawy no problem! 

Looking at your workflow, the one thing that is normally not needed is third step (`git pull origin doc`).

Now, I am not really sure how doing that ended up in having those extra commits, but let's try to solve it.

I would first try:

```
git pull upstream master
git push origin doc
```

and check if that fixes the commits here in the PR (the above updates the PR with changes that have happened in the meantime in the upstream (the pandas-dev/pandas repo) master branch). 

If that didn't fix it, another approach is doing a rebase:

```
git fetch upstream
git rebase upstream/master
git push origin doc --force
```

(note here you will need to force push because rebasing means rewriting the history of the branch, not simply adding commits to the branch as merging does).

If you have more questions, feel free to ask!
@aeltanawy I fixed the git problems for you. If you simply do a `git pull` in your branch, you should be able to continue working with the docstring.
Thanks a lot @jorisvandenbossche and @datapythonista !! Now I'm able to push changes without git rejecting it and, hopefully for good, just submitting my commits only.

I have simplified the examples even further by  including one column in the initial DataFrame.

@datapythonista merge when satisfied
Here are the recent changes to the DataFrame.assign docstring:

1. Showed the output of the initial dataframe.
2. Re-wrote the third example to illustrate python3.6+ feature of being able to assign multiple columns that depends on each other. The example is derived from @datapythonista and @jschendel  comments.
Hello @aeltanawy! Thanks for updating the PR.

 - There are no PEP8 issues in the file [`pandas/core/frame.py`](https://github.com/aeltanawy/pandas/blob/1fa9bc5983808d6d62a4625a49af7c8ee1f0079d/pandas/core/frame.py) !


@datapythonista, I have adjusted DataFrame.assign docstring with your comments. I've also ran ./scripts/validate_docstrings.py pandas.DataFrame.assign till I got 'the Docstring for "pandas.DataFrame.assign" correct. :)'.

Let me know your thoughts on this commit. Thanks!
Thanks @datapythonista! Adjusted `series` and `list-like` to `Series` and `sequence` respectively. 
Thanks a lot @datapythonista! I've learned a lot!

Is there is any next steps I should do for this case, such as closing this pull request?
can you merge master into your branch and update the PR please? Seems like some checks failed, and this way they'll rerun and we can merge the changes. Other than that, it's in our side.

In case it's not clear what I meant, in your branch do:
`git fetch upstream ; git merge upstream/master ; git push`
Do I need to rebase my changes against master?
It's like the other way round I'd say. You get the latest changes from pandas `git fetch master`, you merge those changes into your branch `git merge upstream/master`, so your branch has your changes on top of the latest pandas, not the pandas of the time you started the changes, and then you update the PR with them `git push`. Besides having your changes on the latest development version of pandas, any update to the PR will make the continuous integration to run again. So the checks that failed (unrelated to your changes), will luckily pass this time.
Pretty sure my branch tree is messed up! For now, I have merged upstream master to my branch and pushed the changes. Waiting for your directions @datapythonista after the checks are finished.
Git changes look OK.

@aeltanawy could you remove `-assign` from https://github.com/pandas-dev/pandas/blob/0480f4c183a95712cb8ceaf5682c5b8dd02e0f21/ci/doctests.sh#L24? Then the docstring will be tested on each PR.
Looks like all checks passed.

@TomAugspurger, I'll create another pull request for removing -assign so as not to confuse this one which is entirely a DOC case. How does this sound?
@aeltanawy it's better if you do it in this one, as removing the `-assign` will make the CI validate that your examples pass the doctests already.
ah! 
removed -assign from pandas/ci/doctests.sh
Thanks @aeltanawy, merging on green.
Thanks @aeltanawy!
Time to celebrate my first contribution! Thanks to everyone :).
@aeltanawy Thanks a lot!