Add ndarray for NumPy users doc

[jturner314]

Motivated by @rcarson3 in #419, I put together an initial "ndarray for NumPy users" document (rendered here). It needs more stuff added (maybe some examples solving the same problems with NumPy and ndarray?), and I'm not convinced that a big table is the best way to organize things, but it's a start.

@rcarson3 What do you think so far?

Where's the best place to put this? Just host it on GitHub at bluss/rust-ndarray and link to it from the README and docs, or is there a good way to put it on its own page in the docs themselves?

Fixes #399

[rcarson3]

@jturner314 I really like this.

I do agree that a giant table might not be a best way to convey the information at once.
I could see potentially something along the lines of breaking the table down into sections like the following:

Array Indexing;
Array Bounds;
Array Operations
Array Creation;
Array Manipulation so like flattening, reshape, transpose;
... maybe Miscellaneous topic.

I feel like examples could be nice to have, but I would definitely say what you have right now is a great start for those of us coming over from other languages. I'll see if I can't come up with a few examples this weekend when I have some more time that could potentially go in here.

Also, one thing that I might like to see added is just a simple mention for how to create a Fortran memory layout array. While it didn't take me too long to find in the docs, I think it'd be nice to have it just listed here as well.

[jturner314]

I added some more stuff and reorganized the big table into sections. (rendered here) Any thoughts?

@rcarson3 That would be awesome if you have any examples to include.

Would some discussion of Array vs. ArrayView vs. ArrayViewMut be helpful?

[rcarson3]

@jturner314 I think the current setup is fine. I don't know if discussions on Array, ArrayView, and ArrayViewMut is really necessary, since the docs do a decent enough job on it. However, if other people have thoughts on the manner then maybe?

I've written some ndarray examples here. It includes some common operations that I thought people might want to do. It could probably use an index array example, but I wanted to get some quick examples together first.

The equivalent numpy version of the code is here.

If you can think of any other common features that might be useful to include let me know, and I'll iterate on these a bit more. I'm not sure if the best place to put them would be in the document just due to length, but maybe they could go in the examples folder. I currently just have them hosted on my repo I made to learn Rust, but I can just as easily make a pull request on your ndarray-for-numpy-users branch for the examples as well.

[jturner314]

Yeah, I think it makes the most sense to put the example(s) in the examples directory because then they get built when running cargo test. This makes it easier to ensure that they don't get out-of-date with changes to the library. I'd prefer to put the Python and Rust programs in their own directory within examples, like this:

examples/
\- ndarray-for-numpy-users/
   |- main.py
   \- main.rs

Will you please submit a PR to my ndarray-for-numpy-users branch?

I added another section to the ndarray for NumPy users document: "Other Rust array/matrix crates". ndarray is the most similar to NumPy, but for some use-cases, other crates may be a better choice (e.g. cgmath for coordinate transformations for computer graphics).

[bluss]

That's really great work.

For C & C on the document, I'd like us to be clear in the style / algorithms we promote.

From the top.

a[a.len()-1] should be a[a.len() - 1] to use spaces around the operators.

Instead of current a[(1,4)] it should be a[[1, 4]] to use the preferred style in both whitespace and brackets IMO.

Slices are fine, the range dots are usually cuddled even when using spaces. So the style would prefer this: x..x + 1 and that's fine.

There's an unqualified .into() call in there, that's not something I'd approve for inclusion. a.slice_axis(Axis(0), (-5..).into()) should be a.slice_axis(Axis(0), Slice::from(-5..))

Where we mention a.dim() and a.shape(), should we mention their differing return types? Probably something about that, to explain why there are two.

For a.t() we can mention it's a view.

Some things we can add:

• Array::ones (it's new, not yet in a released version)

• np.zeros_like(a) with equivalent in Array::zeros(a.raw_dim()) (but this doesn't match the memory layout, just the dimensions)

• Maybe we can mention a.outer_iter() as the equivalent of numpy iter(a), but there is an unfortunate explosion of equivalents for the specific case of a 2D array. For example .genrows() and .gencolumns() are neat producers / iterables.

I don't know if we should avoid mentioning uninitialized. They do approximately the same thing in Python and Rust, but in Rust it's easier to get a broken program by using it incorrectly.

[bluss]

In the spirit of style, I think I'd skip a.shape()[axis] in favour of the len_of method

[jturner314]

Okay, I changed those things. I also did the following:

• Move the page into a module in the API docs (which is only included with the docs feature).
• Mention the ndarray for NumPy users page on the landing page of the API docs.
• Add a table of contents.
• Add a separate "Iteration" section.
• Add some more examples (and move @rcarson3's examples into the ndarray_for_numpy_users module).

The examples maybe could use a little more description or reorganization, but I think they're good enough for the time being. Everything else seems pretty good.

You can view the docs by running cargo +nightly doc --open --features=docs. (The docs also build on stable, but the Markdown parser on stable is buggy and produces incorrect output in some of the tables.)

What do you think? Is this ready to merge? (I'll clean up the commit history first.)

[bluss]

Yes, it's ready for merge. It looks great!

[bluss]

(Feel free to merge when you have rebased it)

[bluss]

🥇 fantastic!