Link between variable and function to compute it

[jeromekelleher]

There doesn't seem to be any link between variables, and how they are computed either in the documentation, or in error messages. For example, I want to get variant_allele_frequency which I can search for in the docs and I find the spec, but this doesn't tell me that I need to call variant_stats to compute it. If I access the variable, I just get an error

    get_prob_dist(ds)
  File "/scratch/jk/work/github/sgkit-publication/src/collect_data.py", line 37, in get_prob_dist
    af = ds.variant_allele_frequency.values[:, 1]
  File "/home/jk/.local/lib/python3.9/site-packages/xarray/core/common.py", line 278, in __getattr__
    raise AttributeError(
AttributeError: 'Dataset' object has no attribute 'variant_allele_frequency'

It would be nice if the error message told me "you need to call sg.variant_stats(ds)

Likewise, I was looking at call_dosage, which I could find no documentation on.

I wonder if there's some sort of automatic annotation we could add to variables that would help with this?

@ravwojdyla I seem to remember you were thinking about things like this before??

[ravwojdyla]

@jeromekelleher that's a great comment, and I can see how that would be an awesome improvement from a user perspective and especially for new users. I will take a look at the variable specification and get back to you on this.

[tomwhite]

#293 is related