BrandonFors/pandas-github-issues huggingface dataset:
DOC: update the DataFrame.cov docstring
State: closed

Update the docstring with some examples from
elsewhere in the pandas documentation.

Some of the examples use randomly generated time series
because we need to get covariance between long series.
Used a random seed to ensure that the results are the
same each time.

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.cov" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.




Labels:
name: Docs
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
This looks very good. Thanks!
DOC: Update Series.repeat docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [ X] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [ X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [ X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```

################################################################################
####################### Docstring (pandas.Series.repeat) #######################
################################################################################

Repeat elements of a Series.

Each element of the Series is repeated 'repeats' times.

Parameters
----------
repeats : int
    The number of repetitions for each element.
*args
    These parameters will be passed to a validation function.
**kwargs
    These parameters will be passed to a validation function.

See also
--------
Series.append : Concatenate two or more Series.
pandas.concat : Concatenate two or more DataFrames.
numpy.repeat : Repeat elements of an array.

Returns
-------
Series
    The repeated version of the Series.

Examples
--------
>>> df = pd.DataFrame({'col1' : ['A','B','C'],'col2' : [ 0 , 1 , 2 ]})
>>> df
col1  col2
0    A     0
1    B     1
2    C     2
>>> df.col1.repeat(3)
0    A
0    A
0    A
1    B
1    B
1    B
2    C
2    C
2    C
Name: col1, dtype: object

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
		Unknown parameters {'**kwargs', '*args'}
		Parameter "*args" has no type
		Parameter "**kwargs" has no type

```

The errors returned for the script is an error, since t is not ready for **kwargs and *args parameters.


Labels:

Comments:
@pedropazzini Can you check the similar PR https://github.com/pandas-dev/pandas/pull/19985 to see if there is something in there you can use? (eg explanation for the `**kwargs`)
@pedropazzini Is there a reason that you closed this?
Docstring pandas.series.diff
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.diff" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
@adatasetaday were you assigned both DataFrame.diff and Series.diff? OK to do as one PR, but wanted to make sure we don't conflict with someone else.
Ah I see https://github.com/pandas-dev/pandas/pull/20227

could you remove the dataframe changes from this branch so we don't ahve merge conflicts?
LGTM once you remove the dataframe changes.
@TomAugspurger Yes, I was assigned diff for both Series and DataFrame. I made sense since it were very similar.

I fixed the commit. 
thanks @adatasetaday very nice!
DOC: update the PeriodIndex docstring
State: closed

year, month, quarter, day, hour, minute, second documentation
improved. Detailed in depth the requirements of each parameter.

Documentation is still confusing for allowable freq arguments

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

```
################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'fields', 'name', 'ordinal'} not documented
		Unknown parameters {'second', 'month', 'year', 'minute', 'quarter', 'day', 'hour'}
		Parameter "dtype" has no description
	No returns section found
```

A few errors are still reported but are outside of the scope of the doc sprint (fields, name, ordinal).


Labels:
name: Docs
name: Frequency
description: DateOffsets
name: Period
description: Period data type

Comments:
Hello @costrouc! Thanks for submitting the PR.

 - In the file [`pandas/core/indexes/period.py`](https://github.com/pandas-dev/pandas/blob/594708a909c952fe2b772fee99e07104b42c38b5/pandas/core/indexes/period.py), following are the PEP8 issues :

> [Line 212:80](https://github.com/pandas-dev/pandas/blob/594708a909c952fe2b772fee99e07104b42c38b5/pandas/core/indexes/period.py#L212): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (87 > 79 characters)


Ok so I am sort of lost with all the feedback. 

I hear the requests for changes but many of these parameters require multiple sentences to describe. The `PeriodIndex` class has three ways of initializing each one requiring a subset of the arguments. The `_generate_range` and `_range_from_fields` methods of the class show this. Here are the three ways:

 1. `PeriodIndex(start, end, periods, freq)`
 2. `PeriodIndex(year, quarter, freq)`
 3. `PeriodIndex(year, month, day, hour, minute, second, freq)`

Case 2 requires that the freq must match Q or Q-DEC.

Additionally while year, month, day, hour, minute and second all do default to None for cases 1 and 2. Case 3 has a completely different default behavior (day=1, hour=0, minute=0, second=0) while year and month are required.
Thanks for listing out the cases. I think as long as each of those has at least one example we're OK.
closing as stale. if you'd like to continue pls ping.
DOC: update the pd.Index.argsort docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
####################### Docstring (pandas.Index.argsort) #######################
################################################################################

Return the order of the indices.

We have an object with values and index. Using argsort method
returns a series of indices that would sort the index.

Parameters
----------
*args
    Passed to `numpy.ndarray.argsort`.
**kwargs
    Passed to `numpy.ndarray.argsort`.

Returns
-------
numpy.ndarray : Argsorted indices of the index

See also
--------
numpy.ndarray.argsort : Returns the indices that would sort this array.

Examples
--------
>>> s = pd.Series(data=[4,3,2,1],index=['c','b','a','d'])
>>> s.index.argsort()
array([2, 1, 0, 3], dtype=int64)

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Parameters {'args', 'kwargs'} not documented
                Unknown parameters {'**kwargs', '*args'}
                Parameter "*args" has no type
                Parameter "**kwargs" has no type
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

We did our best to explain *args and **kwargs

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
Thanks @dajcs!
DOC: update the Index.get_values docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
##################### Docstring (pandas.Index.get_values)  #####################
################################################################################

Return `Index` data as an `ndarray`.

Because this is a wrapper function around Index.values, it is useful
when one explicitly wants to use a getter.

Returns
-------
numpy.ndarray
    A one-dimensional numpy `array` of the indexes.

See Also
--------
Index
    The basic object storing axis labels for all pandas objects.
Index.values
    The original function around which `get_values` creates a wrapper.

Examples
--------
Getting the `Index` values of a `DataFrame`:

>>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]],
...                    index=['a', 'b', 'c'], columns=['A', 'B', 'C'])
>>> df
   A  B  C
a  1  2  3
b  4  5  6
c  7  8  9
>>> df.index.get_values()
array(['a', 'b', 'c'], dtype=object)

Standalone `Index` values:

>>> idx = pd.Index(['1', '2', '3'])
>>> idx.get_values()
array(['1', '2', '3'], dtype=object)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Index.get_values" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves

Comments:
Thanks @nocibambi !
DOC: update the pandas.Series.dt.dayofweek docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
#################### Docstring (pandas.Series.dt.dayofweek) ####################
################################################################################

The day of the week with Monday=0, Sunday=6.

Return the day of the week. It is assumed the week starts on
Monday, which is denoted by 0 and ends on Sunday which is denoted
by 6.

See Also
--------
pandas.Series.dt.dayofweek : Identical method.
pandas.Series.dt.weekday : Identical method.

Returns
-------
ndarray of integers indicating the day of the week

Examples
--------
>>> dates = pd.date_range("2016-12-31", "2017-01-08", freq="D")
>>> s = pd.Series(dates)
>>> day_name = s.dt.strftime("%A")
>>> pd.DataFrame({'dt': s, 'num': s.dt.weekday, 'day': day_name})
          dt  num        day
0 2016-12-31    5   Saturday
1 2017-01-01    6     Sunday
2 2017-01-02    0     Monday
3 2017-01-03    1    Tuesday
4 2017-01-04    2  Wednesday
5 2017-01-05    3   Thursday
6 2017-01-06    4     Friday
7 2017-01-07    5   Saturday
8 2017-01-08    6     Sunday

Note that `series.dt.dayofweek` and `series.dt.weekday` are the same.

>>> s.dt.dayofweek
0    5
1    6
2    0
3    1
4    2
5    3
6    4
7    5
8    6
dtype: int64
>>> s.dt.weekday
0    5
1    6
2    0
3    1
4    2
5    3
6    4
7    5
8    6
dtype: int64

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.dt.dayofweek" correct. :)
```

Labels:
name: Docs
name: Datetime
description: Datetime data dtype

Comments:
Closing in favor of #21823 (the original fork/branch don't exist and can't fix the conflict in this PR).

Thanks @koaning for the contribution, and sorry for the delay.
Docstring pandas.data frame.diff
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.diff" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
I think we just need a `.` at the end of this line https://github.com/pandas-dev/pandas/pull/20227/files#diff-1e79abbbdd150d4771b91ea60a4e1cc7R4739

LGTM otherwise.
I can definitely do that, but it won't be consistent with the other functions' documentation.

I'm also adding a "See Also" to DataFrame.pct_change() which I didn't realize was pretty much the same function using % instead of absolute value.
As discussed, the "." was added at the end of the versionadded and passed validation without any errors.
Hello @adatasetaday! Thanks for updating the PR.



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

##### Comment last updated on March 11, 2018 at 12:35 Hours UTC
Thanks @adatasetaday!
DOC: Update pandas.DataFrame.tail docstring
State: closed

-Add extended summary

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
###################### Docstring (pandas.DataFrame.tail)  ######################
################################################################################

Return the last `n` rows.

This function returns last `n` rows from the object based on the
underlying index. It is useful for quickly verifying data,
for example, after sorting or appending rows.

Parameters
----------
n : int, default 5
    Number of rows to select.

Returns
-------
type of caller
    The last `n` rows of the caller object.

See Also
--------
pandas.DataFrame.head : The first `n` rows of the caller object.

Examples
--------
>>> df = pd.DataFrame({'animal':['alligator', 'bee', 'falcon', 'lion',
...                    'monkey', 'parrot', 'shark', 'whale', 'zebra']})
>>> df
      animal
0  alligator
1        bee
2     falcon
3       lion
4     monkey
5     parrot
6      shark
7      whale
8      zebra

Viewing the last 5 lines

>>> df.tail()
   animal
4  monkey
5  parrot
6   shark
7   whale
8   zebra

Viewing the last n lines (three in this case)

>>> df.tail(3)
  animal
6  shark
7  whale
8  zebra

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.tail" correct. :)

```


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
And in the examples section in "Viewing the last n lines (three in this case)" -> can you there also add single backticks around "n" ?
Thanks!
DOC: update the DataFrame.iat[] docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
# paste output of "scripts/validate_docstrings.py <your-function-or-method>" here
# between the "```" (remove this comment, but keep the "```")

################################################################################
####################### Docstring (pandas.DataFrame.iat) #######################
################################################################################

Selects a single value for a row/column pair by integer position.

Useful if performance is a major concern and you only need to
get or set a value at a particular row/column.

See Also
--------
at : Selects a single value for a row/column label pair
loc : Selects a group of rows and columns by label(s)
iloc : Selects group of rows and columns by integer position(s)

Returns
-------
    None

Examples
--------
>>> df = pd.DataFrame([[0,2,3], [0,4,1], [10,20,30]])
>>> df
    0   1   2
0   0   2   3
1   0   4   1
2  10  20  30
>>> df.iat[1, 2]
1
>>> df.iat[1, 2] = 10
>>> df.iat[1, 2]
10

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.iat" correct. :)

```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

Labels:
name: Docs
name: Indexing
description: Related to indexing on series/frames, not to indexes themselves

Comments:
Thank you for the comments! Please let me know if there is anything else that should be changed.
Thanks for the updates!
Thanks @akosel !