diff options
Diffstat (limited to 'doc/neps')
| -rw-r--r-- | doc/neps/missing-data.rst | 55 |
1 files changed, 49 insertions, 6 deletions
diff --git a/doc/neps/missing-data.rst b/doc/neps/missing-data.rst index 5ced54be2..dbf9765b5 100644 --- a/doc/neps/missing-data.rst +++ b/doc/neps/missing-data.rst @@ -690,13 +690,56 @@ There are 2 (or 3) flags which must be added to the array flags:: /* To possibly add in a later revision */ NPY_ARRAY_HARDNAMASK -****************************** -C API Access: Masked Iteration -****************************** +******************************************** +C Iterator API Changes: Iteration With Masks +******************************************** + +For iteration and computation with masks, both in the context of missing +values and when the mask is used like the 'where=' parameter in ufuncs, +extending the nditer is the most natural way to expose this functionality. + +Masked operations need to work with casting, alignment, and anything else +which causes values to be copied into a temporary buffer, something which +is handled nicely by the nditer but difficult to do outside that context. + +First we describe iteration designed for use of masks outside the +context of missing values, then the features which include missing +value support. + +Iterator Mask Features +====================== -TODO: Describe details about how the nditer will be extended to allow -functions to do masked iteration, transparently working with both -NA dtypes or masked arrays in one implementation. +We add several new per-operand flags: + +NPY_ITER_WRITEMASKED + Indicates that any copies done from a buffer to the array are + masked. This is necessary because READWRITE mode could destroy + data if a float array was being treated like an int array, so + copying to the buffer and back would truncate to integers. No + similar flag is provided for reading, because it may not be possible + to know the mask ahead of time, and copying everything into + the buffer will never destroy data. + +NPY_ITER_ARRAYMASK + Indicates that this array is a boolean mask to use when copying + any WRITEMASKED argument from a buffer back to the array. There + can be only one such mask, and there cannot also be a virtual + mask. + +NPY_ITER_VIRTUALMASK + Indicates that the mask is not an array, but rather created on + the fly by the inner iteration code. This allocates enough buffer + space for the code to write the mask into, but does not have + an actual array backing the data. There can only be one such + mask, and there cannot also be an array mask. + +Iterator NA-array Features +========================== + +NPY_ITER_USE_NAMASK + If the operand has an NA dtype, a mask, or both, this adds a new + virtual operand to the end of the operand list which iterates + over the mask of the particular operand. ******************** Rejected Alternative |