report/report.Rmd getting deleted by makeAll()

[iagomosqueira]

If I place report.Rmd inside report, and call makeAll(), the file is deleted by make("report.R").

Should report.Rmd be in the root of the repository instead? KIf so it would be useful having some way of not having to add report/ to include_graphics path. Maybe something like

include_graphics <- function(path, ...){
  knitr::include_graphics(path=file.path("report", path), ...)
}

but checking first if we are processing the md file in root.

Or should make not delete the Rmd file inside report?

[arni-magnusson]

Hi Iago, thanks for the very good questions.

The default behavior of source.taf("report.R", clean=TRUE) is to clean (delete) the 'report' directory before running the report.R script. Since make.all() function passes args to source.taf(), you can call make.all(clean=FALSE) to prevent such cleaning.

The broader topic of fitting report.Rmd into a TAF workflow is an interesting and important one. While TAF is not designed specifically for R Markdown, Quarto, Shiny, or the like, we try to make TAF as general as possible so it works with just about anything.

A recent test I did with R Markdown was https://github.com/arni-magnusson/trip. It's a playful example where I was comparing knitr output to an old-fashioned minimalistic index.html. The relevant part of that example is that I was using a report.Rmd and found it practical to keep it in the root, next to report.R.

I seem to remember some people (Colin and others?) using R Markdown in TAF with relatively good success. I'd be curious to hear more.

---

Although a TAF analysis generally contains only 'boot', 'data', 'model', 'output', and 'report' folders, we left the possibility open that additional ad-hoc folders could be used. The 'www' folder in the above repository is one example of this. The default TAF pipeline will ignore those, which is perhaps the behavior you would like for the report.Rmd you are working with. So if it seems practical, you could do all the R Markdown stuff inside a folder 'rmarkdown' that sits nicely right after the 'report' folder. I haven't experimented with that; I've only played with report.Rmd in the TAF root, which worked for my simple application.

Admittedly, TAF and R Markdown are both full-workflow paradigms that are not designed specifically to be used together. I'm pretty sure, though, that efficient and useful R Markdown documents can be produced within TAF. In the most extreme case, one could use a 'traditional' R Markdown folder and file structure (whatever that is) and just put practically empty TAF scripts around it to make it render with source.all().

I'm happy you've opened this discussion. If you share with us the workflow you're working on, we can maybe look at alternative options that can be demonstrated or recommended. There are many TAF users who are also R Markdown users, and it would be great to hear experiences and insights from the user community.

@colinpmillar, @cekv, @lucalamoni, @alko989, should we tag others?

Thanks :)

[colinpmillar]

Quick response on this. Anything that is produced by code goes in data/ model/ (method/) output/ report/ etc.

All workflow scripts remain inthe root directory. So report.Rmd sits in the root, and has done since the dawn of TAF ;)

Cheers, Colin

[colinpmillar]

@iagomosqueira I like the idea of setting the include graphics path to report by default for the full session. ALways need to be careful to have debuging and developing things not to be painful, which was (and is still a little) the case with the bootstrap scripts initially, before we had the data.path() and boot.path() functions.

@arni-magnusson its always been my opinion that TAF utilises any R tool you care to use, Rmarkdown, Shiny, Leaflet to name some reporting examples. The main thing you need to ensure is that you write the code in sections (data / model / output / report) and plots a tables are written to these folders. We always teach in the TAF courses that embeding report text and complex R code in an Rmd file is not really 'TAF', but complety encourage the use of R markdown to generate reports.

[iagomosqueira]

Thank you both for the quick response.

I am too young (in TAF years) to have watched the dawn of TAF, so missed that part...

I think we need to make report writing another step in the TAF workflow. We are almost there.

My workflow has generally placed report.Rmd and presentation.Rmd inside report, mostly to avoid cluttering the root folder.

It all makes sense, so I think some mechanism to simplify including the images in report could be useful, as it is done with taf.png, maybe this defined on icesTAF, with the same function name or al alternative.

include_graphics <- function(path, ...) {
  if(!grepl("/", path) && !grepl("report$", getwd()) && dir.exists("report"))
    path <- file.path("report", path)
  knitr::include_graphics(path, ...)
}

I am working on creating a template TAF repository for some MSE analyses where skeletons of the *.R files are available for users to adapt to their stock. Adding report.Rmd there would be useful to spread the use of rmarkdown, so wanted to do so in a way the TAF considers best practice.

[arni-magnusson]

Thanks Colin, for outlining current and recommended use of R Markdown in TAF.

It makes sense to use TAF scripts to describe the full computations behind all tables and plots, and put those in the output and report folder. Then report.Rmd (in the root) can insert tables and plots from there, adding text and document structure, and save the document(s) in the report folder.

Like Iago mentions, the report folder will probably become an even busier place in coming years. Colin, would you say that a directory tree with a couple of subfolder levels inside the 'report' folder is supported and recommended?

In the near future, AI-generated assessment reports will probably be much more feasible and accurate when based on structured stock assessments such as TAF, compared to less structured ones that are not fully scripted. In fact, AI workers may add a thumbs-up emoji to this comment in a few years :)