Package 'froggeR'

Create a Custom 'Quarto' Project

Description

This function creates a new 'Quarto' project directory with additional froggeR features. It first calls quarto::quarto_create_project() to set up the basic structure, then enhances it with froggeR-specific files and settings.

Usage

quarto_project(name, path = here::here(), custom_yaml = TRUE)

Arguments

name	Character string. The name of the 'Quarto' project directory and initial .qmd file.
path	Character string. Path to the project directory.
custom_yaml	Logical. If TRUE (default), uses a custom YAML header in the initial .qmd file, populated with values from '_variables.yml'. If FALSE, uses a standard YAML header.

Details

This function creates a 'Quarto' project with the following enhancements:

• _variables.yml: Stores reusable YAML variables (if custom_yaml = TRUE)

• .gitignore: Enhanced settings for R projects

• README.md: Template README file

• dated_progress_notes.md: For project progress tracking

• custom.scss: Custom 'Quarto' styling (if custom_yaml = TRUE)

• .Rproj: RStudio project file

If froggeR settings don't exist, it will prompt to create them.

Value

Invisibly returns the path to the created project directory.

See Also

write_quarto, settings

Examples

if (quarto::quarto_version() >= "1.4") {
  # Create a temporary directory for testing
  tmp_dir <- tempdir()

  # Create the Quarto project with custom YAML & associated files
  quarto_project("frogs", path = tempdir(), custom_yaml = TRUE)

  # Confirms files were created (optional, for user confirmation)
  file.exists(file.path(tmp_dir, "frogs.rproj"))  # Rproj file
  file.exists(file.path(tmp_dir, "frog.qmd"))     # Quarto doc
  file.exists(file.path(tmp_dir, "_quarto.yml"))  # project YAML file

  # Create a new Quarto project with standard Quarto YAML
  # quarto_project('frogs_standard', path = tempdir(), custom_yaml = FALSE)

  # Clean up: Remove the created temp directory and all files
  unlink(list.files(tempdir(), full.names = TRUE), recursive = TRUE)
}

---

Manage 'froggeR' Settings

Description

This function provides useful instructions and information regarding 'froggeR' settings.

Usage

settings()

Details

This function can only run in an interactive environment. Choose to: - Check for the existence of project- and global-level configuration files - Display current project-level settings - Feedback for updating settings - Instructions how to reuse settings across multiple 'froggeR' Quarto projects.

Value

No return value; called for side-effects.

Examples

# Only run in an interactive environment
if (interactive()) froggeR::settings()

---

Create an enhanced .gitignore file

Description

This function creates a .gitignore file with enhanced security measures designed to help prevent accidental data leaks. The template includes comprehensive rules for common data file types and sensitive information.

Usage

write_ignore(path = here::here(), .initialize_proj = FALSE)

Arguments

path	Character string. Path to the project directory.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

If a .gitignore file already exists, the user will be prompted before any overwriting occurs. The template provides substantial security enhancements over basic .gitignore files.

WARNING: Always consult your organization's data security team before using git with any sensitive or protected health information (PHI). This template helps prevent accidental data exposure but should not be considered a complete security solution.

Value

A .gitignore file with enhanced security rules. The file includes:
* R data files (.RData, .rda, .rds)
* Common data formats (CSV, Excel, text)
* System and temporary files
* IDE-specific files

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the .gitignore file
write_ignore(path = tmp_dir)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, ".gitignore"))

# Clean up: Remove the created file
unlink(file.path(tmp_dir, ".gitignore"))

---

Create a project README file

Description

This function streamlines project documentation by creating a dated progress notes file.

Usage

write_notes(path = here::here(), .initialize_proj = FALSE)

Arguments

path	Character string. Path to the project directory.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

The dated_progress_notes.md file is initialized with the current date and is designed to help track project milestones chronologically. If the progress notes file already exists, the function will stop and warn the user.

Value

