Clarifies notation and units in Ensemble Kalman Inversion documentation

[navidcy]

Attempts to resolve #46.

[navidcy]

@glwagner and @adelinehillier, how does it read now? Feel free to edit at your liking.

[glwagner]

@navidcy do we have docs previews?

[glwagner]

Thanks @navidcy, I appreciate the extra verbosity.

[navidcy]

@navidcy do we have docs previews?

https://clima.github.io/EnsembleKalmanProcesses.jl/previews/PR47/ensemble_kalman_inversion/

[glwagner]

Is Gamma_y a scalar variance or a covariance matrix (eg curly N is the multivariate Gaussian)... ?

[navidcy]

Is Gamma_y a scalar variance or a covariance matrix (eg curly N is the multivariate Gaussian)... ?

Hm, didn't think of that.
Still Γ is positive definite and thus the inverse square root makes sense, right?

[glwagner]

From Iglesias et al (2013):

I think this means \Gamma_y is a matrix in general (allowing each observation to have a different variance and also cross-correlations between observations), so maybe the manipulations you've made in the update equation aren't universally valid?

[navidcy]

Even if it's a matrix, it should be a positive definite one. The inverse square root is then, nothing else, from the eigen decomposition of Γ but with the inverse square root of the eigenvalues of Γ in the diagonal matrix. Right?

[navidcy]

But perhaps it's simpler if we go back to Γ^{-1}. :)

[glwagner]

Even if it's a matrix, it should be a positive definite one. The inverse square root is then, nothing else, from the eigen decomposition of Γ but with the inverse square root of the eigenvalues of Γ in the diagonal matrix. Right?

Ah, I see.

But perhaps it's simpler if we go back to Γ^{-1}. :)

Your call.

[navidcy]

Even if it's a matrix, it should be a positive definite one. The inverse square root is then, nothing else, from the eigen decomposition of Γ but with the inverse square root of the eigenvalues of Γ in the diagonal matrix. Right?

Ah, I see.

Well, now that I'm thinking about it, same questions arise if Γ is a matrix and we write Γ^{-1}. Does the inverse exist and is it well-defined? So I vote for keeping the symmetric version and adding a clarification, I'll do that. :)

[glwagner]

Even if it's a matrix, it should be a positive definite one. The inverse square root is then, nothing else, from the eigen decomposition of Γ but with the inverse square root of the eigenvalues of Γ in the diagonal matrix. Right?

Ah, I see.

Well, now that I'm thinking about it, same questions arise if Γ is a matrix and we write Γ^{-1}. Does the inverse exist and is it well-defined? So I vote for keeping the symmetric version and adding a clarification, I'll do that. :)

Okay. Also need to clarify that Gamma_y is a covariance matrix rather than variance and N is the multivariate Gaussian distribution. It could be nice to remark on the meaning of Gamma_y too (represents uncertainty, including correlated uncertainty, in the observations?)

[navidcy]

@glwagner have a look at 46b0969 and feel free to rephrase to make it even clearer! :)

[odunbar]

Thanks! A few small comments.

RE notation - we have a glossary which links notation in code docs and the application examples. We have tried to be consistent here, so changing these will require its own PR. as things will need to change everywhere.

RE the formulas, the notation we use matches papers that describe the algorithms as well as how they are implemented, so i think we should leave these.

[navidcy]

RE notation - we have a glossary which links notation in code docs and the application examples. We have tried to be consistent here, so changing these will require its own PR. as things will need to change everywhere.

Perhaps raise this as an issue (if it's not already there)?

[navidcy]

preview @ https://clima.github.io/EnsembleKalmanProcesses.jl/previews/PR47/ensemble_kalman_inversion/

[navidcy]

@odunbar I did everything, do you want to have another look?

[odunbar]

I'm happy except for the typo, LGTM, thanks Navid!

PS you can view the docs by going the the bottom of the thread, and click Details in the documenter/deploy — Documentation build succeeded section

[navidcy]

bors r+

[bors]

Build succeeded:

• docs-build
• test_success