Turing.jl: Lessons learned and open questions to improve documentation

[scheidan]

Thanks for all the nice work!
I've recently implemented my first "real" model in Turing. To get it running I had to overcome a couple of (undocumented) obstacles listed below. My hope is that my beginner perspective can help to improve the documentation (I'd be happy to contribute to that).

Lessons learned and open questions:

1. You cannot use @model in a module, see #592. The error message is unfortunately no helpful.
2. The models definition is not declarative like in WinBugs or Jags, i.e. the order of the statements matters like in STAN.
3. Arrays of parameters must be preallocated and filled with a loop:

Y = Array{Real}(undef, W, N)
for w in 1:W, i in 1:N
      Y[w,i] ~ Weibull(shape[i], scale[w])
end

1. List comprehension like Y = [ ~ Weibull(shape[i], scale[w]), for i in 1:3, w in 1:5] does not work.
2. When/why should I use TArrays? Can I run in trouble with normal arrays?
3. tzeros(4) does not work: ERROR: KeyError: key Symbol("##513") not found (on Turing v0.5.1+ #master)
4. TArrays do not work with more than one dimension. For example this code fails with LoadError: setindex! not defined for TArray{Real,2}:

 Y = TArray{Real}(W, N)
    for w in 1:W, i in 1:N
        Y[w,i] ~ Weibull(shape[i], scale[i])
    end

1. Unlike normal arrays, TArrays are created without the undef keyword. So this works: TArray{Real}(4), but this not TArray{Real}(undef, 4).

[trappmartin]

Thanks a for taking the efforts to report all the issues you ran into. I'll make sure we have individual issues for them so we can work on resolving those issues.

Here are a few comments:

1. List comprehension in Turing works using:

Y ~ [Weibull(shape[i], scale[w]) for i in 1:3 for w in 1:5]

1. A TArray is necessary for all particle based sampling techniques. I'll make sure we add details into the documentation. Currently, there is a possibly out of date documentation of TArray's on the GitHub wiki.

2. @yebai we should probably change this so that we use the standard Julia syntax here.

[scheidan]

Thanks, that's already very helpful!
I've tried array comprehension, but I could not get it working, see #604.

[cpfiffer]

@scheidan Thank you so much for compiling this! It's a superb list. I'll get everything we can into the documentation.

On note 6, did this show up when used from the REPL? We've made a couple changes to the display call that prints the contents of a TArray, so I would try updating Libtask and seeing if that persists. This should hopefully solve note 7 as well, as I recently expanded the multi-index support for the TArray. If it does not, could you please open a task for it over at the Libtask repo?

@yebai Just to clarify for the docs on point 5 (when to use a TArray), this is any time a sampler involves a particle? If that's the case, which samplers are safe and which aren't? I'll add a TArray section for this in the docs.

[trappmartin]

The following samplers require a TArray.

• IPMCMC
• IS
• PG
• (PMMH) because it requires a SMC sampler
• SMC

[scheidan]

@cpfiffer Thanks for the hint to update Libtask! With the current master the points 6 and 7 are solved.