17  AI-Automated Analysis

17.1 Overview

ivdtools-analysis is an AI-powered analysis Skill (current version 0.1.0) for in-vitro diagnostic (IVD) evaluation data. It uses the R package ivdtools as its statistical engine and, starting from CSV, TSV, Excel, or RDS data, performs data quality checks and statistical analysis, then generates reproducible Chinese HTML reports, R code, result tables, and figures. It works in conversational agent environments such as Claude Code (/ivdtools-analysis) and OpenAI Codex ($ivdtools-analysis).

Scope statement: This Skill is intended for statistical analysis and evidence compilation; it does not constitute clinical validation, product release, or regulatory approval. Decisions involving clinical, regulatory, or release matters should be independently reviewed by appropriate professionals.

The value of using the Skill in a conversation is not to “replace statistical judgment,” but to standardize the repetitive technical steps: data precheck, parameter confirmation, statistical computation, result verification, and Chinese report generation are executed through a fixed workflow, while data sources, parameters, exclusion records, warnings, result tables, figures, and the software environment are all saved together, reducing the risk of omissions and manual copy errors.

17.2 Applicable Analysis Tasks

The Skill covers 10 categories of analysis tasks, all powered by the corresponding modules of ivdtools as their statistical engine:

Analysis Category	Typical Tasks
Method comparison	Descriptive statistics, correlation, OLS/WLS/Deming/weighted Deming/Passing–Bablok, Bland–Altman, bias at medical decision levels
ROC analysis	Single/multi-marker ROC, AUC, cutoff values, sensitivity/specificity, multivariate Logistic
Qualitative agreement	2×2 tables, sensitivity/specificity/predictive values, overall agreement, Kappa, McNemar
Precision	Variance components, SD/CV, confidence intervals, profile results
Analytical sensitivity	sadler fit, limit of blank/limit of detection/limit of quantitation establishment
Reference intervals	Percentile, parametric, and robust methods with confidence intervals
Stability	Condition trend, test/reference comparison, shelf life, MKT, Arrhenius, stability design
Quality control	Levey–Jennings plots, Westgard rule violation identification
Curve fitting	Curve search, nonlinear/weighted fitting, model comparison, residual diagnostics
Data checks	Outlier candidates, normality tests, bottle-to-bottle ANOVA, Youden plots
Sample size	Bland–Altman, proportion tests, proportion confidence intervals, stability design sample size

17.3 Standard Workflow

The Skill’s analysis follows a fixed process, with a fixed output directory structure, to facilitate verification and traceability.

17.3.1 1. Create a Dedicated Output Directory

The default directory is named <input-file-name>-ivdtools-analysis-YYYYMMDD-HHMMSS, located outside the Skill directory, and does not overwrite existing directories. Source data is always kept read-only and is never modified.

17.3.2 2. Data Precheck

Generate a data inspection JSON with inspect_data.R:

Rscript scripts/inspect_data.R \
  --input /data/example.csv \
  --encoding UTF-8 \
  --output /output/data-inspection.json

The precheck reports the number of rows, duplicate rows/column names, per-column type and proportion of missing values, number of unique values, candidate binary fields and candidate ID fields, category levels, and numeric ranges, helping to uncover data quality issues before analysis.

17.3.3 3. Determine the Analysis Plan

Select the analysis type based on the research objective and confirm parameters that cannot be safely inferred from the data. The Skill will not fabricate clinical cutoff values, allowable bias, stability limits, or acceptance criteria on its own; if such parameters affect the conclusions and cannot be safely derived from the data or the study plan, the user will be asked to confirm them.

17.3.4 4. Execute the Analysis and Render the Report

The Skill copies assets/report-template.Rmd into the output directory, creates an analysis.R with explicit parameters and ivdtools:: namespaced calls to perform the analysis, then renders the Chinese HTML report. The rendering process preserves warnings and messages rather than silently suppressing them.

17.3.5 5. Verify the Results

