DOC: update the Series.align 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.align)  #######################
################################################################################

Align two Series on their axes with the
specified join method for each axis Index.

The result is a tuple containing two Series with the same indexes. Using
`join`, one can specifiy if the union or intersection of the indexes are
retained or whether to keep the index of the first or second Series.

Align supports MultiIndexing, `level` can be used to select which index
that is used for alignment.

Parameters
----------
other : DataFrame or Series
    The Series object to align with.
join : {'outer', 'inner', 'left', 'right'}, default 'outer'
    How to aggregate the indexes.
axis : allowed axis of the other object, default None
    Align on index (0), columns (1), or both (None).
level : int or level name, default None
    Broadcast across a level, matching Index values on the
    passed MultiIndex level.
copy : boolean, default True
    Always returns new objects. If copy=False and no reindexing is
    required then original objects are returned.
fill_value : scalar, default np.NaN
    Value to use for missing values. Defaults to NaN, but can be any
    "compatible" value.
method : str, default None
    Method to use for filling holes in reindexed Series
    pad / ffill: propagate last valid observation forward to next valid
    backfill / bfill: use NEXT valid observation to fill gap.
limit : int, default None
    If method is specified, this is the maximum number of consecutive
    NaN values to forward/backward fill. In other words, if there is
    a gap with more than this number of consecutive NaNs, it will only
    be partially filled. If method is not specified, this is the
    maximum number of entries along the entire axis where NaNs will be
    filled. Must be greater than 0 if not None.
fill_axis : {0, 'index'}, default 0
    Filling axis, method and limit.
broadcast_axis : {0, 'index'}, default None
    Broadcast values along this axis, if aligning two objects of
    different dimensions.

Returns
-------
(left, right) : (Series, type of other)
    Aligned objects

See also
--------
reindex : Conform Series to new index with optional filling logic.    

Examples
--------
>>> weights = pd.Series([2., 5., 999.], index=['ant', 'beetle', 'cow'],
...                         name='weigth')
>>> height = pd.Series([0.1, 2, 34], index=['ant', 'cow', 'duck'],
...                         name='weigth')

>>> weights.align(height)
(ant         2.0
 beetle      5.0
 cow       999.0
 duck        NaN
 Name: weigth, dtype: float64, ant        0.1
 beetle     NaN
 cow        2.0
 duck      34.0
 Name: weigth, dtype: float64)

By setting `join` to 'inner', only the intersection of the two indexes
is retained.

>>> weights.align(height, join='inner')
(ant      2.0
 cow    999.0
 Name: weigth, dtype: float64, ant    0.1
 cow    2.0
 Name: weigth, dtype: float64)

The missing values can be set by the parameter `fill_value`.

>>> weights.align(height, fill_value=-1)
(ant         2.0
 beetle      5.0
 cow       999.0
 duck       -1.0
 Name: weigth, dtype: float64, ant        0.1
 beetle    -1.0
 cow        2.0
 duck      34.0
 Name: weigth, dtype: float64)

This method can also deal with MultiIndexes.

>>> idx = pd.MultiIndex.from_tuples([('insect', 'herbivore'),
...                                  ('insect', 'carnivore'),
...                                  ('mammals', 'herbivore'),
...                                  ('mammals', 'carnivore')])
>>> weights = pd.Series([1, 2, 59, 102], index=idx)
>>> s = pd.Series([1, 2], index=['herbivore', 'carnivore'])

>>> weights.align(s, level=0)
(insect   herbivore      1
          carnivore      2
 mammals  herbivore     59
          carnivore    102
 dtype: int64, insect   herbivore   NaN
          carnivore   NaN
 mammals  herbivore   NaN
          carnivore   NaN
 dtype: float64)

>>> weights.align(s, level=1)
(insect   herbivore      1
          carnivore      2
 mammals  herbivore     59
          carnivore    102
 dtype: int64, insect   herbivore    1
          carnivore    2
 mammals  herbivore    1
          carnivore    2
 dtype: int64)

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Series.align" 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.


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: Indexing
description: Related to indexing on series/frames, not to indexes themselves

Comments:
Hello @MichielStock! Thanks for updating the PR.

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

> [Line 2612:80](https://github.com/pandas-dev/pandas/blob/be69d5daf7163596d54b5ba769a695ce6bc605f6/pandas/core/series.py#L2612): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (85 > 79 characters)



##### Comment last updated on March 12, 2018 at 09:31 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20156?src=pr&el=h1) Report
> Merging [#20156](https://codecov.io/gh/pandas-dev/pandas/pull/20156?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/840d4323935348a890d6b868f2b18e8dddd22199?src=pr&el=desc) will **decrease** coverage by `0.02%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #20156      +/-   ##
==========================================
- Coverage   91.72%    91.7%   -0.03%     
==========================================
  Files         150      150              
  Lines       49156    49151       -5     
==========================================
- Hits        45090    45073      -17     
- Misses       4066     4078      +12
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <100%> (-0.03%)` | :arrow_down: |
| #single | `41.84% <61.76%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20156?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.84% <100%> (-0.02%)` | :arrow_down: |
| [pandas/plotting/\_converter.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb252ZXJ0ZXIucHk=) | `65.07% <0%> (-1.74%)` | :arrow_down: |
| [pandas/core/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYmFzZS5weQ==) | `96.78% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <0%> (-0.01%)` | :arrow_down: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.23% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.06% <0%> (ø)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20156/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (ø)` | :arrow_up: |

------

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

closing as stale. if you'd like to continue pls ping.