DOC: Improve the docstring of Timedelta.asm8

[chalmerlowe]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

################################################################################
###################### Docstring (pandas.Timedelta.asm8)  ######################
################################################################################

Return a numpy timedelta64 array view.

Provides access to the array view associated with the
numpy.timedelta64().view() including a 64-bit integer
representation of the timedelta in nanoseconds (Python int
compatible).

Returns
-------
numpy timedelta64 array view
    Array view of the timedelta in nanoseconds.

Examples
--------
>>> td = pd.Timedelta('1 days 2 min 3 us 42 ns')
>>> td.asm8
numpy.timedelta64(86520000003042,'ns')

>>> td = pd.Timedelta('2 min 3 s')
>>> td.asm8
numpy.timedelta64(123000000000,'ns')

>>> td = pd.Timedelta('3 ms 5 us')
>>> td.asm8
numpy.timedelta64(3005000,'ns')

>>> td = pd.Timedelta(42, unit='ns')
>>> td.asm8
numpy.timedelta64(42,'ns')

################################################################################
################################## Validation ##################################
################################################################################

[codecov]

Codecov Report

Merging #21821 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #21821   +/-   ##
=======================================
  Coverage   91.92%   91.92%           
=======================================
  Files         160      160           
  Lines       49914    49914           
=======================================
  Hits        45883    45883           
  Misses       4031     4031

Flag	Coverage Δ
#multiple	90.3% <ø> (ø)	⬆️
#single	42.1% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update c5870aa...06251ac. Read the comment docs.

[mroeschke]

In general, I would replace "array" with "scalar"

[chalmerlowe]

@mroeschke thanks for the feedback. I am learning in public, so please help me out...
Since the return values shows both the numeric value and the unit, would it be safe to say that the return value is an array scalar and should we call it that in this documentation? I am asking this based on the material I found here:

https://docs.scipy.org/doc/numpy/user/basics.types.html

NumPy generally returns elements of arrays as array scalars (a scalar with an associated dtype). Array scalars differ from Python scalars, but for the most part they can be used interchangeably (the primary exception is for versions of Python older than v2.x, where integer array scalars cannot act as indices for lists and tuples). There are some exceptions, such as when code requires very specific attributes of a scalar or when it checks specifically whether a value is a Python scalar. Generally, problems are easily fixed by explicitly converting array scalars to Python scalars, using the corresponding Python type function (e.g., int, float, complex, str, unicode).

The primary advantage of using array scalars is that they preserve the array type (Python may not have a matching scalar type available, e.g. int16). Therefore, the use of array scalars ensures identical behaviour between arrays and scalars, irrespective of whether the value is inside an array or not. NumPy scalars also have many of the same methods arrays do.

[jreback]

i suppose u can call it a numpy array scalar
array scalar is not really descriptive to anyone using pandas

[jreback]

thanks @chalmerlowe

[chalmerlowe]

@mroeschke @WillAyd @jorisvandenbossche @TomAugspurger @jreback

thanks for your help over the past couple of months to get FOUR pull requests added to pandas documentation. I use pandas regularly and greatly appreciate your work on the tool, your time in assisting me and your kindness in putting up with the new guy as he stumbles around trying to figure things out.

[mroeschke]

@chalmerlowe Thank you for contributing! We always appreciate pull requests, especially towards improving documentation.