Tutorial alpha user feedback: Spectral Dynamic Causal Modeling Tutorial

[sbrincat]

General

• Based on the title, I feel like users could feel a little confused about why this tutorial (and associated functionality) is within the scope of NB. Everything so far has been about building various kinds of simulations, but this sounds more like data analysis functionality. So, maybe we could a bit more explicit in the Intro what this tutorial is adding, and how that relates to NB as a whole? For example, something along the lines of “Previously, we’ve built models with hand-set parameter values. Now we will show you how you can use Neuroblox to fit model parameters to data. We’ll also demonstrate Neuroblox functionality for simulating fMRI BOLD data and for performing data analysis.” (I think that reflects the main value added for this tutorial?)
• Also, if the above interpretation is correct, maybe we should rethink the title to emphasize the fitting aspect? Maybe something more like “Spectral DCM Model Fitting Tutorial”
• Several plots look quite different from the tutorial, I’m assuming because of randomness in generating connections. Can we set a random seed to make it repeatable?

Cell 3

• There are a few new Julia constructs here that haven’t appeared in previous tutorials: push!(), the colon preceding a function argument (:weight), and the use of the arrow for something other than a connection (:weight => 1/16). Could we give a brief explanation of what those are, and why they are used?
• The model-building structure here is different from that used in the rest of the tutorials, where the components are all defined first, then connected in a second step. Here, each component and its connections are defined together in a loop. I wonder if we might either align this with the other tutorials, or give a brief explanation of why we use a different organization here?

Cell 4

• I found this code difficult to follow. Could we get a bit more of a granular explanation in the text here, eg “Next we define the between-region connectivity matrix. Connections are random, but the adjacency matrix is transformed to ensure it is diagonally dominant…”?

Cell 6

• “Time in seconds” – Is this a typo? In every other tutorial, time is in ms, and there doesn’t seem to be anything different about these calls??

Cell 7

• This is the first usage of get_idx_tagged_vars() in the tutorials. Could we get a brief explanation in the associated text? Eg, “Here, we use the NB function get_idx_tagged_vars() to extract an attribute—the time sampling indices—from the generate system.”

Cell 12-14 / Model Inference

• I feel like we are introducing important new concepts here (I think), but the treatment is as if this is just a little tweak on the same-old things. Can we get a bit more of walking the user through what is new here and an explanation of it? Eg “Now we will show you how to use Neuroblox to fit a model to a specific dataset”. And what exactly are “parameters”? Can they be used with any Neuroblox function or?
• Can we get a quick explanation of what A_prior represents—connections between the neural masses, no? And how that reflect a prior? (or if it doesn’t, maybe a different variable name because that is confusing)
• We haven’t previously seen the ‘split’ argument for system_from_graph(). Could we get like a quick inline comment on what that does?

Cell 15-21 / Setup spectral DCM

• I don’t follow what’s going on in this section. Could we get some explanation in its header text?
• The is the first usage of get_dynamic_states(), defaultprior(), get_eqidx_tagged_vars(), setup_sDCM(), run_sDCM_iteration!(). Can we get a quick explanation of each of those in the text, along the lines of “Here, we use the NB function get_dynamic_states() to .”

Cell 22- / Plotting

• As above, could we have brief explanations for freeenergy(), ecbarplot()
• Maybe some explanation of what “free energy” reflects in this context?