Improve UnfoldSim Docstrings

[jschepers]

Here we can list Doc strings that need to be revised either because they are unclear or incomplete or because their formatting is not correct or inconsistent. Afterwards, we can also have a look at the code to see whether any doc strings are missing for exported functions.

[jschepers]

@behinger Could you please add the missing information for the following docstrings

bases.jl

• [x] PuRF function: Please

  • improve the function description
  • add descriptions for the keyword arguments and the return value
  • and maybe (if you see fit) add second example or adapt existing one
  • decide whether the second signature PuRF(t, n, tmax) should be included or if it's only for internal use and should not be visible

• [x] hrf function: Please

  • decide whether function signature is okay like this or too cluttered and should rather contain only a <keyword arguments> place holder?
  • improve the function description (and format it correctly i.e. one sentence description and a second paragraph if needed.)
  • add descriptions for the keyword arguments and the return value
  • if you like change the example

[jschepers]

@behinger Could you please have a look at/adapt the following docstrings:

component.jl

• [x] MixedModelComponent: " basis::Any: an object, if accessed, provides a 'basis function', e.g. hanning(40), this defines the response at a single event. It will be weighted by the model prediction." -> Is it misleading since a vector is expected? Do we want to change that in the future? (Also for LinearModelComponent)

• [x] Please double-check whether the left-hand side of the formula is ignored for the MixedModelComponent but must be zero for the LinearModelComponent.

• [x] MutlichannelComponent: Revise projection description + add output dimensions. Especially the problem with the two different projection types. Should the pair one also be in the field section or is it confusing?

• [x] simulate_component(rng, c::AbstractComponent, simulation::Simulation) : Clarify docstring

• [x] Check Descriptions of the return value for the simulate_component functions for all component types (Include output type and dimensions)

• [x] simulate_component(rng, c::MixedModelComponent, design::AbstractDesign): revise/clarify docstring; I don't completely understand the part about removing the "normal-noise" from MixedModel. Why is it there and why do we have to remove it? Which code-stub is meant here?

• [x] simulate_component(rng, c::LinearModelComponent, design::AbstractDesign)_ Is it appropriate to say that the return type is Matrix? Is it always Matrix{Float64} or could it also be another type? Is the description of the output dimensions correct?

• [x] weight_σs(σs::Dict, b_σs::Float64, σ_lmm::Float64): Unfortunately, I don't really understand the docstring. Could you please revise/clarify it and add the missing docstring sections.

• [x] simulate_responses(rng, components::Vector{<:AbstractComponent}, simulation::Simulation): Check Returns section (especially output dimensions) and adapt it if it is not correct.

[behinger]

Please double-check whether the left-hand side of the formula is ignored for the MixedModelComponent but must be zero for the LinearModelComponent

We could change this and replace the lhs also with :df_tmp like in MixedModelsComponent then it would be consistentI don't see the downside, except :df_tmp being not useable as a column in events

[behinger]

simulatecomponent(rng, c::LinearModelComponent, design::AbstractDesign) Is it appropriate to say that the return type is Matrix? Is it always Matrix{Float64} or could it also be another type? Is the description of the output dimensions correct?

This was actually surprisingly hard to find out. Turns out we use a ModelFrame in the background. It is theoretically possible by reimplementing a bit to return also other types, but Matrix{Float64} is the default as returned from StatsModels

[behinger]

weight_sigmas - Here it is difficult to provide an example, I think this is such a implementation specific internal function, that we don't need it.

I think in general only the outward facing functions need proper docstrings, for the others it is a nice to have