Add Citation for covariance calculation

[ladoramkershner]

Could we add a reference describing the calculation of the covariance?

https://github.com/USGS-Astrogeology/plio/blob/47af64c6f217210ad3409e58d8b0b5e7efd2e6fa/plio/utils/covariance.py#L4

[jessemapel]

What kind of reference are you looking for? The computation is standard error propagation $C_b = J_b(a) C_a J_b^T(a)$ and the jacobian is just the jacobian of the spherical to rectangular transform.

[ladoramkershner]

I guess a reference isn't needed, but maybe a more specific docstring and/or in line documentation would be helpful.

I spent a while trying to see how the equation in this function related to just the covariance-variance matrix, not recognizing that the calculation on line 75 and 76 is actually the error propagation formula. Additionally this function is called compute_covariance, so that is misleading unless what is happening in 78-83 is somehow converting it back to a covariance?

[jessemapel]

I agree the documentation around this is rather confusing. I'd propose the following:

1. Update the docs to indicate that it is using error propagation to convert the covariance from spherical to rectangular. Particularly it should indicate that this require geocentric latitude, this is not correct for geodetic latitude.
2. The return should be changed to either return the full 3x3 covariance matrix, or a 1x6 array. It currently returns the upper triangular portion of the symmetric covariance matrix because that is what ISIS stores in control networks, but it returns it as a 2x3 which makes no sense.

I could see changing the name to something more descriptive, but it is actually computing the covariance matrix from the ground sigmas. Maybe something like compute_rect_covariance? I think it would be better to just improve the documentation instead of trying to rename it.

[ladoramkershner]

I agree with just upping the documentation, I don't think there needs to be a name change. I am also a bit worried about changing the return. Wouldn't that be considered API breaking?

[jessemapel]

That is a fuzzy part of API breaks. I would lean towards yes, and that likely makes it not worth it unless we have other breaks we want to do.

[ladoramkershner]

I am fine with just a documentation update! I will try throwing up a PR tomorrow