From a823d39e2acc53418178256c7884863733865492 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:25:03 +0000 Subject: [PATCH 01/11] Fix formatting in README for R code example Fix formatting and removed the python code Signed-off-by: Jessica Ikechukwu --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 301c198..ed22073 100644 --- a/README.md +++ b/README.md @@ -40,8 +40,8 @@ If you are having problems installing the package, please see the more detailed Before using any function from the package, an acro object should be initialised using the following R code: ``` r ->>> library("acro") ->>> acro_init(suppress = TRUE) +library("acro") +acro_init(suppress = TRUE) ``` ### Try Online with MyBinder From 2a7674434ef7fc2cf8e55120a54899ac6c07c8f0 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:26:50 +0000 Subject: [PATCH 02/11] Revise INSTALL.md for clarity and conciseness Updated installation instructions for acro-r, including prerequisites and step-by-step guidance for setting up Python and R environments. Signed-off-by: Jessica Ikechukwu --- inst/INSTALL.md | 149 ++++++++---------------------------------------- 1 file changed, 24 insertions(+), 125 deletions(-) diff --git a/inst/INSTALL.md b/inst/INSTALL.md index dbd2650..d984b0a 100644 --- a/inst/INSTALL.md +++ b/inst/INSTALL.md @@ -1,143 +1,42 @@ # Installation Guides -This document is intended to provide help installing and running acro-r in different settings. +This document is intended to provide help installing and running acro-r. -Keeping this comprehensive will require input from the community. +## Prerequisites -So please email sacro.contact@uwe.ac.uk, or [raise an issue on the GitHub repository](https://github.com/AI-SDC/ACRO-R/issues/new/choose) if: - - you have a setting that is not covered, or - - the steps outlined below do not work for you, +- **Python 3.10+**: You must have Python installed on your system. +- **R**: You need a working installation of R. -**Please note**: most of the scenarios below assume that -- you have a working version of Python 3 (version 3.9 or higher) on your system -- you are able to access a terminal or command prompt to write and execute some commands. +## Installation ---- +### Step 1: Install the R package -## Step 1 create a python virtual environment and install the base python package *acro* -**In every case** we recommend that you create what is called a 'python virtual environment' called **r-acro**. -Virtual environments (*venv's*) are recommended best practice. -This is because they isolate the impact of any changes you make in one venv - such as adding or updating a package- from the rest of your system. +Install the **acro** package from CRAN: -There are many tutorials available on the web if you get stuck. -We do not endorse any particular site, but here are some examples: -- [an overview with examples for windows/linux/mac](https://python.land/virtual-environments/virtualenv) -- [another that also contains instructions for VSCode and Pycharm](https://realpython.com/python-virtual-environments-a-primer/) - -**For individual users** we suggest that you do this in your home directory where you should have write permission. - -**To install site-wide** we assume you have access rights and know where your organisation's preferred locations are (for example, this might be ```/usr/local``` on a linux system). - -### Make a dedicated virtual environment -You can make a new virtual environment via: -- the Anaconda GUI interface to the conda system -- command line access - by opening a terminal or command prompt and entering the command: - ```sh - conda create --n r-acro - ``` -if you have a version of conda installed or - ```sh -python -m venv ./r-acro -``` -to use the native python *venv* package. - -### Change to that virtual environment and install acro -Anaconda comes with its own GUI to makes this process easy. - -**On any system** using *conda* from the command line : -```sh -conda activate r-acro -conda install conda-forge::acro - -#assuming this completes successfully you can now exit -conda deactivate r-acro -``` - -**On Windows**from the command line with python's *pip* package manager: -```sh -# In cmd.exe -r-acro\Scripts\activate.bat -# In PowerShell -r-acro\Scripts\Activate.ps1 -``` -followed by -```sh -python -m pip install acro -#assuming this completes successfully you can now exit the virtual environment -deactivate -``` - -**On linux/mac** using conda: - -```sh -source r-acro/bin/activate -#you should see the your command prompt change to show (r-acro) -python -m pip install acro -#assuming this completes successfully you can now exit the virtual environment -deactivate -``` ---- - -## Step 2 Install the R packages *reticulate* and *acro* - -The *reticulate* package is the industry-standard method for supporting communications between R and Python. -It provides the `plumbing` between the R `front-end' - -These commands should work whether you are -- working on a machine outside the TRE: in which case packages should install from a mirror of the CRAN service -- working on a machine inside a TRE: in which case the administrator should have set up a local mirror of approved packages from CRAN - -**For individual users** without permission to make site-wide or machine-wide changes -Open your preferred R interface - for example, RStudio, and in a R window type -```R -install.packages*("reticulate") +```r install.packages("acro") ``` -**For administrators wishing to install for all users site-wide** the commands are the same but you will need to run them in *sudo* mode. - ---- - -## Step 3: Telling R and reticulate to use the new python virtual environment -The final step of the process is to tell the R package reticulate which version of python to use. - -What we need to do is to set the value of a global variable ```RETICULATE_PYTHON``` -The [R documentation for doing this](https://rstudio.github.io/reticulate/articles/versions.html) is a little inconsistent here, but the following options all seem to work. +### Step 2: Initialize ACRO -### Option 1- For individuals using RStudio -If you follow the menu items from ```Tools->Project Options ->Python``` or ```Tools->Global Options->Python``` you can tell it to use the version of python from the virtual environment you create in step 1, either for a specific R project or for all your sessions as shown below +The `acro` package interfaces with the Python `acro` library. The package provides a helper function to set up the necessary Python environment and dependencies automatically. -![This is what it looks like: step0](./images/settingpython-rstudio-step0.png) +Run the following in your R console: -![This is what it looks like: step1](./images/settingpython-rstudio-step1.png) - -![This is what it looks like: step2](./images/settingpython-rstudio-step2.png) - -![This is what it looks like: step3](./images/settingpython-rstudio-step3.png) - -### Option 2 - Adding code to an individual project file - you add add one of the following lines at the start of your file - ```R - #Either - use_python("~/r-acro/bin/python") - #or - use_virtualenv("~/r-acro") - #or - use_condaenv("r-acro") - #finally followed by - library(reticulate) - library("acro)" - ``` - -### Option 3 - Editing your personal R preferences -In your home directory create (or edit) the file ```.Rprofile``` file, adding the lines - -```R -Sys.setenv(RETICULATE_PYTHON=file.path(Sys.getenv("USERPROFILE"),"r-acro/bin/python")) -Sys.setenv(RETICULATE_PYTHON_ENV=file.path(Sys.getenv("USERPROFILE"),"r-acro")) +```r +library("acro") +acro_init() ``` +This command will: +1. Check for a valid Python installation. +2. Create a virtual environment named `r-acro`. +3. Install the required Python `acro` package into this environment. + +Once initialized, you are ready to use ACRO-R! +## Troubleshooting -### Option 4- Making site-wide changes - You can also edit the [site-wide Rprofile]() file to add these global environment variables, using replacing *~/r-acro* with the path to wherever you created the dedicated virtual environment. +If you encounter issues during `acro_init()`: +- Ensure Python 3.10+ is installed and added to your system PATH. +- If you are on a restricted network, you may need to configure proxy settings for Python package installation. From f4bab237b04303281d528cf09c80279a81a6887b Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:28:02 +0000 Subject: [PATCH 03/11] Delete inst/installation.md Signed-off-by: Jessica Ikechukwu --- inst/installation.md | 50 -------------------------------------------- 1 file changed, 50 deletions(-) delete mode 100644 inst/installation.md diff --git a/inst/installation.md b/inst/installation.md deleted file mode 100644 index 901fd23..0000000 --- a/inst/installation.md +++ /dev/null @@ -1,50 +0,0 @@ -# Installation Guide - -## Install from CRAN - -Install the **acro** package from CRAN as follows: - -```r -install.packages("acro") -``` - -## Development Version - -To install the development version from GitHub: - -```r -# Install devtools if you haven't already -install.packages("devtools") - -# Install ACRO-R from GitHub -devtools::install_github("AI-SDC/ACRO-R") -``` - -## Prerequisites - -ACRO-R requires: -- R version 4.0 or higher -- Python 3.10+ or higher with the ACRO Python package installed - -## Python ACRO Installation - -The R package interfaces with the Python ACRO library. Install it using: - -```bash -pip install acro -``` - -## Troubleshooting - -If you are having problems installing the package, please see the more detailed [installation guide](INSTALL.md) or check the [GitHub issues](https://github.com/AI-SDC/ACRO-R/issues). - -## Verification - -To verify your installation works correctly: - -```r -library("acro") -acro_init(suppress = TRUE) -``` - -If this runs without errors, your installation is successful! From ef84672643f445a826281f517866c284064987b2 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:28:57 +0000 Subject: [PATCH 04/11] Delete inst/examples.md Signed-off-by: Jessica Ikechukwu --- inst/examples.md | 40 ---------------------------------------- 1 file changed, 40 deletions(-) delete mode 100644 inst/examples.md diff --git a/inst/examples.md b/inst/examples.md deleted file mode 100644 index c6168ef..0000000 --- a/inst/examples.md +++ /dev/null @@ -1,40 +0,0 @@ -# Examples - -## Interactive Notebook - -For comprehensive examples and tutorials, see our interactive R notebook: - -[Example Notebook](articles/example-notebook.html) - -## Quick Start Examples - -### Basic Usage - -```r -library("acro") - -# Initialize ACRO -acro_init(suppress = TRUE) - -# Your analysis code here -# ACRO will automatically check outputs for disclosure risks -``` - -### Creating Safe Tables - -```r -# Example of creating a cross-tabulation with ACRO -result <- acro_crosstab(data$variable1, data$variable2) - -# ACRO automatically applies disclosure control -print(result) -``` - -### Finalizing Your Session - -```r -# When you're done with your analysis -acro_finalise() -``` - -For more detailed examples and use cases, please refer to the [Example Notebook](articles/example-notebook.html). From ff329c352b9225748f927aa93dda8b1d3126f29a Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:29:26 +0000 Subject: [PATCH 05/11] Delete inst/welcome.md Signed-off-by: Jessica Ikechukwu --- inst/welcome.md | 47 ----------------------------------------------- 1 file changed, 47 deletions(-) delete mode 100644 inst/welcome.md diff --git a/inst/welcome.md b/inst/welcome.md deleted file mode 100644 index d3d2e78..0000000 --- a/inst/welcome.md +++ /dev/null @@ -1,47 +0,0 @@ -# Welcome to ACRO-R - -## ACRO: Tools for the Semi-Automatic Checking of Research Outputs - -[![IEEE Xplore](https://img.shields.io/badge/IEEE%20Xplore-10.1109/TP.2025.3566052-blue)](https://doi.org/10.1109/TP.2025.3566052) -[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) -[![CRAN](https://www.r-pkg.org/badges/version/acro)](https://CRAN.R-project.org/package=acro) -[![check](https://github.com/AI-SDC/ACRO-R/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/AI-SDC/ACRO-R/actions?query=workflow%3AR-CMD-check) -[![codecov](https://codecov.io/gh/AI-SDC/ACRO-R/graph/badge.svg?token=VxbjBHzeXU)](https://app.codecov.io/gh/AI-SDC/ACRO-R) - -This repository maintains the ACRO R package, which is an interface to the Python [ACRO](https://github.com/AI-SDC/ACRO) package. - -ACRO is a free and open source tool that supports the semi-automated checking of research outputs (SACRO) for privacy disclosure within secure data environments. SACRO is a framework that applies best-practice principles-based [statistical disclosure control](https://en.wikipedia.org/wiki/Statistical_disclosure_control) (SDC) techniques on-the-fly as researchers conduct their analysis. SACRO is designed to assist human checkers rather than seeking to replace them as with current automated rules-based approaches. - -The ACRO package is a lightweight Python tool that sits over well-known analysis tools that produce outputs such as tables, plots, and statistical models. This package adds functionality to: - -* automatically identify potentially disclosive outputs against a range of commonly used disclosure tests; -* apply optional disclosure mitigation strategies as requested; -* report reasons for applying SDC; -* and produce simple summary documents trusted research environment staff can use to streamline their workflow and maintain auditable records. - -This creates an explicit change in the dynamics so that SDC is something done with researchers rather than to them, and enables more efficient communication with checkers. - -A graphical user interface ([SACRO-Viewer](https://github.com/AI-SDC/SACRO-Viewer)) supports human checkers by displaying the requested output and results of the checks in an immediately accessible format, highlighting identified issues, potential mitigation options, and tracking decisions made. - -Additional programming languages such as this R package are supported by providing front-end packages that interface with the core ACRO Python back-end. - -## Usage - -Before using any function from the package, an acro object should be initialised using the following R code: - -```r -library("acro") -acro_init(suppress = TRUE) -``` - -## Documentation - -The github-pages contains pre-built [documentation](https://ai-sdc.github.io/ACRO-R/). - -Additionally, see our [paper describing the SACRO framework](https://doi.org/10.1109/TP.2025.3566052) to learn about its principles-based SDC methodology and usage. - -## Acknowledgement - -This work was funded by UK Research and Innovation under Grant Numbers MC_PC_21033 and MC_PC_23006 as part of Phase 1 of the Data and Analytics Research Environments UK ([DARE UK](https://dareuk.org.uk/)) programme, delivered in partnership with Health Data Research UK (HDR UK) and Administrative Data Research UK (ADR UK). The specific projects were Semi-Automatic checking of Research Outputs (SACRO; MC_PC_23006) and Guidelines and Resources for AI Model Access from Trusted Research environments (GRAIMATTER; MC_PC_21033). This project has also been supported by MRC and EPSRC [grant number MR/S010351/1]. - -![UK Research and Innovation](man/figures/UK_Research_and_Innovation_logo.svg){width="20%"} ![Health Data Research UK](man/figures/health-data-research-uk-hdr-uk-logo-vector.png){width="20%"} ![Logo](man/figures/logo_print.png){width="20%"} From bfc9c27ed21dd510ccbc3605b83465bfbb4e65f4 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:29:37 +0000 Subject: [PATCH 06/11] Delete inst/supports.md Signed-off-by: Jessica Ikechukwu --- inst/supports.md | 123 ----------------------------------------------- 1 file changed, 123 deletions(-) delete mode 100644 inst/supports.md diff --git a/inst/supports.md b/inst/supports.md deleted file mode 100644 index b18267d..0000000 --- a/inst/supports.md +++ /dev/null @@ -1,123 +0,0 @@ -# What ACRO-R Supports - - -This page provides a comprehensive overview of ACRO’s capabilities for researchers, developers, and non-technical stakeholders. ACRO supports a wide range of statistical analysis functions with automated disclosure control. - -## Supported Data Analysis Functions - -### Table Creation & Cross-tabulation - -**For Researchers:** Create frequency tables and cross-tabulations with automatic cell suppression for small counts. - -**What ACRO Supports:** - -* **crosstab()** - Cross-tabulation of two or more variables with frequency counting -* **pivot_table()** - Spreadsheet-style pivot tables with aggregation functions -* **table()** - Simple frequency tables for categorical data (R interface only) - -**Technical Details:** - ACRO suppresses, and reports the reason why, the value of an aggregation statistic (mean, median, variance, etc.) for any cell is deemed to be sensitive - The current version of ACRO supports the three most common tests for sensitivity: ensuring the number of contributors is above a frequency threshold, and testing for dominance via N-K rules - **N-K Rule** : A dominance test where if the top N contributors account for more than K% of the total, the cell is considered disclosive - **Frequency Threshold** : Cells with fewer than a specified number of contributors are suppressed - All thresholds are configurable via YAML configuration files - For detailed methodology, see our [research paper](https://doi.org/10.1109/TP.2025.3566052) - Automatic flagging of negative or missing values for human review - -**Example Use Cases:** - Survey response analysis by demographics - Clinical trial outcome tables - Market research cross-tabulations - Educational assessment reporting - -### Statistical Modeling - -**For Researchers:** Run regression analyses with automated checks on model outputs and residual degrees of freedom. - -**What ACRO Supports:** - -* **ols()** - Ordinary Least Squares linear regression -* **logit()** - Logistic regression for binary outcomes -* **probit()** - Probit regression for binary outcomes - -**Technical Details:** - For regressions such as linear, probit, and logit, the tests verify that the number of residual degrees of freedom exceeds a threshold - Within the ACRO Python package, the functionality of the ‘ACRO’ class is split into a number of separate classes for maintainability and extensibility. A ‘Tables’ class contains the code necessary to perform disclosure checks on tabular data, such as crosstab. A separate ‘Regression’ class contains the code for checking regressions such as logit and probit - -**Example Use Cases:** - Economic modeling and policy analysis - Medical research and clinical studies - Social science research - Business analytics and forecasting - -## Programming Language Support - -### Python (Primary) - -**For Developers:** The ACRO package is a lightweight Python tool that sits over well-known analysis tools that produce outputs such as tables, plots, and statistical models - -**Supported Libraries:** - **Pandas** - For data manipulation and table creation - **Statsmodels** - For statistical modeling and regression analysis - **NumPy** - For numerical computations - -**Python Version Support:** - Python 3.10, 3.11, 3.12, 3.13 - -### R Language - -**For R Users:** Additional programming languages such as this R package are supported by providing front-end packages that interface with the core ACRO Python back-end - -**Integration Features:** - Native R syntax and workflows - R Markdown and Shiny application support - Tidyverse compatibility - CRAN package availability - -**Getting Started in R:** ``r`` ``library("acro")`` ``acro_init(suppress`` ``=`` ``TRUE)`` `` - -### Stata Integration - -**For Stata Users:** ACRO is designed to let you use familiar commands in R, Stata and Python - -**Features:** - Drop-in replacement for standard Stata commands - Familiar Stata syntax and workflows - Integration with existing Stata scripts - -## Disclosure Control Features - -### Automated Sensitivity Testing - -**What ACRO Checks:** - -**For Tables:** - Minimum cell counts (frequency thresholds) - Dominance rules (N-K rules for concentration) - Presence of negative or missing values - -**For Statistical Models:** - Residual degrees of freedom thresholds - Model fit diagnostics - Parameter significance testing - -**For Non-Technical Users:** ACRO automatically identifies when research outputs might reveal sensitive information about individuals or organizations, applying industry-standard privacy protection rules without requiring manual review of every result. - -### Output Management - -**What ACRO Provides:** - -* **Suppression Masks** - Clear indication of which results are hidden and why -* **Summary Reports** - Detailed explanation of all disclosure checks performed -* **Audit Trails** - Complete record of all analysis steps and decisions -* **Exception Handling** - Process for requesting release of flagged outputs - -**Workflow Integration:** The finalise function will: Check that each output with “fail” or “review” status has an exception, if not you will be asked to enter one. Write the outputs to a directory. This directory contains everything that the output checkers need to make a decision - -## Supported Environments - -### Research Environments - -**Where ACRO Works:** - Trusted Research Environments (TREs) - Data safe havens - Secure data centers - Academic research computing facilities - Government statistical offices - Healthcare research environments - -**Installation:** See [Installation](https://jessuwe.github.io/ACRO/installation.html) for complete installation instructions and system requirements. - -## Integration Capabilities - -### Analysis Workflows - -**For Research Teams:** ACRO integrates seamlessly into existing data analysis workflows, requiring minimal changes to current practices while adding comprehensive privacy protection. - -**Supported Workflows:** - Jupyter notebook analysis - R Markdown documents - Stata do-files and scripts - Batch processing and automation - Interactive analysis sessions - -**Data Sources:** - CSV and Excel files - Database connections - Survey data platforms - Administrative datasets - Clinical trial databases - -### Output Formats - -**What ACRO Produces:** - Standard CSV files for tables - JSON metadata files for automation - Excel workbooks for human reviewers - -**Review Process Support:** Compatible with SACRO-Viewer for interactive output review by data controllers and compliance officers. - -## Technical Architecture - -**For System Administrators:** - -**Core Technology:** Lightweight translation scripts intercept your commands and pass them through to a python ‘engine’, based on industry-standard packages that run your commands and perform statistical disclosure checks on them - -**System Requirements:** - Python 3.10+ runtime environment - Standard scientific computing libraries (pandas, numpy, statsmodels) - Minimal computational overhead - No external network dependencies during analysis - -**Security Features:** - Local processing only (no cloud dependencies) - Audit logging and tracking - Configurable disclosure thresholds - Role-based access controls (through integration with TRE systems) - -**Documentation and Support:** Standard Python coding and naming practices have been used throughout. GitHub continuous integration (CI) runners automatically generate and publish API documentation using the Python docstrings written in numpydoc format - -## What ACRO Does NOT Support - -**Current Limitations:** - Complex visualizations and plots (coming in future versions) - Time series analysis (specialized disclosure rules needed) - Machine learning models (use SACRO-ML for AI/ML workflows) - Real-time data streams - Distributed computing frameworks - -**Alternative Solutions:** - **SACRO-ML** - For machine learning and AI model disclosure control - **SACRO-Viewer** - For interactive output review and approval - **Traditional SDC tools** - For specialized use cases not covered by ACRO From fdc1ebdc0283af8b5a4b6113c3c3bf3583d4c693 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:30:29 +0000 Subject: [PATCH 07/11] Update links in _pkgdown.yml to point to articles Signed-off-by: Jessica Ikechukwu --- _pkgdown.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_pkgdown.yml b/_pkgdown.yml index b74690f..4f4b5ac 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -14,13 +14,13 @@ navbar: - text: "Reference" href: reference/index.html - text: "Welcome to ACRO-R" - href: welcome.html + href: articles/welcome.html - text: "What ACRO-R Supports" - href: supports.html + href: articles/supports.html - text: "Installation" - href: installation.html + href: articles/installation.html - text: "Examples" - href: examples.html + href: articles/examples.html right: - icon: fab-github href: https://github.com/AI-SDC/ACRO-R From 5673e8ee92d1b0c2fe40f7ca821765b9d0aa1af6 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:32:45 +0000 Subject: [PATCH 08/11] Create examples.Rmd Signed-off-by: Jessica Ikechukwu --- vignettes/examples.Rmd | 44 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 vignettes/examples.Rmd diff --git a/vignettes/examples.Rmd b/vignettes/examples.Rmd new file mode 100644 index 0000000..c69e3e3 --- /dev/null +++ b/vignettes/examples.Rmd @@ -0,0 +1,44 @@ +--- +title: "Examples" +--- + +# Examples + +## Interactive Notebook + +For comprehensive examples and tutorials, see our interactive R notebook: + +[Example Notebook](example-notebook.html) + +## Quick Start Examples + +### Basic Usage + +```r +library("acro") + +# Initialize ACRO +acro_init(suppress = TRUE) + +# Your analysis code here +# ACRO will automatically check outputs for disclosure risks +``` + +### Creating Safe Tables + +```r +# Example of creating a cross-tabulation with ACRO +result <- acro_crosstab(data$variable1, data$variable2) + +# ACRO automatically applies disclosure control +print(result) +``` + +### Finalizing Your Session + +```r +# When you're done with your analysis +acro_finalise() +``` + +For more detailed examples and use cases, please refer to the [Example Notebook](example-notebook.html). From 6565ff7b7bd5adc17c53e8b4f06df508a06a2138 Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:33:17 +0000 Subject: [PATCH 09/11] Add installation guide for acro package Added a comprehensive installation guide for the acro package, including instructions for CRAN and GitHub installation, prerequisites, initialization, troubleshooting, and verification steps. Signed-off-by: Jessica Ikechukwu --- vignettes/installation.Rmd | 57 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 vignettes/installation.Rmd diff --git a/vignettes/installation.Rmd b/vignettes/installation.Rmd new file mode 100644 index 0000000..2382964 --- /dev/null +++ b/vignettes/installation.Rmd @@ -0,0 +1,57 @@ +--- +title: "Installation Guide" +--- + +# Installation Guide + +## Install from CRAN + +Install the **acro** package from CRAN as follows: + +```r +install.packages("acro") +``` + +## Development Version + +To install the development version from GitHub: + +```r +# Install devtools if you haven't already +install.packages("devtools") + +# Install ACRO-R from GitHub +devtools::install_github("AI-SDC/ACRO-R") +``` + +## Prerequisites + +ACRO-R requires: +- R version 4.0 or higher +- Python 3.10+ or higher + +## Initialization + +The package interfaces with the Python ACRO library. Use `acro_init()` to automatically handle the Python environment setup: + +```r +library("acro") +acro_init(suppress = TRUE) +``` + +This will create a virtual environment and install the required Python packages if they are missing. + +## Troubleshooting + +If you are having problems installing the package, please see the simplified steps above or check the [GitHub issues](https://github.com/AI-SDC/ACRO-R/issues). + +## Verification + +To verify your installation works correctly: + +```r +library("acro") +acro_init(suppress = TRUE) +``` + +If this runs without errors, your installation is successful! From 23da7869c449b1db7eb9b13f239f4a80acf4b29f Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:33:37 +0000 Subject: [PATCH 10/11] Create supports.Rmd Signed-off-by: Jessica Ikechukwu --- vignettes/supports.Rmd | 100 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 vignettes/supports.Rmd diff --git a/vignettes/supports.Rmd b/vignettes/supports.Rmd new file mode 100644 index 0000000..5a2e0fb --- /dev/null +++ b/vignettes/supports.Rmd @@ -0,0 +1,100 @@ +--- +title: "What ACRO-R Supports" +--- + +# What ACRO-R Supports + +This page provides a comprehensive overview of ACRO’s capabilities. ACRO supports a wide range of statistical analysis functions with automated disclosure control. + +## Supported Data Analysis Functions + +### Table Creation & Cross-tabulation + +**For Researchers:** Create frequency tables and cross-tabulations with automatic cell suppression for small counts. + +**What ACRO Supports:** + +* **`crosstab()`** - Cross-tabulation of two or more variables with frequency counting +* **`pivot_table()`** - Spreadsheet-style pivot tables with aggregation functions +* **`table()`** - Simple frequency tables for categorical data (R interface only) + +**Technical Details:** + +- ACRO suppresses, and reports the reason why, the value of an aggregation statistic (mean, median, variance, etc.) for any cell is deemed to be sensitive. +- The current version of ACRO supports the three most common tests for sensitivity: ensuring the number of contributors is above a frequency threshold, and testing for dominance via N-K rules. + - **N-K Rule**: A dominance test where if the top N contributors account for more than K% of the total, the cell is considered disclosive. + - **Frequency Threshold**: Cells with fewer than a specified number of contributors are suppressed. +- All thresholds are configurable via YAML configuration files. +- For detailed methodology, see our [research paper](https://doi.org/10.1109/TP.2025.3566052). +- Automatic flagging of negative or missing values for human review. + +**Example Use Cases:** +- Survey response analysis by demographics +- Clinical trial outcome tables +- Market research cross-tabulations +- Educational assessment reporting + +### Statistical Modeling + +**For Researchers:** Run regression analyses with automated checks on model outputs and residual degrees of freedom. + +**What ACRO Supports:** + +* **`ols()`** - Ordinary Least Squares linear regression +* **`logit()`** - Logistic regression for binary outcomes +* **`probit()`** - Probit regression for binary outcomes + +**Technical Details:** +- For regressions such as linear, probit, and logit, the tests verify that the number of residual degrees of freedom exceeds a threshold. +- The functionality acts as a wrapper around standard statistical packages. + +**Example Use Cases:** +- Economic modeling and policy analysis +- Medical research and clinical studies +- Social science research +- Business analytics and forecasting + +## Disclosure Control Features + +### Automated Sensitivity Testing + +**What ACRO Checks:** + +**For Tables:** +- Minimum cell counts (frequency thresholds) +- Dominance rules (N-K rules for concentration) +- Presence of negative or missing values + +**For Statistical Models:** +- Residual degrees of freedom thresholds +- Model fit diagnostics +- Parameter significance testing + +**For Non-Technical Users:** +ACRO automatically identifies when research outputs might reveal sensitive information about individuals or organizations, applying industry-standard privacy protection rules without requiring manual review of every result. + +### Output Management + +**What ACRO Provides:** + +* **Suppression Masks** - Clear indication of which results are hidden and why +* **Summary Reports** - Detailed explanation of all disclosure checks performed +* **Audit Trails** - Complete record of all analysis steps and decisions +* **Exception Handling** - Process for requesting release of flagged outputs + +**Workflow Integration:** +The `finalise()` function will: +1. Check that each output with “fail” or “review” status has an exception (if not you will be asked to enter one). +2. Write the outputs to a directory. This directory contains everything that the output checkers need to make a decision. + +## Supported Environments + +### Research Environments + +**Where ACRO Works:** +- Trusted Research Environments (TREs) +- Data safe havens +- Secure data centers +- Academic research computing facilities +- Government statistical offices +- Healthcare research environments From 30283814b3c84236b778d9c4935ea2155a17685a Mon Sep 17 00:00:00 2001 From: Jessica Ikechukwu Date: Tue, 20 Jan 2026 12:34:03 +0000 Subject: [PATCH 11/11] Add welcome documentation for ACRO-R package This document introduces the ACRO-R package, its features, and usage instructions. It also includes acknowledgements and links to relevant resources. Signed-off-by: Jessica Ikechukwu --- vignettes/welcome.Rmd | 49 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 vignettes/welcome.Rmd diff --git a/vignettes/welcome.Rmd b/vignettes/welcome.Rmd new file mode 100644 index 0000000..0be5d2b --- /dev/null +++ b/vignettes/welcome.Rmd @@ -0,0 +1,49 @@ +--- +title: "Welcome to ACRO-R" +--- + +# Welcome to ACRO-R + +## ACRO: Tools for the Semi-Automatic Checking of Research Outputs + +[![IEEE Xplore](https://img.shields.io/badge/IEEE%20Xplore-10.1109/TP.2025.3566052-blue)](https://doi.org/10.1109/TP.2025.3566052) +[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) +[![CRAN](https://www.r-pkg.org/badges/version/acro)](https://CRAN.R-project.org/package=acro) +[![check](https://github.com/AI-SDC/ACRO-R/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/AI-SDC/ACRO-R/actions?query=workflow%3AR-CMD-check) +[![codecov](https://codecov.io/gh/AI-SDC/ACRO-R/graph/badge.svg?token=VxbjBHzeXU)](https://app.codecov.io/gh/AI-SDC/ACRO-R) + +This repository maintains the ACRO R package, which is an interface to the Python [ACRO](https://github.com/AI-SDC/ACRO) package. + +ACRO is a free and open source tool that supports the semi-automated checking of research outputs (SACRO) for privacy disclosure within secure data environments. SACRO is a framework that applies best-practice principles-based [statistical disclosure control](https://en.wikipedia.org/wiki/Statistical_disclosure_control) (SDC) techniques on-the-fly as researchers conduct their analysis. SACRO is designed to assist human checkers rather than seeking to replace them as with current automated rules-based approaches. + +The ACRO package sits over well-known analysis tools that produce outputs such as tables, plots, and statistical models. This package adds functionality to: + +* automatically identify potentially disclosive outputs against a range of commonly used disclosure tests; +* apply optional disclosure mitigation strategies as requested; +* report reasons for applying SDC; +* and produce simple summary documents trusted research environment staff can use to streamline their workflow and maintain auditable records. + +This creates an explicit change in the dynamics so that SDC is something done with researchers rather than to them, and enables more efficient communication with checkers. + +A graphical user interface ([SACRO-Viewer](https://github.com/AI-SDC/SACRO-Viewer)) supports human checkers by displaying the requested output and results of the checks in an immediately accessible format, highlighting identified issues, potential mitigation options, and tracking decisions made. + +## Usage + +Before using any function from the package, an acro object should be initialised using the following R code: + +```r +library("acro") +acro_init(suppress = TRUE) +``` + +## Documentation + +The github-pages contains pre-built [documentation](https://ai-sdc.github.io/ACRO-R/). + +Additionally, see our [paper describing the SACRO framework](https://doi.org/10.1109/TP.2025.3566052) to learn about its principles-based SDC methodology and usage. + +## Acknowledgement + +This work was funded by UK Research and Innovation under Grant Numbers MC_PC_21033 and MC_PC_23006 as part of Phase 1 of the Data and Analytics Research Environments UK ([DARE UK](https://dareuk.org.uk/)) programme, delivered in partnership with Health Data Research UK (HDR UK) and Administrative Data Research UK (ADR UK). The specific projects were Semi-Automatic checking of Research Outputs (SACRO; MC_PC_23006) and Guidelines and Resources for AI Model Access from Trusted Research environments (GRAIMATTER; MC_PC_21033). This project has also been supported by MRC and EPSRC [grant number MR/S010351/1]. + +![UK Research and Innovation](../inst/Images/UK_Research_and_Innovation_logo.svg){width="20%"} ![Health Data Research UK](../inst/Images/health-data-research-uk-hdr-uk-logo-vector.png){width="20%"} ![Logo](../inst/Images/logo_print.png){width="20%"}