Update docstrings of pm.set_data and model.Data

[bwengals]

Adds docstrings describing how to track changing shape of MutableData in the likelihood. Meant to address issue #5987. The recommended solution is then to set the shape=x.shape, like this:

import pymc as pm                                                                       
with pm.Model() as model:                                                               
    x = pm.MutableData('x', [1., 2., 3.])                                               
    y = pm.MutableData('y', [1., 2., 3.])                                               
    beta = pm.Normal('beta', 0, 1)                                                      
    obs = pm.Normal('obs', x * beta, 1, observed=y, shape=x.shape) # <--- here                      
    idata = pm.sample(1000, tune=1000)   

with model:                                                                             
    pm.set_data({'x': [5., 6., 9., 12., 15.]})                                               
    y_test = pm.sample_posterior_predictive(idata)                                      
y_test.posterior_predictive['obs'].mean(('chain', 'draw'))

Major / Breaking Changes

None

Bugfixes / New features

None

Docs / Maintenance

Add recommendation to docstrings relevant to prediction and posterior predictive sampling.

[codecov[bot]]

Codecov Report

Merging #6087 (163e2fa) into main (0b191ad) will increase coverage by 2.59%. The diff coverage is n/a.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6087      +/-   ##
==========================================
+ Coverage   89.54%   92.14%   +2.59%     
==========================================
  Files          72       92      +20     
  Lines       12929    21061    +8132     
==========================================
+ Hits        11577    19406    +7829     
- Misses       1352     1655     +303     

Impacted Files	Coverage Δ
pymc/data.py	80.08% <ø> (ø)
pymc/model.py	88.23% <ø> (ø)
pymc/variational/inference.py	84.97% <0.00%> (-1.13%)	:arrow_down:
pymc/printing.py	86.08% <0.00%> (-0.58%)	:arrow_down:
pymc/distributions/logprob.py	97.31% <0.00%> (-0.42%)	:arrow_down:
pymc/distributions/shape_utils.py	98.95% <0.00%> (-0.33%)	:arrow_down:
pymc/distributions/mixture.py	95.40% <0.00%> (-0.32%)	:arrow_down:
pymc/distributions/simulator.py	87.23% <0.00%> (-0.27%)	:arrow_down:
pymc/distributions/continuous.py	97.50% <0.00%> (-0.01%)	:arrow_down:
... and 55 more

[junpenglao]

Is this ready to merge?

[bwengals]

Took another crack at it, basically made the docstring more minimal and added an example as per your suggestion @ricardoV94.

Would it be nice to also have the syntax allow pm.set_data(y=y) as well as pm.set_data({'y': y})? a la xarray?

[ricardoV94]

Would it be nice to also have the syntax allow pm.set_data(y=y) as well as pm.set_data({'y': y})? a la xarray?

I guess so ;)

[bwengals]

One last question, if you don't mind, I can't seem to figure out why pre-commit isn't happy. Since this PR just changes docstrings, what's it saying about numpy, positional arguments?

[ricardoV94]

That was fixed today. If you rebase from main it should go away