The documentation of each method of each distribution should be more specific

[nbro]

The documentation of the sample method of the distributions tfp.distributions.Bernoulli, tfp.distributions.Binomial, tfp.distributions.Categorical, tfp.distributions.Multinomial and probably many other distributions (if not all of them) is

Generate samples of the specified shape.

Note that a call to sample() without arguments will generate a single sample.

This is a very generic description. Ideally, the documentation should describe exactly what sample specifically does for each of the distributions.

For example, consider the Binomial distribution and the following program.

from tensorflow_probability import distributions as tfd

d = tfd.Binomial(total_count=4., probs=0.05)
print(d.sample())

which can apparently produce a tensor with either the value 0.0, 1.0, 2.0, 3.0 or 4.0, but it may not be cleary why, so I think that the documentation of each method should be adapted for each distribution, so that newbies can more easily understand the behaviour of each implemented distribution. In this case, sample seems to return the number of 1s in 4 trials (which can either be 0, 1, 2, 3 or 4), but this may not be correct or clear.

I haven't checked the documentation of the other methods, but they probably suffer from the same issue.

[brianwa84]

This information is generally captured in the class-level or init doc, ie take a look at https://www.tensorflow.org/probability/api_docs/python/tfp/distributions/Binomial for more on the distribution.

On Fri, Jan 17, 2020, 6:42 PM nbro notifications@github.com wrote:

The documentation of the sample method of the distributions tfp.distributions.Bernoulli, tfp.distributions.Binomial, tfp.distributions.Categorical, tfp.distributions.Multinomial` and probably many other distributions (if not all of them) is

Generate samples of the specified shape.

Note that a call to sample() without arguments will generate a single sample.

This is a generic description. Ideally, the documentation should describe exactly what sample specifically does for each of the distributions.

For example, consider the Binomial distribution and the following program.

from tensorflow_probability import distributions as tfd

d = tfd.Binomial(total_count=4., probs=0.05) print(d.sample())

which can apparently produce a tensor with either the value 0.0, 1.0, 2.0, 3.0 or 4.0, but it may not be cleary why, so I think that the documentation of each method should be adapted for each distribution, so that newbies can more easily understand the behaviour of each implemented distribution. In this case, sample seems to return the number of 1s in 4 trials (which can either be 0, 1, 2, 3 or 4), but this may not be correct or clear.

I haven't checked the documentation of the other methods, but they probably suffer from the same issue.

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/tensorflow/probability/issues/736?email_source=notifications&email_token=AFJFSI2FEJ5GNQOGDDXQTOLQ6I67JA5CNFSM4KIPRHI2YY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4IHB75WQ, or unsubscribe https://github.com/notifications/unsubscribe-auth/AFJFSIZBBV32XQAPUHRR43DQ6I67JANCNFSM4KIPRHIQ .

[nbro]

@brianwa84 Honestly, I had already quickly read that intro and I couldn't fully and immediately understand the behaviour of sample from it. I think it may not hurt to specifically describe the behaviour of sample (and any other method) for each distribution in the documentation of the method.