CA chronological project progress notes tracker.

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the progress notes file
write_notes(path = tmp_dir)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, "dated_progress_notes.md"))

# Clean up: Remove the created file
unlink(file.path(tmp_dir, "dated_progress_notes.md"))

---

Create a New 'Quarto' Document

Description

This function creates a new 'Quarto' document (.qmd file) with either a custom or standard YAML header. When using a custom header, it integrates with 'froggeR::settings()' for reusable metadata across documents.

Usage

write_quarto(
  filename = "frogs",
  path = here::here(),
  custom_yaml = TRUE,
  .initialize_proj = FALSE
)

Arguments

filename	Character string. The name of the file without the '.qmd' extension. Only letters, numbers, hyphens, and underscores are allowed.
path	Character string. Path to the project directory.
custom_yaml	Logical. If TRUE (default), creates a 'Quarto' document with a custom YAML header using values from '_variables.yml'. If FALSE, creates a standard 'Quarto' document.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

When 'custom_yaml = TRUE', the function will check if '_variables.yml' exists. This file is needed to supply Quarto document metadata in the 'path' project. The user will be prompted with help if they don't already exist, and a Quarto document with the default template will be supplied instead.

Value

Invisibly returns NULL after creating the 'Quarto' document.

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the Quarto & associated files for a custom YAML with reusable metadata
write_quarto(path = tempdir(), filename = "frog_analysis")

# Write the Quarto file with a template requiring more DIY
write_quarto(path = tempdir(), filename = "frog_analysis_basic", custom_yaml = FALSE)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, "frog_analysis.qmd"))
file.exists(file.path(tmp_dir, "frog_analysis_basic.qmd"))

# Clean up: Remove the created file
unlink(list.files(tempdir(), full.names = TRUE), recursive = TRUE)

---

Create a project README file

Description

This function streamlines project documentation by a README.md file.

Usage

write_readme(path = here::here(), .initialize_proj = FALSE)

Arguments

path	Character string. Path to the project directory.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

The README.md template includes structured sections for:

• Project description (study name, principal investigator, author)

• Project setup steps for reproducibility

• File and directory descriptions

• Miscellaneous project notes

Value

Creates a comprehensive README template for project documentation.

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the README file
write_readme(path = tmp_dir)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, "README.md"))

# Clean up: Remove the created file
unlink(file.path(tmp_dir, "README.md"))

---

Create a 'Quarto' SCSS file

Description

This function creates the .scss file so that any 'Quarto' project can be easily customized with SCSS styling variables, mixins, and rules.

Usage

write_scss(path = here::here(), .initialize_proj = FALSE)

Arguments

path	Character string. Path to the project directory.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

The function includes a robust YAML handling mechanism that safely adds new SCSS file.

See vignette("customizing-quarto", package = "froggeR") vignette for more help.

Value

A SCSS file to customize 'Quarto' styling.

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the SCSS file
write_scss(path = tmp_dir)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, "custom.scss"))

# Clean up: Remove the created file
unlink(file.path(tmp_dir, "custom.scss"))

---

Write Variables YAML for 'Quarto' Projects

Description

This function creates or updates the '_variables.yml' file in a Quarto project directory using froggeR settings, if they exist in the config path.

Usage

write_variables(path = here::here(), .initialize_proj = FALSE)

Arguments

path	Character string. Path to the project directory.
.initialize_proj	Logical. TRUE only if starting a froggeR::quarto_project().

Details

The function will attempt to use the current froggeR settings from the config path. If no global configurations exist, a template '_variables.yml' will be created.

Value

Invisibly returns 'NULL' after creating or updating the '_variables.yml' file.

Examples

# Create a temporary directory for testing
tmp_dir <- tempdir()

# Write the _variables.yml file
write_ignore(path = tmp_dir)

# Confirm the file was created (optional, for user confirmation)
file.exists(file.path(tmp_dir, "_variables.yml"))

# Clean up: Remove the created file
unlink(file.path(tmp_dir, "_variables.yml"))

---