Dedicated vignette on wildcard templating

[wlandau]

Ref: #353. As @lorenzwalthert suggested, we should caution users to come up with wildcards that do not conflict with existing text in the commands.

[lorenzwalthert]

Thanks for opening this. In case you did not know: If want to refer to the exact comment in that issue, you can get the link from right clicking on "xx hours ago" in "lorenzwalthert commented xx hours ago" in the header of the comment. Learned that from Kirill 😊

[lorenzwalthert]

And let me know if I can assist on this, as it is in principle an easy task. But maybe it adds more overhead and you wanna do it yourself. 😊 Let me know.

[wlandau]

If want to refer to the exact comment in that issue, you can get the link from right clicking on "xx hours ago"...

That is my usual preference, but I was away from a proper computer.

And let me know if I can assist on this, as it is in principle an easy task.

Yes, I would love help. Thank you!

[lorenzwalthert]

So would you want to give an outline? Because I don't know drake very well (yet) so I want to make sure I can focus on the right aspects.

I thought about:

• Quick description of what a wild card is and why it is useful (including recycling property).
• mention two functions plan_analysis() and make_plan() and their relationship. Not sure how to describe.
• Word of caution (reason for this issue) plus recommendations to use consistent wild cards, e.g. analysis__ and dataset__.
• Example (maybe simply taking from help file, or create a new one).

[wlandau]

Yeah, let's outline it together. From bullet 2 in your list, I think we might even expand the vignette to cover workflow plan data frames in general. Workflow plans are at least as mysterious, and they might even deserve more attention than wildcards. Throughout, we could build on one of the existing examples, maybe the GSP example.

• What is a workflow plan data frame?
  • Role in make().
  • Possible comparison to Makefiles.
  • drake_plan().
• Why is it a data frame and not a file?
  • You can manipulate it (more easily than a Makefile).
  • Workflow plan from the GSP example: generate lots of targets easily with combos() or expand.grid().
  • expand_plan() generates replicates.
• Wildcard templating: a tool for generating lots of targets.
  • plan_analyses()
  • plan_summaries()
  • evaluate_plan()
  • Need to avoid conflicts with non-wildcard text. Maybe use trailing double underscores.

[lorenzwalthert]

Ok, will try to get us started this or next week on this. Most likely, I will miss a few things though and need help from you 😊

[wlandau]

I would really appreciate that, thank you!

[wlandau]

FYI: when you are ready for a PR, would you submit it to https://github.com/wlandau/drake-manual? I am moving all the vignettes and HTML widgets to a large online bookdown-powered user manual: (ref: #332 (comment)).

Closing in favor of ropensci-books/drake#5.

[lorenzwalthert]

Sure