asar
Please consult the README page for installation instructions.
If you are receiving the following error when trying to download the package:
Using GitHub PAT from the git credential store.
Initiating curl with CURL_SSL_BACKEND: openssl
Error: Failed to install 'unknown package' from GitHub:
HTTP error 403.
Resource protected by organization SAML enforcement. You must grant your OAuth token access to this organization.If you’re a member of the NMFS OST organization, you can authorize your token to solve this issue.
Otherwise, please download the package using this code:
install.packages("asar", repos = c("https://nmfs-ost.r-universe.dev", "https://cloud.r-project.org"))create_template() isn’t working. What do I do?
This could mean a lot of things. Most of the time, when
create_template() is not working, it means you are missing
a key argument to the function. Make sure to read the error message(s)
clearly and check the ‘report’ folder where all of the file were
created. If you have exhausted your options and double checked that you
have all of the correct arguments, then please open an issue.
asar was designed to create reports for single species.
As a workaround, you can combine multiple species using “and” in the
species argument of create_template(). For
example, the following code will produce a report with two species in
the title, though a cover image must be added manually since cover
images are matched to single species:
create_template(species = "Species A and Species B")
We encourage users writing species complex/multispecies assessments
to remember that the reports are highly customizable both before and
after the skeleton is created. For example, the
create_template() command allows for customization by
providing custom section options. After the skeleton has been created,
advanced Quarto users can edit the YAML, chunk options, and other
components of the report, and everyone can customize the report’s
text.
While we have striven to add sufficient options for customization, we highly discourage changing the formatting or adding many sections so that the final document does not stray far from the intended, standardized format.
output_and_quantities in the skeleton?
This chunk is what we call the preamble. It loads in commonly-used estimates and quantities that you can reference throughout your report, making the document dynamic. By updating the values calculated in your report folder’s preamble.R script file, you can easily update the values throughout your report.
To reference these quantities in your text, please use the following notation:
For example, if start_year = 2025 and your report
contained this text:
The current year is
`r start_year`.
It would render as:
The current year is 2025.
For more help using Quarto efficiently, please see our markdown guide.
Please refer to the accessibility vignette’s guide on editing alt text and captions.
Please refer to the Acronyms and Glossary section of the accessibility vignette for guidance on how to use acronyms and edit the glossary.
You may be using a version of Quarto older than v1.6. Please read this Discussion post detailing how to check which version you have and update it.
You will notice that the order of your figures and tables in their respective 08_tables.qmd and 09_figures.qmd docs will determine their numbers in the report. This might result in Table 2 being referenced before Table 1, for instance, in your report.
We are encouraging users to keep the order as-is for a few reasons.
First, the predictability of standardized figure and table order could
prove useful when comparing reports. Second, the choice of where to
prioritize the figure/table order- in the Figures and Tables sections,
or in the main text- is somewhat of a personal preference, rather than a
hard rule. Third, as far as we know, a fix isn’t yet possible with
Quarto. We are choosing to focus on building other features for
asar.
However, we understand that some will strongly prefer to set the order of their tables and figures. You can try manually changing the order of the figure and table chunks in the 08_tables.qmd and 09_figures.qmd docs, but this isn’t a reproducible or permanent solution.
tables_dir and figures_dir at the tops of my
figures and tables docs?
We tried to implement relative filepaths for these objects but decided to return to the original workflow for two reasons.
Hardcoding getwd() into the path doesn’t work; when
rendering your report, Quarto will recognize your “report” folder as the
working directory, which probably isn’t your actual working
directory. This will result in a rendering error.
While hardcoding here::here() into the path
does work, we recognize that some users may be unfamiliar with
the here package and
are not able to learn another tool while already learning
asar. We highly recommend checking out this awesome
package, but in the meantime, we are not going to force its
use.
If you want to ensure tables_dir and
figures_dir are relative filepaths (which may be essential
if you are collaborating), you can directly edit these paths yourself
and reset them using getwd(), here::here(), or
some other option.
compilation failed- error
LaTeX Error: Something's wrong--perhaps a missing \item.
See the LaTeX manual or LaTeX Companion for explanation.
Type H <return> for immediate help.
...
l.419 \end{CSLReferences}The above error message is created due to a bug introduced in Quarto in the last year where the notation in 07_references.qmd creates an issue when there is no in-text reference in the text. To correct this, please add a temporary reference to any of the Quarto files in the outlined document (only if you are using the default asar_references.bib file), then replace it with real references when ready. Here is an example “temporary reference”:
Here is an example of an in-text citation (@methot_stock_2013).
! LaTeX Error: No support files for \DocumentMetadata found.
The above error message occurs when LaTeX packages necessary for rendering haven’t been installed.
We typically encourage users to install
the default tinytex bundle (“TinyTeX-1”, installed via
tinytex::install_tinytex()). This bundle contains most, but
not all, LaTeX packages needed for rendering asar reports.
Then, when you render your report for the first time, those missing
LaTeX packages needed for rendering should install automatically (e.g.,
‘tagpdf’). However, this doesn’t always happen; we don’t know why.
Try to resolve the error by installing the full TinyTeX bundle in the R console. Since this TinyTeX bundle contains every LaTeX package you could install from CTAN (TinyTeX-2), it should contain every LaTeX package needed for rendering (hence its large size):
tinytex::install_tinytex(bundle = "TinyTeX-2")
Then, render your report once more.
When rendering your report, it may hang when processing the figures file. If this occurs, it probably means that your tinytex installation isn’t working properly. This may occur even if you’ve installed the TinyTeX bundle with every LaTeX package you could install from CTAN (TinyTeX-2).
Try this: Uninstall tinytex in the R console
(tinytex::uninstall_tinytex()), then reinstall it in the
terminal (quarto install tinytex).
Notably, this command will install TinyTeX-1 bundle (the default), then install the necessary LaTeX packages needed for rendering while your report is rendering the first time. See the “DocumentMetadata” error section for more information.
find support_files/before-body.tex?
This error can occasionally occur to some users when they are working on a remote or shared drive that does not originate from their local machine. Due to constraints of Quarto, the user must render their skeleton document when the support files and child documents are found somewhere locally.
We suggest users who encounter this problem to store their files made
from asar on their local computer and push them to a GitHub
repo to store and share.
When getting to know asar, you’ll probably encounter
some errors. We highly recommend checking out our issues page and discussion board
to see if someone else has already asked (and maybe solved!) your
question.
If you cannot find an answer, feel free to report your issue or question to the issues page or discussion board. There are multiple issue templates to choose from: request to add author affiliation, bug report, feature request, and more.