Review the documentation

[aimalz]

RAIL has documentation explaining the basic structures that Olivia and I are currently overhauling in a fork. Please leave comments on this issue to bring to our attention unanswered questions you wish were addressed in the documentation and specific things that need to be revised, i.e. the parts that don't make sense, and we'll try to fix them as they come up.

[alice-crafford]

These might be a bit specific to me, but some questions I have so far:

• What are posteriors and how are they acquired from the data?
• What are SED's?
• Is galaxy blending when two galaxies at different distances appear at the same place on the sky?
• In the Creation Base Design section, how does your model interpolate/extrapolate data? I could be misinterpreting, but it seems like this is saying that you start with real data, and then alter it to get your mock data. Is this correct? (& if so, how does this work in practice?)

[alice-crafford]

Also:

• From the Degradation Base Design section: What is a DataFrame? Are these what are created in the Creation module and are then altered in the Degradation module to create the mock data?

[alice-crafford]

Here are some comments/questions about degrader documentation:

Grid Selection:

• What are HSC spectroscopic galaxies?
• I don't fully understand "percentile cut" --> what does it mean for there to be a percentile in a spec-z?

LSST Error Model:

• When it says "see the overview paper," specific locations would be helpful :) you might have already addressed this & there are some places where this is done well but there were a few instances where the documentation just said "see the paper"
• After our research meeting I now know these terms, but "fiducial airmass" and "atmospheric extinction" were words I didn't know; if this documentation is targeted at people with less experience, defining these might be helpful

Observing Conditions:

• I feel like there is maybe more jargon-y stuff in this one than the rest; there are several things I haven't heard of, for example:
• What is "nside"?
• What is HEALPIX? weight HEALPIX format?

Quantity Cuts:

• I think it would be good to have a list of the types of data in each of the columns (referred to at the top of the page) in more plain sight somewhere in this documentation. It says "applies a cut to the given columns;" what goes in the columns?

[alice-crafford]

qp demo: storing/retrieving ensembles section: syntax in description doesn't match actual syntax: qp.Ensemble.read_from should be qp.Ensemble.read

[alice-crafford]

There should be info about how to access raw PIT values & plot a histogram in the RAIL evaluation demo

Update: I think I figured this one out; it was just as simple as things being in a 2D array vs. a 1D array