8000 `image` description in docstring: towards uniformity? · Issue #4869 · scikit-image/scikit-image · GitHub
[go: up one dir, main page]
Skip to content

image description in docstring: towards uniformity? #4869

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
sciunto opened this issue Jul 30, 2020 · 8 comments
Open

image description in docstring: towards uniformity? #4869

sciunto opened this issue Jul 30, 2020 · 8 comments
Labels
📄 type: Documentation Updates, fixes and additions to documentation 💬 Discussion

Comments

@sciunto
Copy link
Member
sciunto commented Jul 30, 2020 •
edited
Loading

Description

I greped the descriptions of our image parameters ( ggrep 'image : ' | sed 's/.*: ...//' | uniq )and the list reflects the variety

1D, 2D or 3D ndarray of floats, optionally a masked array
2D, 3D or 4D ndarray
2-D array
2D array
2D array, dtype=float
2-D array (integer or float)
2-D array (np.uint8 or np.uint16)
2D array, optional
2-D array (uint8, uint16)
2D ndarray
2D ndarray of double
2D or 3D ndarray
array
array-like
array_like
array_like, dtype=float
array of arbitrary type
array of float
array of int
array, same shape as ``self.image_viewer.image``, or None
array, shape ``label_field.shape + (3,)``
array, shape (M, N[, 3])
array, shape (M, N, 3), optional
array, shape (M,[ N, ..., P])
binary (M, N) ndarray
binary ndarray, shape (M, N)
matplotlib.image.AxesImage object
(M, N[, 3]) array
(M, N) array
(M, N[, C]) ndarray
(M, N[, D]) array
(M, N, D) ndarray
(M, N) ndarray
(M, N) ndarray``
(M, N) ndarray, optional
(M, N) or (L, M, N) array
(M[, N[, ..., P]][, C]) ndarray
(M, N[, P]) ndarray
(M, N[, P]) ndarray, optional
(M, N) uint8 array, same shape as image
(N1, ...,NN[, C]) ndarray
(N1,...,NN) ndarray
ndarray
ndarray
ndarray (2-D, 3-D, ...) of integers
ndarray, 2D or 3D
ndarray (2d or 3d) of ints, uints or floats
ndarray ([M[, N[, ...P]][, C]) of ints, uints or floats
ndarray, ndim=3, dtype=np.uint8
ndarray of dtype int
ndarray of float or uint
ndarray of ints, uints or floats
ndarray, one-dimensional
ndarray, shape (M, N[, 3])
ndarray, shape (M, N[, C])
ndarray, shape (M, N[, P[, ...]])
ndarray, shape(M, N, [..., P,] 3)
nD double or uint8 array
(N, M) array
(N, M, C) ndarray
(N, M) double array
(N, M) float array
(N, ..., M) ndarray
(N, M) ndarray
(N, M) ndarray, optional
(N, M) or (N, M, 3) ndarray
(N, M[, ..., P]) ndarray
(N, M[, P]) ndarray
numeric array
numpy.ndarray
PIL image
[P, ..., ]M[, N][, C] ndarray
tuple
uint8 array
(width, height, 3) or (width, height) ndarray
(width, height, channels) ndarray

We might have places where exceptions are needed, but otherwise, this looks fairly inconsistent. Do we have / can we decide a policy on this?

xref #4407
@sciunto sciunto added 📄 type: Documentation Updates, fixes and additions to documentation 💬 Discussion labels Jul 30, 2020
@sciunto sciunto added this to the 1.0 milestone Jul 30, 2020
@sciunto sciunto changed the title image description in docstring: towards uniformity image description in docstring: towards uniformity? Jul 30, 2020
@jni
Copy link
Member
jni commented Jul 30, 2020

@sciunto AWESOME work. =D But you should sort and then uniq... ;)

I agree that it would be absolutely fantastic to bring this down to some very small number — the biggest difference is whether it's 2D, 2D/3D, or nD, and whether it's grayscale only or allows multichannel. That does not give as many options as listed above 😂

@sciunto
Copy link
Member Author
sciunto commented Jul 30, 2020

@sciunto AWESOME work. =D But you should sort and then uniq... ;)

I tried to find this feature in man uniq. My bad... of course sort does the thing :) Thanks, list updated.

@sciunto
Copy link
Member Author
sciunto commented Jul 30, 2020

PS: my favorite one array of arbitrary type :)

@jni
Copy link
Member
jni commented Jul 30, 2020

This is just a gold mine. My favourite is:

array-like
array_like

... 🤦

@jni
Copy link
Member
jni commented Jul 30, 2020

My suggestions:

array
array, shape (M,)
array, shape (M, N)
array, shape (M, N[, C])
array, shape (M, N, P)
array, shape (M[, N[, ...]][, C])
array, shape (N, D)  # for points

The shapes are there when they restrict the number of dimensions, or when they are used for pattern matching in the documentation, for example, in util.view_as_windows.

Discussion questions:

  • Do we want to specify dtypes? If so, I would append: , numeric, , float, , uint8, integer, ... to the end of the above strings, where required.
  • Do we want to differentiate between NumPy arrays and arbitrary duck arrays? ie do we want to write np.ndarray in places where Cython will be called.

@rfezzani
Copy link
Member

xref #4407 :)

@emmanuelle
Copy link
Member

Thanks for this @sciunto! A pass through docstrings can be done when adding type annotations (see #4794) so this is a good timing to discuss this issue.

@sciunto
Copy link
Member Author
sciunto commented Jul 30, 2020

You're right. It crossed my mind too.

@jni jni mentioned this issue Aug 4, 2020
Closed
@alexdesiqueira alexdesiqueira mentioned this issue Aug 24, 2020
Closed
@scikit-image scikit-image locked and limited conversation to collaborators Oct 18, 2021
@grlee77 grlee77 mentioned this issue Feb 20, 2022
Closed
@scikit-image scikit-image unlocked this conversation Feb 21, 2022
@grlee77 grlee77 reopened this Feb 21, 2022
@mkcor mkcor mentioned this issue Feb 28, 2022
Closed
@jarrodmillman jarrodmillman modified the milestones: 0.21, 0.22 May 19, 2023
@jarrodmillman jarrodmillman removed this from the 0.22 milestone Oct 3, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
📄 type: Documentation Updates, fixes and additions to documentation 4163 💬 Discussion
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@jarrodmillman @emmanuelle @sciunto @jni @rfezzani @grlee77
0