refactor/decide on API

[beckermr]

To do:

• come up with API examples
• define all the use cases
• decide on stuff below

We agreed to decide on an API and/or format for:

• correlation functions
• covariances
• power spectra
• redshift distributions
• window functions
• Bandpass information. Currently hacked by using Tracer.z and Tracer.Nz, but this could be done in a more sophisticated manner.
• cluster counts
• cluster lensing
• SNe data

Some of this exists and other parts do not yet.

We also want APIs for:

• quick cov. matrix inversions
• easily access all elements of the data vector containing one particular type of correlation (e.g. EE or BB or +R etc.)
• easily access all elements of the data vector associated to one particular pair of tracers.
• standards for diffing data and/or determining if two datasets are the same
• Extracting the angle values, mean and, covariance of specific bin pairs as numpy arrays
• Masking out scales in specific bins or globally
• Masking out entire bin pairs
• Extracting the distribution for a named tracer
• Attaching a covariance/precision to an incomplete sacc object
• Adding a new bin pair to an incomplete sacc object
• Making a copy of a sacc object
• Building up a sacc object progressively from e.g. rows in a table
• Plotting data (?) This is optional.
• unique ids
• checksumming
• your thing here

[slosar]

You will find that many of these things are in there already, especially cutting on various things (for example, you could now specify lmin, lmax, zmin, zmax and it will cut for you and do the right thing with cov matrices), or you can cull correlations in different redshift bins, there are plotting routines already, etc. It also has an automatic and transparent cov/precision matrix inversion. It can store matrix as diagonal, block-diagonal or dense, however, for example if you store covariance as block diagonal and ask for precision, it will force it to dense on inversion, so not everything is done quite right. Having a general sparse matrix would also be useful. I don't think we'll ever need very complex linear algebra, our datasets will always be up to a few thousand elements in data vector and dense routines can invert this these days without issues. You can also has datasets that just specify cov matrix and another one that specifes the mean and load them up as a pair (useful for mocks when one cov matrix is there for many realizations). It can also coadd saccs in Cinvse way. However, our logic so far has been -- if you need something, code it up. I think it works pretty well as long as the basics are agreed.
I think having a few utilities in command-line to do basic things like merging, splitting, plotting, etc would be nice.

[beckermr]

Yep the api has quite a bit of these things already. The goal here is to take stock of what is there, figure out what we want to do in addition, and make sure when we add everything it is all coherent.

[rmjarvis]

I have an issue in TreeCorr to support outputting to SACC format, but it sounds like maybe this isn't really stable yet. Especially given that there aren't any releases or tags for this repo yet.

Please ping me on that issue when the API settles down and you think it would be worth it for me to work on that. I don't want to do something there if it will end up having to be redone when you change stuff over here.

[joezuntz]

This issue has been dealt with in the v 0.2.0 release.