-
-
Notifications
You must be signed in to change notification settings - Fork 11.9k
DOC: update structured array docs to reflect #6053 #9056
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.
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
Conversation
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Not a complaint about this PR, but I don't think I like this behaviour:
>>> np.dtype([('', 'f4'),('f0', 'i4'),('z', 'i8')])
ValueError: field 'f0' occurs more than once
In #9054, I change this in some cases to be "index within the unnamed values". Is that a good thing?
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it might be clearer to show these as >>> dt = np.dtype(...), >>> np.zeros(1, dtype=dt)
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems that arrays.dtypes.rst duplicates a lot of the contents here, and perhaps these should be condensed into a single help page
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Missing comma
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is misleading - we should clarify whether "equivalent dtypes" are such that dt1 == dt2, or if simply np.can_cast(dt1, dt2)
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Might be tempting to write this in the following form:
>>> np.zeros(3, dtype=dict(names= ['col1', 'col2'],
... formats= ['i4','f4'],
... offsets= [0, 4],
... itemsize= 12)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Which of course, raises the question of whether np.dtype(**dict) should be added as a shorhand for np.dtype(dict)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Aligning the [...] isn't PEP8. It may take a bit of getting used to but eventually the unaligned versions become easier to read.
|
@ahaldane ping. |
|
Got it, I'll go over it soon. |
f07ea87 to
3a7f388
Compare
|
Updated, and ready to read through. You can view an html version of the current state at https://ahaldane.github.io/user/basics.rec.html |
602e22d to
5be7def
Compare
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"array of length two" and omit the comma. The clause after the comma is essential.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"for example, interpreting ..."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
comma after "purposes"
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe "For simple manipulation of tabular data, other pydata projects, such as pandas, xarray, or DataArray, provide higher-level interfaces that may be more suitable."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"by numpy, but can be manually specified."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could use a rewrite. I'd probably start a new sentence instead of using "with".
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Do we want to number subtitles? Maybe a simple enumerated list would do.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"is an empty string, '', the ..."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"... string and separated ..."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"specifications, all of the same length."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"The optional 'offsets' key is a list of integer byte offsets, one for each field within the structure."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"... to contain all the fields."
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Commas rather than parenthesis. I don't know when the current parenthetical scourge originated, but it seems to be everywhere these days :-(
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there an example of using a scalar array for the rhs? Does scalar array mean 1-D array here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I guess by "scalar array" I mean "unstructured array", will fix.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is there an example of that? Which side has the single field, or is that both sides?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'll try to modify the example, perhaps using different variable names,.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe "The view's" instead of "This view's".
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
and <- comma
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
this <- the
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Could omit "Importantly".
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"such that" <- "so that".
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
though <- thought
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Omit "of".
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What does "equivalent" mean?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
equal, will fix
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
dimension <- dimesions.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
``True`` ?
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What might be the alternative?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Currently in this case we get:
[1]: a = np.zeros(3, dtype='f,f,f')
[2]: b = np.zeros(3, dtype='f,f')
[3]: a == b
FutureWarning: elementwise == comparison failed and returning scalar instead; this will raise an error or perform elementwise comparison in the future
I'll reword the text to more accurately describe what happens.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe "The .... operators always return ..."?
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Many or all? Maybe "no other"?
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
which <- that.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Comma not needed.
numpy/doc/structured_arrays.py
Outdated
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
which <- that
|
I'm not sure that we should be using 'title' instead of italicized NumPy should hire a copy editor, there should be plenty out there in this time of self publishing. |
47f1041 to
b282aff
Compare
|
Updated, thanks a lot. You make a great copy editor! For the styling of the parts of the dtype, my idea was to use them as normal nouns through most of the document (eg, "the field name is.."), except in the dtype-specification section where I need to make clear the format of the tuple, in which case I write |
6ca3fda to
4280fb3
Compare
4280fb3 to
a08da3f
Compare
|
OK, let's get this in. Thanks Allan. |
These are updated structure arrays docs to reflect the changes in #6053.
Don't merge this before #6053.
I'm putting them here now for comments to accompany #6053.
While this PR is open I will maintain an HTML compiled version of these docs at https://ahaldane.github.io/user/basics.rec.html