How do I understand the documentation (for Distributions.jl)?

New to Julia
1

I’m trying to learn how to use Distributions.jl to specify probability distributions. I wanted to figure out how to create a multivariate normal distribution object (is “object” the right term?), so I looked at Multivariate Distributions · Distributions.jl.

In that doc, it suggests that there are some easy ways to get a multivariate normal with a zero mean and diagonal covariance without writing out a full vector of means and covariance matrix, but from the docs I wasn’t able to figure out how to do that.

After some searching, I stumbled on this

julia> MvNormal(2, 1)
MvNormal{Int64, PDMats.ScalMat{Int64}, FillArrays.Zeros{Int64, 1, Tuple{Base.OneTo{Int64}}}}(
dim: 2
μ: Zeros(2)
Σ: [1 0; 0 1]
)

Hooray! But I have no idea how to understand that it’s possible to write it this way just from looking at that documentation page.

Can anyone help me string together the pieces? What pieces of that documentation page tell you that you can get an MvNormal by specifying the dim and std. dev?

2

The simplest way for people who are familiar enough with Julia syntax is to directly go into the source code and read how things are defined. For large packages, searching the keywords in the source code and occasionally using @which are typically sufficient for grabbing all the details.

Creating detailed, accurate and up-to-date documentation is extremely time-consuming. Things are changed frequently and it may take a lot of words to explain things that can be concisely expressed in a few lines of code.

3

I think you have a point here. I’m a frequent user of Distributions.jl so I don’t have any issues, but I can certainly see how a newcomer might find the documentation for Distributions.MvNormal to be lacking. I think if you look at the section on Distributions.AbstractMvNormal things should become much clearer, but still, there’s probably room for improvement. As @Norman pointed out, creating good, up-to-date documentation can be time consuming and it’s probably one of the best/easiest ways to contribute to a package that you are first learning about. Maybe you could write some examples and submit a pull request to help others.

1 Like
4

Thank you all for your answers. I certainly appreciate that writing documentation is a difficult job.

I really have next to no experience with Julia, so I was wondering if there are some conventions that I was not understanding. After looking at the source and the Julia docs on constructors, I realized that MvNormal is defined like a regular function and you can overload these functions with differently typed args to define these convenience constructors.

I think I was a little confused by the MvNormal section in the docs, because under that heading it says something like “ordinary users don’t need to be concerned about these internal details” and I thought that referred to the word MvNormal itself.

1 Like