8000 STY: index_tricks: Improve comments and documentation strings · numpy/numpy@f30000b · GitHub
[go: up one dir, main page]
Skip to content

Commit f30000b

Browse files
mwiebecharris
mwiebe
authored and
charris
committed
STY: index_tricks: Improve comments and documentation strings
1 parent bdf25de commit f30000b

File tree

5 files changed

+63
-32
lines changed

5 files changed

+63
-32
lines changed

‎numpy/add_newdocs.py

Lines changed: 16 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4349,17 +4349,16 @@
43494349
coords : tuple of array_like
43504350
A tuple of integer arrays, one array for each dimension.
43514351
dims : tuple of ints
4352-
The shape of an array into which indices from `coords` are for.
4352+
The shape of array into which the indices from ``coords`` apply.
43534353
mode : {'raise', 'wrap', 'clip'}, optional
4354-
Specifies how out-of-bounds indices will behave. Can specify
4355-
either one mode or a tuple of modes, with length matching that
4356-
of ``dims``.
4354+
Specifies how out-of-bounds indices are handled. Can specify
4355+
either one mode or a tuple of modes, one mode per index.
43574356
43584357
* 'raise' -- raise an error (default)
43594358
* 'wrap' -- wrap around
43604359
* 'clip' -- clip to the range
43614360
4362-
Note that in 'clip' mode, a negative index which would normally
4361+
In 'clip' mode, a negative index which would normally
43634362
wrap will clip to 0 instead.
43644363
order : {'C', 'F'}, optional
43654364
Determines whether the coords should be viewed as indexing in
@@ -4368,13 +4367,17 @@
43684367
Returns
43694368
-------
43704369
raveled_indices : ndarray
4371-
This is a new array with the same shape as the broadcast shape
4372-
of the arrays in ``coords``.
4370+
An array of indices into the flattened version of an array
4371+
of dimensions ``dims``.
43734372
43744373
See Also
43754374
--------
43764375
unravel_index
43774376
4377+
Notes
4378+
-----
4379+
.. versionadded:: 1.6.0
4380+
43784381
Examples
43794382
--------
43804383
>>> arr = np.array([[3,6,6],[4,5,1]])
@@ -4401,19 +4404,20 @@
44014404
Parameters
44024405
----------
44034406
indices : array_like
4404-
An integer type array whose elements are indices for a
4405-
flattened array with shape `dims`.
4407+
An integer array whose elements are indices into the flattened
4408+
version of an array of dimensions ``dims``. Before version 1.6.0,
4409+
this function accepted just one index value.
44064410
dims : tuple of ints
4407-
The shape of an array into which flattened indices from
4408-
``indices`` are for.
4411+
The shape of the array to use for unravelling ``indices``.
44094412
order : {'C', 'F'}, optional
4413+
.. versionadded:: 1.6.0
44104414
Determines whether the indices should be viewed as indexing in
44114415
C (row-major) order or FORTRAN (column-major) order.
44124416
44134417
Returns
44144418
-------
44154419
unraveled_coords : tuple of ndarray
4416-
Each array in the tuple is the same shape as the input ``indices``
4420+
Each array in the tuple has the same shape as the ``indices``
44174421
array.
44184422
44194423
See Also

‎numpy/core/src/multiarray/ctors.c

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3726,4 +3726,3 @@ _array_fill_strides(npy_intp *strides, npy_intp *dims, int nd, size_t itemsize,
37263726
}
37273727
return itemsize;
37283728
}
3729-

‎numpy/core/src/multiarray/multiarraymodule.c

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1313,43 +1313,51 @@ PyArray_ClipmodeConverter(PyObject *object, NPY_CLIPMODE *val)
13131313

