Episcout2

.Rbuildignore

@@ -1,6 +1,11 @@
+^archive$
+^archive/
+^future$
+^future/
 ^codecov\.yml$
 ^cran-comments\.md$
 ^\.travis\.yml$
+^\.DS_Store$
 ^data-raw$
 ^LICENSE\.md$
 ^episcout\.Rproj$
@@ -23,4 +28,8 @@
 ^AGENTS\.MD$
 ^fishers_results\.txt$
 ^spec_driven_EDA_plan$
+^environment\.yml$
+^scripts$
+^build$
+^legacy$
 # .Rbuildignore

.github/workflows/r-cmd-check.yml

@@ -10,7 +10,7 @@
 
 on:
   push:
-    branches: [main, master]
+    branches: ["**"] #[main, master]
   pull_request:
     branches: [main, master]
 

.lintr

@@ -1,2 +1,2 @@
 linters: linters_with_defaults(line_length_linter = line_length_linter(150), object_name_linter = object_name_linter(styles = "snake_case"), assignment_linter = assignment_linter(), spaces_left_parentheses_linter = spaces_left_parentheses_linter(), object_usage_linter = object_usage_linter(), commented_code_linter = NULL, indentation_linter(indent = 2L, hanging_indent_style = "always"))
-exclusions: list("blurbs_and_old_code/*")
+exclusions: list("blurbs_and_old_code/*", "scripts/rscript_env_caller.R")

AGENTS.MD

@@ -1,7 +1,26 @@
 # AGENTS.md
 
 This file defines conventions and instructions to guide OpenAI Codex and other agents in contributing to this R package.
-It standardises formatting, documentation, testing, and pull request workflows.
+It standardises code writing, formatting, documentation, testing, and pull request workflows.
+
+It should be respected by automated agents at all times, particularly when:
+
+* Writing new functions (must include roxygen2 and tests)
+* Refactoring existing code (preserve naming and indentation)
+* Editing documentation (run `devtools::document()`)
+* Opening a PR (follow title/description/branch rules)
+* Running checks (use scripts provided above)
+* Debugging, identifying errors and making improvements
+
+Do not overcomplicate and over-engineer. Prefer the simpler solution. Make it easy for a human to review, supervise and monitor work. Do not bloat file content or create numerous files when one would suffice. e.g. use one `TODOs.md`, not a dir with `now.md`, `next.md`, `later.md`.
+
+When fixing code, identify the cause; do not simply fix the symptom.
+
+Never hide behaviour behind 'clean up' when refactoring.
+
+When writing tests, never mirror the implementation. Always test against the intended behaviour. If this is unclear, undocumented or may be wrong, always stop and report.
+
+---
 
 ## 📁 Project Structure
 
@@ -17,6 +36,76 @@ It standardises formatting, documentation, testing, and pull request workflows.
 
 ---
 
+## R Environment
+
+Use the repo-local R wrapper for all R commands:
+
+```bash
+scripts/rscript_env_caller.R -e "R.home(); .libPaths()"
+```
+
+The wrapper resolves to the project mamba environment by default:
+
+```text
+~/apps/miniforge3/envs/episcout/bin/Rscript
+```
+
+Do not use bare `Rscript` unless you have verified it resolves to the
+`episcout` mamba environment. To use a different R binary, set
+`EPISCOUT_RSCRIPT`; see `scripts/rscript_env_caller.R`.
+
+For `devtools` checks, set a real CRAN mirror inside the R expression. Do not
+leave `repos` as the placeholder `@CRAN@`, because package checks may spend a
+long time probing package repositories.
+
+```bash
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::check(manual = FALSE)"
+```
+
+## Repo Script Discovery and Naming
+
+Before adding or changing helper commands, inspect existing project entry
+points:
+
+```text
+scripts/
+Makefile
+.github/workflows/
+AGENTS.MD
+```
+
+Do not add a new helper script if an existing script already covers the task.
+If an existing helper has an unclear or misleading name, propose a rename or
+targeted cleanup instead of adding another wrapper.
+
+Script names must describe the project action, not merely mirror a system
+binary. Avoid names that are visually or semantically confusable with common
+commands, such as:
+
+```text
+rscript
+python
+R
+test
+check
+```
+
+Prefer explicit project or task names such as:
+
+```text
+scripts/rscript_env_caller.R
+scripts/check-local.sh
+scripts/check-cran.sh
+scripts/render-report.sh
+```
+
+Before adding a new script, confirm:
+
+1. No existing script already does the job.
+2. The name is unambiguous in chat, docs, logs and CI.
+3. The script follows the repo's existing shell/R conventions.
+
+
 ## Coding Conventions
 
 * Use `snake_case` for object and function names.
