Important modifications to be applied the presentation of Workshop 8

pedrohbraga commented 3 years ago

Before developing and modifying this workshop, please read through the presenter and developer protocol carefully and refer back to it regularly as you work.

General issues to be addressed related to the presentation of this workshop

[Priority] Specific to adapting workshops to a remote framework:

[x] Fit this workshop to a 3 to 3.5 hours format. The duration of this workshop should be ~3 hours (including exercises and one or two breaks of 5 minutes; excluding longer breaks). To fit this format, please add, edit, or hide slides from existing workshops. You can begin by hiding repetitive examples, non-essential slides, or some of the additional advanced slides that are included at the end of some workshops. Some workshops will be more difficult to shorten than others, due to their subject matter. It is not a problem to let these workshops run slightly over 3 hours to guarantee accurate and complete information. (Use your judgment). DO NOT delete slides. Use the instruction: hidden_remote tag. See an example below:

---
exclude: true

# Slide title: I love statistics!

### Content: Amazing!
---

[x] Develop new or adapt current exercises to better suit the remote workshop format and the use of breakout rooms. Exercises should be informative and engaging. Remember to leave time for students to work through exercises and ask questions. Refer to these guidelines to find suggestions of exercises promoting active learning. You may use additional resources to create the exercises.

Specific to slide structure, grammar and style

[x] Ensure code is working correctly and that code matches workshop presentation. Continue to check this as you make changes.
[x] Proofread correcting spelling, grammar, or punctuation errors.
[x] Look for and correct the content of slides that overflow the screen.
[x] Look for and correct prose that mentions function names, object names, package names and code chunks that do not use backticks.
[x] Look for and correct unnecessary abbreviations (e.g. use do not instead of don’t).
[x] Correct unnecessary long sentences.
[x] Ensure that the slides are written in a consistent style, which helps with the flow of workshops and student understanding. This is especially important when working collaboratively with other developers.
[x] Include presenter notes to the slides you modify. You can write notes for yourself to read in the presenter mode (press the keyboard shortcut p). These notes are written under three question marks ???. See the example below:

---
The content of this workshop is essential for your graduate studies.

???

Note: _The presenter should sing this slide to the participants_.
---

Specific to the translation of this workshop

[x] Add and translate the modified content to the French version of the workshop.
[x] Proofread and correct spelling, grammar and punctuation errors.
[x] Correct unnecessary long sentences.

General comments

This workshop offers a very good (and ambitious) summary to those interested in generalized additive modelling techniques. While it is an advanced workshop and most participants taking it are assumed to have some knowledge of general linear models and generalized linear models, this workshop would benefit a lot from more mathematical explanations to some of its procedures (especially at its beginning and on those indicated when expanding the basic GAM). There is a useful explanation within section 8 (GAM behind the scenes), which would be best if it came before or incrementally during the presentation to reduce the level of abstraction for participants.

In addition to a push on the mathematical explanation of additive models, this workshop could also benefit from more biological examples (it is mostly done on simulated data).

In addition to the resources available within the presentation, the article Hierarchical generalized additive models in ecology: an introduction with mgcv from Pedersen et al. 2019 has a great review and various examples on generalized additive models.

Separate larger issues to be solved

[x] Solve issue #1.
[ ] Solve issue #2.

Specific issues to be solved

[x] Important to keep in mind: Section "8. GAM behind the scenes" should probably be spread across the workshop, to help participants understand the mathematical side of GAM when they learn how to build their models;
[x] Combine slides where code and output are unnecessarily separated (examples: Slides 14, 15 and 16; Slides 18 and 19; Slides 48 and 49);
[x] Slides 14, 15, 16 could have the code and the figure split into two columns and be incremental (see the developer protocol on how to generate incremental slides);
[x] Adjust situations where the equations or code are displayed without spacing: prefer y_obs ~ s(x) instead of y_obs~s(x) and y_obs ~ s(x) + x instead of y_obs~s(x)+x;
[x] Rephrase the answer to option 2 on Challenge 1 to directly address option 2.: it asks if linearity is justified and it replies as "yes, non-linearity is justified" (which may cause confusion);
[x] Change "3. Multiple smooth terms" to "3. GAM with multiple smooth terms";
[x] Include variable names from Slide 29 (GAM with multiple variables) within code strings (backticks);
[x] Separate basic_summary$p.table and basic_summary$s.table (and their outputs) in different code chunks and output blocks preceded by their explanation;
[x] Highlight (make bold) the definition of the EDF acronym: "estimated degrees of freedom";
[x] Include variable names from Slide 30 (Note on estimated degrees of freedom) within code strings (backticks);
[x] Recall the definition of edf on Slide 31;
[x] Rewrite $p$, $n$, and $n-p$ from Slide 31 (Note on estimated degrees of freedom) as MathJax LaTeX equations (i.e. include them between dollar signs);
[x] Add an explanation for the plot(basic_model) on Slide 32 (GAM with multiple variables);
[x] Separate two_term_summary$p.table and two_term_summary$s.table (and their outputs) in different code chunks and output blocks preceded by their explanation (as recommended above). Do the same on Slide 35.
[x] On Slide 35, highlight the lines (code and output) for Model 3 using #<< ;
[x] On Slide 47 (GAM with interaction terms), capitalize "anova" and include "p > 0.05" between dollar signs;
[x] Combine Slides 48, 49 (and, if possible, 50);
[x] On Slide 53 (Expanding on the basic GAM): add a few recalls on what basis is, on what are link functions, on mixed-effects models;
[x] Separate prop_summary$p.table and prop_summary$s.table (and their outputs) in different incremental code chunks and output blocks preceded by the questions (this is a good opportunity for the presenter to interact with participants since this output has been shown several times during this workshop);
[x] The code output on Slides 66, 67 and 68 (GAM using other distributions) should be preceded by the code that generates them;
[x] Include the code chunk that generates the plot on Slide 68 (GAM using other distributions);
[x] Declutter slides within the "7. Quick intro to GAMM" section to make them more easily readable. You may use incremental slides and line-highlighting to your benefit. You may also separate the information across columns;
[x] Figures generated within section "7. Quick intro to GAMM" should be within the same slides as their code;

Checkout

[ ] Only close this issue after all cases have been ticked and verified.

dschoenig commented 3 years ago

Working on splitting the theoretical part and improving the mathematical explanations (#11), I noticed a couple of other aspects that would be important to fix:

[x] Change fitting method to REML #10
[x] Include example for choosing k #12
[x] Talk about model checking (k and residuals) #13
[x] Improve the "Generalized" section #14

EDIT: Plus some issues with slightly lower priority:

[ ] Mixed models using real-world data #17
[ ] Plotting of smooths for generalized and mixed models #15

dschoenig commented 3 years ago

And in reply to the description of the issue: I think EDF is actually a shorthand for "effective degrees of freedom" (rather than "estimated", see Wood, 2017). This is already addressed by #11

dschoenig commented 3 years ago

As to "Figures generated within section "7. Quick intro to GAMM" should be within the same slides as their code"

Since each pair of plots requires 7 lines of code, it was difficult to put the plots on the same slide while keeping them large enough. So I think it's actually a good idea to keep them separated for now. This whole section is likely to improve once changed to a real-world data set (see #17), where fewer plots may be necessary to show what's going on.

katherinehebert commented 2 years ago

The remaining issues discussed in this thread have been added to this year's issue #19, and this issue is referenced in #19. Closing this issue.

QCBSRworkshops / workshop08