13141314
/*NUMPY_API
13151315
* Convert an object to an array of n NPY_CLIPMODE values.
1316+
* This is intended to be used in functions where a different mode
1317+
* could be applied to each axis, like in ravel_coords.
13161318
*/
13171319
NPY_NO_EXPORT int
1318-
PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE *vals, int n)
1320+
PyArray_ConvertClipmodeSequence(PyObject *object, NPY_CLIPMODE *modes, int n)
13191321
{
13201322
int i;
13211323
/* Get the clip mode(s) */
1322-
if(object && (PyTuple_Check(object) || PyList_Check(object))) {
1324+
if (object && (PyTuple_Check(object) || PyList_Check(object))) {
13231325
if (PySequence_Size(object) != n) {
13241326
PyErr_Format(PyExc_ValueError,
13251327
"list of clipmodes has wrong length (%d instead of %d)",
13261328
(int)PySequence_Size(object), n);
13271329
return PY_FAIL;
13281330
}
1331+
13291332
for (i = 0; i < n; ++i) {
13301333
PyObject *item = PySequence_GetItem(object, i);
13311334
if(item == NULL) {
13321335
return PY_FAIL;
13331336
}
1334-
if(PyArray_ClipmodeConverter(item, &vals[i]) != PY_SUCCEED) {
1337+
1338+
if(PyArray_ClipmodeConverter(item, &modes[i]) != PY_SUCCEED) {
13351339
Py_DECREF(item);
13361340
return PY_FAIL;
13371341
}
1342+
13381343
Py_DECREF(item);
13391344
}
1340-
} else if(PyArray_ClipmodeConverter(object, &vals[0]) == PY_SUCCEED) {
1341-
for(i = 1; i < n; ++i) {
1342-
vals[i] = vals[0];
1345+
}
1346+
else if (PyArray_ClipmodeConverter(object, &modes[0]) == PY_SUCCEED) {
1347+
for (i = 1; i < n; ++i) {
1348+
modes[i] = modes[0];
13431349
}
1344-
} else {
1350+
}
1351+
else {
13451352
return PY_FAIL;
13461353
}
13471354
return PY_SUCCEED;
13481355
}
13491356

13501357
/*
1351-
* compare the field dictionary for two types
1352-
* return 1 if the same or 0 if not
1358+
* Compare the field dictionaries for two types.
1359+
*
1360+
* Return 1 if the contents are the same, 0 if not.
13531361
*/
13541362
static int
13551363
_equivalent_fields(PyObject *field1, PyObject *field2) {

‎numpy/core/src/multiarray/new_iterator.c.src

Lines changed: 17 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -2316,9 +2316,16 @@ NpyIter_GetIterIndexRange(NpyIter *iter,
23162316
}
23172317

23182318
/*NUMPY_API
2319-
* Gets the broadcast shape if coords are enabled, otherwise
2320-
* gets the shape of the iteration as Fortran-order (fastest-changing
2321-
* coordinate first)
2319+
* Gets the broadcast shape if coords are being tracked by the iterator,
2320+
* otherwise gets the shape of the iteration as Fortran-order
2321+
* (fastest-changing coordinate first).
2322+
*
2323+
* The reason Fortran-order is returned when coords
2324+
* are not enabled is that this is providing a direct view into how
2325+
* the iterator traverses the n-dimensional space. The iterator organizes
2326+
* its memory from fastest coordinate to slowest coordinate, and when
2327+
* coords are enabled, it uses a permutation to recover the original
2328+
* order.
23222329
*
23232330
* Returns NPY_SUCCEED or NPY_FAIL.
23242331
*/
@@ -2361,15 +2368,15 @@ NpyIter_GetShape(NpyIter *iter, npy_intp *outshape)
23612368
}
23622369

23632370
/*NUMPY_API
2364-
* Builds a set of strides which are compatible with the iteration order
2365-
* for data packed contiguously, but not necessarily C or Fortran.
2366-
* The strides this produces are equivalent to the strides for an
2367-
* automatically allocated output created without an op_axes parameter,
2368-
* and should be used together with NpyIter_GetShape and NpyIter_GetNDim.
2371+
* Builds a set of strides which are the same as the strides of an
2372+
* output array created using the NPY_ITER_ALLOCATE flag, where NULL
2373+
* was passed for op_axes. This is for data packed contiguously,
2374+
* but not necessarily in C or Fortran order. This should be used
2375+
* together with NpyIter_GetShape and NpyIter_GetNDim.
23692376
*
23702377
* A use case for this function is to match the shape and layout of
23712378
* the iterator and tack on one or more dimensions. For example,
2372-
* if you want to generate a vector per input value for a numerical gradient,
2379+
* in order to generate a vector per input value for a numerical gradient,
23732380
* you pass in ndim*itemsize for itemsize, then add another dimension to
23742381
* the end with size ndim and stride itemsize. To do the Hessian matrix,
23752382
* you do the same thing but add two dimensions, or take advantage of
@@ -2403,7 +2410,7 @@ NpyIter_CreateCompatibleStrides(NpyIter *iter,
24032410
"if coordinates are being tracked");
24042411
return NPY_FAIL;
24052412
}
2406-
2413+
24072414
axisdata = NIT_AXISDATA(iter);
24082415
sizeof_axisdata = NIT_AXISDATA_SIZEOF(itflags, ndim, niter);
24092416

‎numpy/lib/src/_compiled_base.c

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -565,6 +565,14 @@ arr_interp(PyObject *NPY_UNUSED(self), PyObject *args, PyObject *kwdict)
565565
return NULL;
566566
}
567567

568+
/*
569+
* Converts a Python sequence into 'count' PyArrayObjects
570+
*
571+
* seq - Input Python object, usually a tuple but any sequence works.
572+
* op - Where the arrays are placed.
573+
* count - How many arrays there should be (errors if it doesn't match).
574+
* paramname - The name of the parameter that produced 'seq'.
575+
*/
568576
static int sequence_to_arrays(PyObject *seq,
569577
PyArrayObject **op, int count,
570578
char *paramname)
@@ -604,6 +612,7 @@ static int sequence_to_arrays(PyObject *seq,
604612
return 0;
605613
}
606614

615+
/* Inner loop for unravel_index */
607616
static int
608617
ravel_coords_loop(int ravel_ndim, npy_intp *ravel_dims,
609618
npy_intp *ravel_strides,
@@ -665,6 +674,7 @@ ravel_coords_loop(int ravel_ndim, npy_intp *ravel_dims,
665674
return NPY_SUCCEED;
666675
}
667676

677+
/* ravel_coords implementation - see add_newdocs.py */
668678
static PyObject *
669679
arr_ravel_coords(PyObject *self, PyObject *args, PyObject *kwds)
670680
{
@@ -802,6 +812,7 @@ arr_ravel_coords(PyObject *self, PyObject *args, PyObject *kwds)
802812
return NULL;
803813
}
804814

815+
/* C-order inner loop for unravel_index */
805816
static int
806817
unravel_index_loop_corder(int unravel_ndim, npy_intp *unravel_dims,
807818
npy_intp unravel_size, npy_intp count,
@@ -829,6 +840,7 @@ unravel_index_loop_corder(int unravel_ndim, npy_intp *unravel_dims,
829840
return NPY_SUCCEED;
830841
}
831842

843+
/* Fortran-order inner loop for unravel_index */
832844
static int
833845
unravel_index_loop_forder(int unravel_ndim, npy_intp *unravel_dims,
834846
npy_intp unravel_size, npy_intp count,
@@ -855,6 +867,7 @@ unravel_index_loop_forder(int unravel_ndim, npy_intp *unravel_dims,
855867
return NPY_SUCCEED;
856868
}
857869

870+
/* unravel_index implementation - see add_newdocs.py */
858871
static PyObject *
859872
arr_unravel_index(PyObject *self, PyObject *args, PyObject *kwds)
860873
{

0 commit comments

Comments
 (0)
0