@@ -52,13 +141,13 @@ All new functions must include unit tests in `/tests/testthat/`.
 Run tests locally before committing:
 
 ```bash
-Rscript -e "devtools::test(reporter = 'summary')"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::test(reporter = 'summary')"
 ```
 
 Use `covr` to monitor test coverage:
 
 ```bash
-Rscript -e "covr::report()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); covr::report()"
 ```
 
 Ensure test coverage does not decrease for existing functions.
@@ -71,19 +160,19 @@ Always update documentation and verify build integrity before PRs.
 
 ```bash
 # Regenerate documentation
-Rscript -e "devtools::document()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::document()"
 
 # Build the package tarball
 R CMD build . --no-resave-data --compact-vignettes=gs+qpdf
 
 # Run CRAN-like checks
-R CMD check --no-manual --as-cran
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::check(manual = FALSE)"
 ```
 
 Optional: rebuild vignettes manually
 
 ```bash
-Rscript -e "devtools::build_vignettes()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::build_vignettes()"
 ```
 
 ---
@@ -127,10 +216,10 @@ Examples:
 Run all checks **before requesting a review**:
 
 ```bash
-Rscript -e "styler::style_pkg()"
-Rscript -e "lintr::lint_package()"
-Rscript -e "devtools::check(manual = FALSE)"
-Rscript -e "covr::report()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); styler::style_pkg()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); lintr::lint_package()"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); devtools::check(manual = FALSE)"
+scripts/rscript_env_caller.R -e "options(repos = c(CRAN = 'https://cloud.r-project.org')); covr::report()"
 ```
 
 All of the above must pass before merging.
