Moments documentation is confusing to users

[stefanv]

We received a question on StackOverflow:

For central moments:

1. What do each of the values represent? Since the (0,0) element is 16, I get this number corresponds to the area of the square of 1s, and therefore it is mu zero-zero. But how about the others?

2. Is this always a symmetric matrix?

3. What are the values associated with the famous second central moments?

[emmanuelle]

I posted an answer on StackOverflow, which could serve as a basis to improve the doc.

[ahojnnes]

I +1'd your answer, thanks! But I am not really sure as how to
significantly improve the documentation, as we are already referring to
the relevant literature and the same Wikipedia page you are referring to
in your answer on SO. What do you think?

On Wed, Aug 10, 2016, at 09:23 AM, Emmanuelle Gouillart wrote:

I posted an answer on StackOverflow, which could serve as a basis to
improve the doc.
— You are receiving this because you were assigned. Reply to this
email directly, view it on GitHub[1], or mute the thread[2].

Links:

1. Moments documentation is confusing to users #2239 (comment)
2. https://github.com/notifications/unsubscribe-auth/AAIMo-kb5TaBhyXr7cH2gXySg_dVy7Dgks5qeXxogaJpZM4JfTNo

[stefanv]

Moments documentation is confusing to users

[Don86]

Hi, I'm new to contributing, and I'd like to contribute to this please.

[artorias111]

Can I take this up if no one's working on it at the moment?

[lmmx]

I wrote a little explainer on image moments [related to image processing code in another library] here earlier this week, is this the kind of overview you were looking to put in the docs?

[stefanv]

@lmmx I think this is a great start. I wonder if we can turn it into an interactive notebook illustrating the concepts as you go along. Then, we can either add a tutorials section to our documentation, or add this to https://github.com/scikit-image/skimage-tutorials

[lmmx]

Great idea @stefanv, yes, the way the higher order moments [of the various kinds] are built up from the lower order ones would be really well-suited to a notebook style exposition, and if they'd support LaTeX too that'd be perfect (markdown Unicode can only do so much). I wasn't aware of the skimage-tutorials repo but that'd be the perfect venue yes! There is something similar in OpenCV's docs, which very briefly mentions moments in the first subsection. Much easier to 'show' than 'tell'

[stefanv]

Both NumPy and NetworkX have now added notebook tutorials to their documentation. @rossbar may be willing to lend a hand for skimage too, given that he's done it twice! The idea is to use Jupytext so that notebooks can be stored as markdown files. You can use LaTeX inside the markdown cells to expose mathematics.

[rossbar]

rossbar may be willing to lend a hand for skimage too, given that he's done it twice!

I'd be more than happy to help set this up or chat about it! One of the benefits is the generation of a static site from the notebooks that ends up (IMO) being a really nice pedagogical resource. For example, here's what we have for numpy and networkx (not yet deployed).

[stefanv]

I'd be more than happy to help set this up or chat about it! One of the benefits is the generation of a static site from the notebooks that ends up (IMO) being a really nice pedagogical resource. For example, here's what we have for numpy and networkx (not yet deployed).

That looks fantastic; I hope we can do something similar here.

[lmmx]

Wow that is awesome, would not have thought a 30 line makefile thrown onto CI would make such a lovely site! I second that call to aim for something similar ☺️

[lmmx]

I got around to reworking my notes into a notebook and turning the equations into LaTeX, it's looking great! 😄

Moving this discussion to the skimage-tutorials thread and I think this can be closed whenever you're ready 👍

[stefanv]

Closing this issue in favor of scikit-image/skimage-tutorials#58