tar_file(), tar_files(), tar_files_input() - when to use which function?

[joelnitta]

The functions tar_file(), tar_files(), tar_files_input() all do similar things and have similar names, so it is confusing to keep track of when to use which function. The documentation for tar_files_input() includes a comparison with tar_files(), so that helps, but how do these compare to tar_file()? Perhaps a mini-vignette or section in the manual comparing them would help (currently the manual only includes tar_target(..., format = "file"), with no mention of the tarchetypes functions).

FWIW I tend to use tar_file() for steps involving input/output files, but not sure if I should be using tar_files() instead...

[wlandau]

tar_files() and tar_files_input() have built-in dynamic branching, whereas tar_file() is only shorthand for tar_target() with format = "file". (Any dynamic branching would require the user to set the pattern argument.) I see what you are saying about documentation, but balanced against the volume of documentation that users need to read, I would prefer not to add something special for this.

[joelnitta]

I see, thanks for explaining that distinction (sorry for not catching 11.7 in the manual, which already covers this).

In the docs for tar_files_input, it says

automatically groups input files into batches

How is the grouping done? Is it not just one batch (branch) per file?

I can understand not wanting to bloat the documentation, but it seems to me at least mentioning tar_file might be useful in Chapter 10.

[wlandau]

In tar_files_input(), you can select the number of batches with the batches argument. If the number of batches is less than the number of files, then files are evenly distributed among batches.

[joelnitta]

I see, thanks for your patience with these questions that are already documented 😓