@@ -161,16 +250,3 @@ act -j check  # if act is installed for local testing
 ```
 
 ---
-
-## Agent-Specific Instructions
-
-This AGENTS.md should be respected by OpenAI Codex or other automated agents when:
-
-* Writing new functions (must include roxygen2 and tests)
-* Refactoring existing code (preserve naming and indentation)
-* Editing documentation (run `devtools::document()`)
-* Opening a PR (follow title/description/branch rules)
-* Running checks (use scripts provided above)
-
----
-

DESCRIPTION

@@ -8,7 +8,12 @@ Authors@R:
            email = "antoniojberlanga@gmail.com")
 Author: Antonio Berlanga-Taylor [aut, cre]
 Maintainer: Antonio Berlanga-Taylor <antoniojberlanga@gmail.com>
-Description: Facilitates cleaning, exploring and visualising large-ish datasets (hundreds of thousands to millions of observations with tens to hundreds of variables). These are mostly wrapper and convenience functions to pre-process (wrangle, explore, clean, etc.) data-sets. Assumes you're happy with tidyverse and the basics of data.table. 
+Description: Facilitates cleaning, exploring and visualising large-ish
+    epidemiological datasets (hundreds of thousands to millions of
+    observations with tens to hundreds of variables). Provides helper functions
+    for preprocessing and descriptive work, plus specification-first
+    exploratory data analysis workflows for epidemiological datasets. Assumes
+    you're happy with tidyverse and the basics of data.table.
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
@@ -17,6 +22,7 @@ Imports:
     utils,
     stats,
     grDevices,
+    openssl,
     magrittr,
     rlang (>= 0.1.2),
     broom,
@@ -52,7 +58,8 @@ Suggests:
     covr,
     withr,
     roxygen2,
-    mice
+    mice,
+    targets
 Roxygen: list(markdown = TRUE)
 VignetteBuilder: knitr
-RoxygenNote: 7.3.2
+Config/roxygen2/version: 8.0.0

NAMESPACE

@@ -29,6 +29,17 @@ export(epi_clean_replace_value)
 export(epi_clean_spread_repeated)
 export(epi_clean_transpose)
 export(epi_create_dir)
+export(epi_eda_check_schema)
+export(epi_eda_create_project)
+export(epi_eda_generate_synthetic_data)
+export(epi_eda_profile_missing)
+export(epi_eda_profile_plots)
+export(epi_eda_profile_summaries)
+export(epi_eda_render_report)
+export(epi_eda_run)
+export(epi_eda_spec)
+export(epi_eda_validate_spec)
+export(epi_grob_to_excel)
 export(epi_head_and_tail)
 export(epi_list_head)
 export(epi_list_tail)
@@ -47,9 +58,10 @@ export(epi_plot_parallel)
 export(epi_plot_save_parallel)
 export(epi_plot_theme_1)
 export(epi_plot_theme_imss)
-export(epi_plots_to_grid)
 export(epi_plot_volcano)
+export(epi_plots_to_grid)
 export(epi_read)
+export(epi_sec_pseudonym)
 export(epi_stats_2x2_all)
 export(epi_stats_2x2_cols)
 export(epi_stats_2x2_test)
@@ -83,7 +95,6 @@ export(epi_utils_session)
 export(epi_write)
 export(epi_write_df)
 export(expr)
-export(epi_grob_to_excel)
 export(palette_IMSS)
 export(palette_IMSS_accessible)
 export(quo)
@@ -105,8 +116,11 @@ importFrom(e1071,kurtosis)
 importFrom(e1071,skewness)
 importFrom(foreach,`%dopar%`)
 importFrom(grDevices,boxplot.stats)
+importFrom(graphics,abline)
+importFrom(graphics,plot)
 importFrom(magrittr,"%>%")
 importFrom(magrittr,`%>%`)
+importFrom(openssl,rand_bytes)
 importFrom(rlang,":=")
 importFrom(rlang,.data)
 importFrom(rlang,enexpr)
@@ -141,5 +155,3 @@ importFrom(utils,capture.output)
 importFrom(utils,head)
 importFrom(utils,sessionInfo)
 importFrom(utils,tail)
-importFrom(graphics,abline)
-importFrom(graphics,plot)

NEWS.md

@@ -0,0 +1,42 @@
+# episcout News
+
+## Development version
+
+- Added `epi_sec_pseudonym()` to create secure participant pseudonymisation
+  bridge tables using cryptographic random tokens.
+- Added a specification-first EDA workflow driven by data dictionaries:
+  `epi_eda_spec()`, `epi_eda_check_schema()`, `epi_eda_profile_missing()`,
+  `epi_eda_profile_summaries()`, `epi_eda_profile_plots()`,
+  `epi_eda_generate_synthetic_data()`, `epi_eda_run()`, and
+  `epi_eda_render_report()`.
+- Added `epi_eda_create_project()` and a reusable project scaffold under
+  `inst/project-template/`.
+- Added fixture-backed tests for the EDA workflow using a pinned
+  `blood_storage` fixture.
+- Added an HTML EDA report template.
+- EDA missingness and summaries now apply specification `missing_codes`.
+- Categorical EDA summaries now include `p_observed` alongside the existing
+  total-row denominator `p`.
+- Documented current MVP limits: basic summaries and plots, synthetic data for
+  pipeline preparation only, and no Arrow, DuckDB or data.table EDA backends yet.
+- Cleaned up Rd documentation and CRAN-check issues on the development branch.
+
+## 0.1.4
+
+- Added `epi_plot_theme_imss` and colour palette helpers.
+- Added `epi_plot_add_var_labels`.
+- Reworked `epi_stats_*` summary functions.
+
+## 0.1.3
+
+- Improved coverage tests.
+- Added helper wrappers.
+- Improved documentation.
+
+## 0.1.2
+
+- Minor bug fixes and internal improvements.
+
+## 0.1.1
+
+- First release.