Before delivery, verify that the total input row count matches the rows excluded at each step, that missing/non-numeric/duplicate records have been reported, that the positive class and direction are correct, that models converge, that the HTML values match results/*.csv, and that sessionInfo() and the actual package versions are recorded.

17.4 Output Contents

A standard delivery directory contains:

analysis.R                    # Reusable analysis code
report.Rmd                    # Report source file
report.html                   # Chinese HTML report
analysis-manifest.json        # Manifest of data sources, parameters, and artifacts
session-info.txt              # R environment and package versions
results/*.csv                 # Machine-readable result tables
figures/*.png                 # Analysis figures

The Chinese report includes, at minimum, the analysis objective, data source, data quality findings, methods and parameters, result tables, figures, exclusions and warnings, interpretation of results, limitations, and reproducibility information.

17.5 Installation and Usage

17.5.1 Runtime Environment

R ≥ 4.1.0, a matching version of ivdtools, Pandoc, and dependent packages such as ggplot2, VCA, VFP, rmarkdown, and knitr. Run the environment check first:

Rscript scripts/check_environment.R

An output of STATUS: READY indicates readiness; otherwise, missing items are listed. Installing/supplementing dependencies writes to the R library and may only be executed with explicit user authorization (Rscript scripts/install_ivdtools.R --yes).

17.5.2 Use in Claude Code

The Skill is registered as an invocable skill; call it directly in the conversation:

/ivdtools-analysis analyze the Results worksheet of /data/method_comparison.xlsx.
The sample ID is sample_id, the candidate method is candidate, and the reference method is reference.
Per the study plan, perform Deming regression (lambda=1) and difference-type Bland–Altman analysis,
with a 95% confidence level, and output a reproducible Chinese HTML report.

17.5.3 Use in OpenAI Codex

Name $ivdtools-analysis in the conversation and attach the data and analysis requirements:

Please use $ivdtools-analysis to analyze /data/roc.csv.
sample_id is the sample ID, truth is the binary reference result where positive is the positive class;
marker1 and marker2 are the markers under evaluation. Please output AUC, cutoff values, sensitivity,
specificity, ROC plots, and a Chinese HTML report. The cutoff derived from the data is exploratory only.

17.5.4 Recommended Details When Submitting a Task

1. Data file path (for Excel workbooks, also specify the worksheet);
2. Analysis objective and study design;
3. Mapping of fields such as sample ID, candidate/reference method, outcome, time, and lot number;
4. Positive class, direction, paired/repeated structure, and precision design formula;
5. Confidence level, power, statistical method, and plan-specified parameters;
6. Acceptance criteria such as medical decision levels, allowable bias, stability limits, and QC target mean/SD.

17.6 Data Handling Principles

• Preserve the original column names; do not automatically call make.names() to rename them;
• Do not default to imputing missing values, deleting outliers, averaging repeated measurements, or reversing the outcome direction;
• Outlier testing only produces candidate records for review and does not constitute a basis for automatic deletion;
• Keep a record of the rationale for excluded records and, where applicable, report sensitivity analyses with and without them;
• State the operations and rationale for any data transformation, exclusion, aggregation, and post-hoc analysis choices;
• Statistical significance does not equal clinical acceptability; acceptability conclusions can only be drawn against acceptance limits specified in the plan or provided by the user.

17.7 Frequently Asked Questions

• Version mismatch: When the environment check reports an ivdtools version mismatch, do not directly overwrite the newer installed version; choose a new writable R library, install the target version there after authorization, and verify it with --library.
• Excel cannot be prechecked: Confirm that readxl is installed; when there are multiple worksheets, use --sheet to select explicitly.
• HTML cannot be rendered: Confirm that rmarkdown and knitr are installed and that rmarkdown::pandoc_available() is TRUE; review the actual warnings or errors recorded in report.Rmd rather than silently ignoring them.
• Binary direction is reversed: Check the positive class, factor levels, marker direction, and test/reference mapping, and record the direction change and rationale before re-analyzing.
• Outliers or repeated measurements present: Do not automatically delete or average; first determine the handling approach based on the raw records, experimental design, and preset rules.