Code Re-Use

[multimeric]

• Alternative to #17
• The theme of this PR is refactoring the episodes to re-use code, and you will notice the net reduction in about ~500 LoC
• Write workflows from chunks directly into _targets.R wherever possible, which simplifies the codebase, for example: https://github.com/carpentries-incubator/targets-workshop/blob/7aa418cdc0da6ac6e17482acbd8f70a0f3bfe48a/episodes/branch.Rmd#L166-L167
• Workflows that are re-used between files have moved into files/plans, with one plan per file.
• User-facing utility functions like clean_penguin_data have moved into files/tar_functions
• Then, whenever we want to show a script to a user (which might be a plan, or a utility function), we just add a file: chunk such as: https://github.com/carpentries-incubator/targets-workshop/blob/7aa418cdc0da6ac6e17482acbd8f70a0f3bfe48a/episodes/branch.Rmd#L317
• Whenever we want to show a subset of a script to a user, we use readLines(file)[lines]: https://github.com/carpentries-incubator/targets-workshop/blob/7aa418cdc0da6ac6e17482acbd8f70a0f3bfe48a/episodes/branch.Rmd#L261
• Add pushd and popd utility functions that let us reduce the number of hidden chunks significantly, because we can instead just hide the utility functions: https://github.com/carpentries-incubator/targets-workshop/blob/7aa418cdc0da6ac6e17482acbd8f70a0f3bfe48a/episodes/branch.Rmd#L343-L351
• Thus, there is only one copy of each script used throughout the repo, which is very easy to edit.
• Closes #16.

[github-actions[bot]]

Thank you!

Thank you for your pull request :smiley:

:robot: This automated message can help you check the rendered files in your submission for clarity. If you have any questions, please feel free to open an issue in {sandpaper}.

If you have files that automatically render output (e.g. R Markdown), then you should check for the following:

• :dart: correct output
• :framed_picture: correct figures
• :question: new warnings
• :bangbang: new errors

Rendered Changes

:mag: Inspect the changes: https://github.com/carpentries-incubator/targets-workshop/compare/md-outputs..md-outputs-PR-19

The following changes were observed in the rendered markdown documents:

 basic-targets.md                                   |    9 +-
 branch.md                                          |   91 +-
 cache.md                                           |    2 -
 config.yaml (gone)                                 |   87 -
 files.md                                           |   22 +-
 files/lesson_functions.R (new)                     |   59 +
 files/packages.R (new)                             |    5 +
 files/plans/README.md (new)                        |    1 +
 files/plans/plan_1.R (new)                         |   21 +
 files/plans/plan_10.R (new)                        |   42 +
 files/plans/plan_11.R (new)                        |   42 +
 files/plans/plan_2.R (new)                         |   10 +
 files/plans/plan_2b.R (new)                        |    9 +
 files/plans/plan_3.R (new)                         |   12 +
 files/plans/plan_4.R (new)                         |   19 +
 files/plans/plan_5.R (new)                         |   31 +
 files/plans/plan_6.R (new)                         |   29 +
 files/plans/plan_7.R (new)                         |   29 +
 files/plans/plan_8.R (new)                         |   35 +
 files/plans/plan_9.R (new)                         |   42 +
 files/tar_functions/README.md (new)                |    3 +
 files/tar_functions/augment_with_mod_name.R (new)  |    6 +
 .../augment_with_mod_name_slow.R (new)             |    7 +
 files/tar_functions/clean_penguin_data.R (new)     |   11 +
 files/tar_functions/glance_with_mod_name.R (new)   |    6 +
 .../glance_with_mod_name_slow.R (new)              |    7 +
 files/tar_functions/write_lines_file.R (new)       |    4 +
 lifecycle.md                                       |   30 +-
 md5sum.txt                                         |   40 +-
 organization.md                                    |   10 +-
 packages.md                                        |   12 +-
 parallel.md                                        |   37 +-
 quarto.md                                          |    2 +-
 renv.lock (gone)                                   | 1793 --------------------
 setup.md                                           |    2 +-
 35 files changed, 566 insertions(+), 2001 deletions(-)

What does this mean?

If you have source files that require output and figures to be generated (e.g. R Markdown), then it is important to make sure the generated figures and output are reproducible. This output provides a way for you to inspect the output in a diff-friendly manner so that it's easy to see the changes that occur due to new software versions or randomisation.

:stopwatch: Updated at 2023-08-01 10:05:36 +0000

[joelnitta]

@multimeric Thanks, I really like how this cleans up the code. I took it one step further and used this approach for almost all the penguin examples - I think it makes more sense once you get in the mental state of looking at the plan_*.R files.

(BTW the rubber ducky "carpentries-bot" is me... for some odd reason sandpaper repos have a habit of doing that!)

If this looks good to you, I'm happy to merge.

[multimeric]

Great! The shame is that if you preferred the files method to the chunk writing method, #17 may have been better to work off. Ah well, at least you've been able to see both approaches this way.

[multimeric]

If you don't like the chunk saving approach, I can remove it from the codebase to simplify things?

[joelnitta]

I still use it in some places, e.g. write_example_plan(chunk = "example-file-show-1") in files.Rmd (if that's what you're talking about), so I think we should leave it.

[multimeric]

Okay, I'm fine with whichever combination of approaches you're happy to work with. Either way removes the redundancy and makes development easier so I'm happy :+1:

[joelnitta]

I realized the external plan file works well for the penguins examples, because they get run repeatedly and gradually build up in complexity. But the chunk approach is nice for short "one-off" examples where it's easier to grok with the plan right there in the Rmd. So thanks for making both available!

[multimeric]

Cool, I'm happy to merge then