Conventions doc

[janden]

We are getting to the point where we have a lot of conventions that may or may not be explicitly articulated in the code. There are also cases where different parts of the code use different conventions. In that case, it would be good to indicate what the goal convention should be so that we can change things as we go along.

Some examples that come to mind are:
– YX and ZYX convention for images and volumes.
– Grid indexing (inclusive of end points or not, flipped y axis or not).
– Rotation is followed by shifting (class averaging, simulation).
– Projection as integral of φ(R [x, y, z]) dz or φ(Rᵀ [x, y, z]).
– Similarly, rotation of images and volumes: by R or Rᵀ.
– Euler angles (this one's easy).
– CTF parameters.

I'm probably missing things here (and we'll probably want to add more stuff later), but it's probably a good idea to start this document somewhere so we have a place to add this type of information.

FYI: Relion has a similar (albeit quite sparse) document here: https://www3.mrc-lmb.cam.ac.uk/relion/index.php/Conventions_%26_File_formats

[janden]

Noting that this could also include terminology (box size, etc.) and notation (L vs. N vs. n, and so on).

[garrettwrong]

This is great, thank you. I considered adding some of this to the internal developer google doc, but seeing your broader list I think it would be best for this to be in our sphinx docs (which need some refreshing anyway).

Offhand one thing that would also be worth writing down is the real/complex conversion, which can be found in a few places (fspca.py for example).

[janden]

Right. So this document could also include the definition of the basis functions, and so on.

There's a bit of a gray area here between definitions and more comprehensive design documents (that would outline not just what the algorithms are computing, but how). Still, I think this is a good starting point.

We can include formulas pretty easily in Markdown, right? If not, there should be a sphinx plugin somewhere.

[chris-langfield]

A note following the discussion in #522 that we plan to phase out ensure, whether as we encounter it or as one wholesale change. Will make an issue too

[janden]

It might be good to split this into two documents: mathematical conventions (formulas, etc. as I listed above), and coding conventions/terminology (so L, n, etc. ensure vs. assert, docstring format, and so on).

[garrettwrong]

I think @chris-langfield has some recent attempt at writing a few conventions down.

I'm sort of wondering if it would be easier to have a conventions/methodology/theory section in the gallery instead of each of us having random google/latex/text/paper documents floating around. Not sure the right name exactly, but could work that out. I think it would be cool to showcase the rotation demo Chris put together as well.

One question is how much less convenient is it to write this stuff up in the gallery. @j-c-c might know.

[chris-langfield]

I think this would be really useful! Maybe something with the word "Background". Should be a separate section from Experiments and Tutorials maybe