[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CTFP5E08422BDXSFGTXEFS":3,"skill-same:01M7CTFP5E08422BDXSFGTXEFS":118},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":31,"install":32,"resources":45},"01M7CTFP5E08422BDXSFGTXEFS","batch-effect-correction",null,"Use when correcting batch effects in merged bulk expression matrices with sample-level batch metadata while preserving biological group structure and generating before-and-after QC plots. NOT for: single-cell integration, raw FASTQ processing, differential expression without batch labels, or datasets without biological groups.","mrsonord2240\u002Fopenscience-specialists","mrsonord2240","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F76487430?v=4","01M7CTEM40S43GSJZ9A3YCCXZK","Samuel Nord","01M7CTEM4K69JD1GBYNHVJ9ZP4",2,"MIT","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: batch-effect-correction\ndescription: \"Use when correcting batch effects in merged bulk expression matrices with sample-level batch metadata while preserving biological group structure and generating before-and-after QC plots. NOT for: single-cell integration, raw FASTQ processing, differential expression without batch labels, or datasets without biological groups.\"\nlicense: MIT\nskill-author: AIPOCH\n---\n\n# Batch Effect Correction\n\n## Prerequisites\n\nRun the following before the first analysis to install all required R packages:\n\n```bash\nRscript -e \"if (!require('BiocManager', quietly=TRUE)) install.packages('BiocManager'); BiocManager::install(c('sva', 'limma')); install.packages('ggplot2', repos='https:\u002F\u002Fcloud.r-project.org')\"\n```\n\n> Note: `sva` and `limma` are Bioconductor packages and require `BiocManager` for installation. `ggplot2` is a standard CRAN package.\n\n**The skill cannot run until these packages are installed.** In new or bare R environments, always run the prerequisite step first.\n\n---\n\n## When to Read External Files\n\n| Situation                  | File to Read                    | Purpose                                                             |\n| -------------------------- | ------------------------------- | ------------------------------------------------------------------- |\n| **Need algorithm details** | `references\u002Falgorithm.md`       | ComBat workflow, assumptions, and QC logic                          |\n| **Need to run analysis**   | `scripts\u002Fmain.R`                | Execute: `Rscript scripts\u002Fmain.R --input_file ... --group_file ...` |\n| **Encounter errors**       | `references\u002Ftroubleshooting.md` | Common errors and solutions                                         |\n| **Need CLI examples**      | `references\u002Fcli-guide.md`       | Detailed CLI usage examples and baseline run record                 |\n| **Need test data**         | `tests\u002Fdata\u002F`                   | Sample input files for testing                                      |\n\n---\n\n## Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  --input_file .\u002Fexpression_matrix.csv \\\n  --group_file .\u002Fsample_info.csv \\\n  --output_dir .\u002Foutput\u002F \\\n  --batch_column batch \\\n  --group_column group \\\n  --sample_column sample \\\n  --log_transform auto \\\n  --timeout_seconds 600 \\\n  --seed 42\n```\n\n---\n\n## Arguments\n\n| Short | Long                | Type      | Default      | Description                                                |\n| ----- | ------------------- | --------- | ------------ | ---------------------------------------------------------- |\n| `-i`  | `--input_file`      | character | **required** | Expression matrix file (genes as rows, samples as columns) |\n| `-g`  | `--group_file`      | character | **required** | Sample metadata file (sample ID, group, and batch columns) |\n| `-o`  | `--output_dir`      | character | `.\u002Foutput\u002F`  | Output directory                                           |\n| `-b`  | `--batch_column`    | character | `batch`      | Batch column name in metadata                              |\n| `-c`  | `--group_column`    | character | `group`      | Biological group column name in metadata                   |\n| `-n`  | `--sample_column`   | character | `sample`     | Sample ID column name in metadata                          |\n| `-l`  | `--log_transform`   | character | `auto`       | Log transform mode: `auto`, `yes`, `no`                    |\n| `-t`  | `--timeout_seconds` | integer   | `600`        | Elapsed time limit in seconds; use `0` to disable          |\n| `-s`  | `--seed`            | integer   | `42`         | Random seed for reproducibility                            |\n\n---\n\n## Input Format\n\n### Expression Matrix (input_file)\n\nGenes as rows, samples as columns, CSV format with gene ID in the first column.\n\n```csv\n\"\",\"Sample01\",\"Sample02\",\"Sample03\"\n\"GeneA\",5.12,4.87,6.03\n\"GeneB\",8.44,8.11,7.95\n```\n\nRequirements:\n\n- Gene IDs must be unique and non-empty\n- Sample column names must be unique and non-empty\n- Expression values must be numeric and finite\n- Extra expression-matrix sample columns not present in metadata are allowed and will be ignored with a warning\n\n### Sample Metadata (group_file)\n\nCSV with sample ID, biological group, and batch columns.\n\n```csv\n\"sample\",\"group\",\"batch\"\n\"Sample01\",\"Control\",\"Batch1\"\n\"Sample02\",\"Case\",\"Batch1\"\n\"Sample03\",\"Case\",\"Batch2\"\n```\n\nRequirements:\n\n- Sample IDs must be unique and non-empty\n- At least 2 biological groups are required\n- At least 2 batches are required\n- Each group and each batch must contain at least 2 samples\n- Metadata may describe a subset of expression-matrix samples; the analysis will keep only metadata-matched samples and warn about ignored expression columns\n\n---\n\n## Output Files\n\n| File                              | Description                                                  |\n| --------------------------------- | ------------------------------------------------------------ |\n| `corrected_expression_matrix.csv` | Batch-corrected expression matrix                            |\n| `matched_sample_info.csv`         | Standardized metadata used in the analysis                   |\n| `batch_before_boxplot.pdf`        | Sample distribution boxplot before correction                |\n| `batch_after_boxplot.pdf`         | Sample distribution boxplot after correction                 |\n| `batch_before_pca.pdf`            | PCA scatter plot before correction with batch-colored points |\n| `batch_after_pca.pdf`             | PCA scatter plot after correction with batch-colored points  |\n| `batch_before_clustering.pdf`     | Hierarchical clustering before correction                    |\n| `batch_after_clustering.pdf`      | Hierarchical clustering after correction                     |\n| `session_info.txt`                | R session and package version info                           |\n\n---\n\n## Workflow\n\n### Step 1: Validate Input\n\n- Check file existence and non-empty input files\n- Validate metadata column presence\n- Verify expression values are numeric and finite\n- Confirm at least 2 groups, 2 batches, and at least 2 samples per group\u002Fbatch\n\n### Step 2: Align and Prepare Matrix\n\n- Reorder expression columns to match metadata sample order\n- Keep only metadata-matched samples; warn if the expression matrix contains extra samples absent from metadata\n- Decide whether log transformation is needed (`auto`, `yes`, or `no`)\n- Apply `log2(x + 1)` only when required\n\n### Step 3: Run Batch Correction\n\n- Build the design matrix with biological group information\n- Run `sva::ComBat()` to remove batch-driven variation\n- Preserve modeled biological group structure during correction\n\n### Step 4: Normalize and Export Results\n\n- Apply `limma::normalizeBetweenArrays()` after ComBat\n- Write the corrected matrix and matched metadata\n- Save before\u002Fafter QC plots and session information\n\n---\n\n## Methods\n\n### ComBat\n\nEmpirical Bayes batch-effect correction using `sva::ComBat()`. Recommended when merged bulk expression datasets contain known batch labels and at least two biological groups.\n\n### Log Transformation\n\nSupports `auto`, `yes`, and `no`. The `auto` mode applies `log2(x + 1)` only when the matrix appears to be on a raw-like scale.\n\n### normalizeBetweenArrays\n\nPost-correction normalization with `limma::normalizeBetweenArrays()` to reduce remaining cross-sample distribution differences.\n\n### QC Visualization\n\nGenerates paired boxplots, PCA scatter plots with conditional batch ellipses, and hierarchical clustering plots before and after correction to assess whether batch-driven structure is reduced.\n\n---\n\n## Agent Response Contract\n\nAfter a successful run, report:\n\n1. **Sample count** retained after metadata matching and any subset filtering\n2. **Batch count** and **group count** used in the ComBat design matrix\n3. **Log transformation** applied (auto-detected, forced yes, or skipped)\n4. **QC assessment**: describe whether before\u002Fafter PCA plots show reduced batch clustering\n5. **Artifact paths**: `corrected_expression_matrix.csv`, `batch_after_pca.pdf`, `batch_after_clustering.pdf`\n\n---\n\n## Examples\n\n### Basic Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g sample_info.csv \\\n  -o .\u002Foutput\n```\n\n### With Custom Metadata Columns\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g metadata.csv \\\n  -o .\u002Foutput \\\n  -n sample_id \\\n  -c condition \\\n  -b platform_batch\n```\n\n### Disable Log Transform and Timeout\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g sample_info.csv \\\n  -o .\u002Foutput \\\n  -l no \\\n  -t 0 \\\n  -s 42\n```\n\n---\n\n## Error Handling\n\n### Common Errors\n\n| Error                      | Cause                                                                                      | Solution                                                                                         |\n| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |\n| `SKILL_FILE_NOT_FOUND`     | Input file does not exist                                                                  | Check file path                                                                                  |\n| `SKILL_EMPTY_FILE`         | Input file exists but contains no data                                                     | Recreate or re-export the file                                                                   |\n| `SKILL_MISSING_COLUMNS`    | Metadata file is missing sample, group, or batch columns                                   | Check header names or pass custom column names                                                   |\n| `SKILL_SAMPLE_MISMATCH`    | Metadata sample IDs do not match expression matrix columns                                 | Verify sample names between files                                                                |\n| `SKILL_INVALID_DATA`       | Dataset fails minimum design checks (\u003C 2 batches, \u003C 2 groups, \u003C 2 samples per batch\u002Fgroup) | Review group counts, batch counts, and ID validity                                               |\n| `SKILL_INVALID_TYPE`       | Expression values are non-numeric or non-finite                                            | Clean matrix values before running                                                               |\n| `SKILL_TIMEOUT`            | Run exceeded the configured time limit                                                     | Increase `--timeout_seconds` or set it to `0`                                                    |\n| `SKILL_DEPENDENCY_MISSING` | Required R package is not installed                                                        | Install with: `Rscript -e \"BiocManager::install(c('sva','limma')); install.packages('ggplot2')\"` |\n| `SKILL_RUNTIME_ERROR`      | Runtime I\u002FO or filesystem error occurred                                                   | Check read\u002Fwrite permissions and environment                                                     |\n\n**IF error persists**, READ: `references\u002Ftroubleshooting.md`\n\n**Troubleshooting note:** In environments where packages are not yet installed, `SKILL_DEPENDENCY_MISSING` will fire before file-validation or `--help`. Install dependencies first, then re-run to expose file-related errors or access `--help`.\n\n---\n\n## Input Validation\n\nThis skill accepts:\n\n1. A bulk RNA-seq or microarray expression matrix (CSV, genes as rows, samples as columns)\n2. A sample metadata file (CSV) with sample ID, biological group, and batch columns; at least 2 batches and 2 biological groups are required\n\nIf the user's request does not involve batch effect correction on merged bulk expression matrices — for example, asking to integrate single-cell RNA-seq data, process raw FASTQ files, run differential expression without batch labels, or analyze datasets with only one batch — do not proceed with the workflow. Instead respond:\n\n> \"Batch Effect Correction is designed to remove batch-driven variation from merged bulk expression matrices using ComBat, while preserving biological group structure. Your request appears to be outside this scope. Please provide a multi-batch expression matrix with sample-level batch metadata, or use a more appropriate tool for single-cell integration, differential expression, or raw sequencing processing.\"\n\n---\n\n## Testing\n\n### Test with Sample Data\n\n```bash\n# Check help (requires packages installed)\nRscript scripts\u002Fmain.R --help\n\n# Run with bundled test data\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fexpression_matrix_merged.csv \\\n  -g tests\u002Fdata\u002Fsample_info.csv \\\n  -o tests\u002Foutput\u002F\n```\n\n### Validation Commands\n\n```bash\n# Check corrected matrix exists\nls -la tests\u002Foutput\u002Fcorrected_expression_matrix.csv\n\n# Check matched metadata exists\nls -la tests\u002Foutput\u002Fmatched_sample_info.csv\n\n# Check PCA output exists\nls -la tests\u002Foutput\u002Fbatch_after_pca.pdf\n```\n\n---\n\n## Implementation Checklist\n\n- [x] CLI parsing with `optparse`\n- [x] `set.seed()` for reproducibility\n- [x] `requireNamespace()` dependency checks\n- [x] Session info recording\n- [x] Time-limit support through `setTimeLimit()`\n- [x] File reading instructions in SKILL.md\n- [x] Modular script structure in `scripts\u002F`\n- [x] Test data provided\n- [x] Error handling with `SKILL_*` codes\n- [x] QC plots generated before and after correction\n- [x] References in `references\u002F` directory\n\n---\n\n_Last updated: 2026-04-27 | Version: 1.1.0_\n","# Batch Effect Correction\n\n## Prerequisites\n\nRun the following before the first analysis to install all required R packages:\n\n```bash\nRscript -e \"if (!require('BiocManager', quietly=TRUE)) install.packages('BiocManager'); BiocManager::install(c('sva', 'limma')); install.packages('ggplot2', repos='https:\u002F\u002Fcloud.r-project.org')\"\n```\n\n> Note: `sva` and `limma` are Bioconductor packages and require `BiocManager` for installation. `ggplot2` is a standard CRAN package.\n\n**The skill cannot run until these packages are installed.** In new or bare R environments, always run the prerequisite step first.\n\n---\n\n## When to Read External Files\n\n| Situation                  | File to Read                    | Purpose                                                             |\n| -------------------------- | ------------------------------- | ------------------------------------------------------------------- |\n| **Need algorithm details** | `references\u002Falgorithm.md`       | ComBat workflow, assumptions, and QC logic                          |\n| **Need to run analysis**   | `scripts\u002Fmain.R`                | Execute: `Rscript scripts\u002Fmain.R --input_file ... --group_file ...` |\n| **Encounter errors**       | `references\u002Ftroubleshooting.md` | Common errors and solutions                                         |\n| **Need CLI examples**      | `references\u002Fcli-guide.md`       | Detailed CLI usage examples and baseline run record                 |\n| **Need test data**         | `tests\u002Fdata\u002F`                   | Sample input files for testing                                      |\n\n---\n\n## Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  --input_file .\u002Fexpression_matrix.csv \\\n  --group_file .\u002Fsample_info.csv \\\n  --output_dir .\u002Foutput\u002F \\\n  --batch_column batch \\\n  --group_column group \\\n  --sample_column sample \\\n  --log_transform auto \\\n  --timeout_seconds 600 \\\n  --seed 42\n```\n\n---\n\n## Arguments\n\n| Short | Long                | Type      | Default      | Description                                                |\n| ----- | ------------------- | --------- | ------------ | ---------------------------------------------------------- |\n| `-i`  | `--input_file`      | character | **required** | Expression matrix file (genes as rows, samples as columns) |\n| `-g`  | `--group_file`      | character | **required** | Sample metadata file (sample ID, group, and batch columns) |\n| `-o`  | `--output_dir`      | character | `.\u002Foutput\u002F`  | Output directory                                           |\n| `-b`  | `--batch_column`    | character | `batch`      | Batch column name in metadata                              |\n| `-c`  | `--group_column`    | character | `group`      | Biological group column name in metadata                   |\n| `-n`  | `--sample_column`   | character | `sample`     | Sample ID column name in metadata                          |\n| `-l`  | `--log_transform`   | character | `auto`       | Log transform mode: `auto`, `yes`, `no`                    |\n| `-t`  | `--timeout_seconds` | integer   | `600`        | Elapsed time limit in seconds; use `0` to disable          |\n| `-s`  | `--seed`            | integer   | `42`         | Random seed for reproducibility                            |\n\n---\n\n## Input Format\n\n### Expression Matrix (input_file)\n\nGenes as rows, samples as columns, CSV format with gene ID in the first column.\n\n```csv\n\"\",\"Sample01\",\"Sample02\",\"Sample03\"\n\"GeneA\",5.12,4.87,6.03\n\"GeneB\",8.44,8.11,7.95\n```\n\nRequirements:\n\n- Gene IDs must be unique and non-empty\n- Sample column names must be unique and non-empty\n- Expression values must be numeric and finite\n- Extra expression-matrix sample columns not present in metadata are allowed and will be ignored with a warning\n\n### Sample Metadata (group_file)\n\nCSV with sample ID, biological group, and batch columns.\n\n```csv\n\"sample\",\"group\",\"batch\"\n\"Sample01\",\"Control\",\"Batch1\"\n\"Sample02\",\"Case\",\"Batch1\"\n\"Sample03\",\"Case\",\"Batch2\"\n```\n\nRequirements:\n\n- Sample IDs must be unique and non-empty\n- At least 2 biological groups are required\n- At least 2 batches are required\n- Each group and each batch must contain at least 2 samples\n- Metadata may describe a subset of expression-matrix samples; the analysis will keep only metadata-matched samples and warn about ignored expression columns\n\n---\n\n## Output Files\n\n| File                              | Description                                                  |\n| --------------------------------- | ------------------------------------------------------------ |\n| `corrected_expression_matrix.csv` | Batch-corrected expression matrix                            |\n| `matched_sample_info.csv`         | Standardized metadata used in the analysis                   |\n| `batch_before_boxplot.pdf`        | Sample distribution boxplot before correction                |\n| `batch_after_boxplot.pdf`         | Sample distribution boxplot after correction                 |\n| `batch_before_pca.pdf`            | PCA scatter plot before correction with batch-colored points |\n| `batch_after_pca.pdf`             | PCA scatter plot after correction with batch-colored points  |\n| `batch_before_clustering.pdf`     | Hierarchical clustering before correction                    |\n| `batch_after_clustering.pdf`      | Hierarchical clustering after correction                     |\n| `session_info.txt`                | R session and package version info                           |\n\n---\n\n## Workflow\n\n### Step 1: Validate Input\n\n- Check file existence and non-empty input files\n- Validate metadata column presence\n- Verify expression values are numeric and finite\n- Confirm at least 2 groups, 2 batches, and at least 2 samples per group\u002Fbatch\n\n### Step 2: Align and Prepare Matrix\n\n- Reorder expression columns to match metadata sample order\n- Keep only metadata-matched samples; warn if the expression matrix contains extra samples absent from metadata\n- Decide whether log transformation is needed (`auto`, `yes`, or `no`)\n- Apply `log2(x + 1)` only when required\n\n### Step 3: Run Batch Correction\n\n- Build the design matrix with biological group information\n- Run `sva::ComBat()` to remove batch-driven variation\n- Preserve modeled biological group structure during correction\n\n### Step 4: Normalize and Export Results\n\n- Apply `limma::normalizeBetweenArrays()` after ComBat\n- Write the corrected matrix and matched metadata\n- Save before\u002Fafter QC plots and session information\n\n---\n\n## Methods\n\n### ComBat\n\nEmpirical Bayes batch-effect correction using `sva::ComBat()`. Recommended when merged bulk expression datasets contain known batch labels and at least two biological groups.\n\n### Log Transformation\n\nSupports `auto`, `yes`, and `no`. The `auto` mode applies `log2(x + 1)` only when the matrix appears to be on a raw-like scale.\n\n### normalizeBetweenArrays\n\nPost-correction normalization with `limma::normalizeBetweenArrays()` to reduce remaining cross-sample distribution differences.\n\n### QC Visualization\n\nGenerates paired boxplots, PCA scatter plots with conditional batch ellipses, and hierarchical clustering plots before and after correction to assess whether batch-driven structure is reduced.\n\n---\n\n## Agent Response Contract\n\nAfter a successful run, report:\n\n1. **Sample count** retained after metadata matching and any subset filtering\n2. **Batch count** and **group count** used in the ComBat design matrix\n3. **Log transformation** applied (auto-detected, forced yes, or skipped)\n4. **QC assessment**: describe whether before\u002Fafter PCA plots show reduced batch clustering\n5. **Artifact paths**: `corrected_expression_matrix.csv`, `batch_after_pca.pdf`, `batch_after_clustering.pdf`\n\n---\n\n## Examples\n\n### Basic Usage\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g sample_info.csv \\\n  -o .\u002Foutput\n```\n\n### With Custom Metadata Columns\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g metadata.csv \\\n  -o .\u002Foutput \\\n  -n sample_id \\\n  -c condition \\\n  -b platform_batch\n```\n\n### Disable Log Transform and Timeout\n\n```bash\nRscript scripts\u002Fmain.R \\\n  -i expression_matrix.csv \\\n  -g sample_info.csv \\\n  -o .\u002Foutput \\\n  -l no \\\n  -t 0 \\\n  -s 42\n```\n\n---\n\n## Error Handling\n\n### Common Errors\n\n| Error                      | Cause                                                                                      | Solution                                                                                         |\n| -------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ |\n| `SKILL_FILE_NOT_FOUND`     | Input file does not exist                                                                  | Check file path                                                                                  |\n| `SKILL_EMPTY_FILE`         | Input file exists but contains no data                                                     | Recreate or re-export the file                                                                   |\n| `SKILL_MISSING_COLUMNS`    | Metadata file is missing sample, group, or batch columns                                   | Check header names or pass custom column names                                                   |\n| `SKILL_SAMPLE_MISMATCH`    | Metadata sample IDs do not match expression matrix columns                                 | Verify sample names between files                                                                |\n| `SKILL_INVALID_DATA`       | Dataset fails minimum design checks (\u003C 2 batches, \u003C 2 groups, \u003C 2 samples per batch\u002Fgroup) | Review group counts, batch counts, and ID validity                                               |\n| `SKILL_INVALID_TYPE`       | Expression values are non-numeric or non-finite                                            | Clean matrix values before running                                                               |\n| `SKILL_TIMEOUT`            | Run exceeded the configured time limit                                                     | Increase `--timeout_seconds` or set it to `0`                                                    |\n| `SKILL_DEPENDENCY_MISSING` | Required R package is not installed                                                        | Install with: `Rscript -e \"BiocManager::install(c('sva','limma')); install.packages('ggplot2')\"` |\n| `SKILL_RUNTIME_ERROR`      | Runtime I\u002FO or filesystem error occurred                                                   | Check read\u002Fwrite permissions and environment                                                     |\n\n**IF error persists**, READ: `references\u002Ftroubleshooting.md`\n\n**Troubleshooting note:** In environments where packages are not yet installed, `SKILL_DEPENDENCY_MISSING` will fire before file-validation or `--help`. Install dependencies first, then re-run to expose file-related errors or access `--help`.\n\n---\n\n## Input Validation\n\nThis skill accepts:\n\n1. A bulk RNA-seq or microarray expression matrix (CSV, genes as rows, samples as columns)\n2. A sample metadata file (CSV) with sample ID, biological group, and batch columns; at least 2 batches and 2 biological groups are required\n\nIf the user's request does not involve batch effect correction on merged bulk expression matrices — for example, asking to integrate single-cell RNA-seq data, process raw FASTQ files, run differential expression without batch labels, or analyze datasets with only one batch — do not proceed with the workflow. Instead respond:\n\n> \"Batch Effect Correction is designed to remove batch-driven variation from merged bulk expression matrices using ComBat, while preserving biological group structure. Your request appears to be outside this scope. Please provide a multi-batch expression matrix with sample-level batch metadata, or use a more appropriate tool for single-cell integration, differential expression, or raw sequencing processing.\"\n\n---\n\n## Testing\n\n### Test with Sample Data\n\n```bash\n# Check help (requires packages installed)\nRscript scripts\u002Fmain.R --help\n\n# Run with bundled test data\nRscript scripts\u002Fmain.R \\\n  -i tests\u002Fdata\u002Fexpression_matrix_merged.csv \\\n  -g tests\u002Fdata\u002Fsample_info.csv \\\n  -o tests\u002Foutput\u002F\n```\n\n### Validation Commands\n\n```bash\n# Check corrected matrix exists\nls -la tests\u002Foutput\u002Fcorrected_expression_matrix.csv\n\n# Check matched metadata exists\nls -la tests\u002Foutput\u002Fmatched_sample_info.csv\n\n# Check PCA output exists\nls -la tests\u002Foutput\u002Fbatch_after_pca.pdf\n```\n\n---\n\n## Implementation Checklist\n\n- [x] CLI parsing with `optparse`\n- [x] `set.seed()` for reproducibility\n- [x] `requireNamespace()` dependency checks\n- [x] Session info recording\n- [x] Time-limit support through `setTimeLimit()`\n- [x] File reading instructions in SKILL.md\n- [x] Modular script structure in `scripts\u002F`\n- [x] Test data provided\n- [x] Error handling with `SKILL_*` codes\n- [x] QC plots generated before and after correction\n- [x] References in `references\u002F` directory\n\n---\n\n_Last updated: 2026-04-27 | Version: 1.1.0_\n",{"name":5,"license":15,"description":7,"skill-author":24},"AIPOCH","main","e0956dc9606356ab78468936b502e55a365282e2","specialist-src\u002Fpublished-skills\u002Fbatch-effect-correction",0,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists","https:\u002F\u002Fgithub.com\u002Fmrsonord2240","2026-10-12 03:19:04",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add mrsonord2240\u002Fopenscience-specialists --skill batch-effect-correction",{"tool":38,"command":39},"bunx","bunx skills add mrsonord2240\u002Fopenscience-specialists --skill batch-effect-correction",{"tool":41,"command":42},"pnpm","pnpm dlx skills add mrsonord2240\u002Fopenscience-specialists --skill batch-effect-correction","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002FSKILL.md",true,[46,52,56,60,66,70,74,78,82,86,90,96,100,106,110,114],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Falgorithm.md","REFERENCE","参考文档",3744,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Freferences\u002Falgorithm.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fcli-guide.md",6723,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Freferences\u002Fcli-guide.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Ftroubleshooting.md",5345,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Freferences\u002Ftroubleshooting.md",{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"scripts\u002Ffunctions.R","SCRIPT","脚本",1187,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Ffunctions.R",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"scripts\u002Finput_functions.R",4794,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Finput_functions.R",{"path":71,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":72,"sourceHtmlUrl":73},"scripts\u002Fmain.R",4429,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Fmain.R",{"path":75,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":76,"sourceHtmlUrl":77},"scripts\u002Foutput_utils.R",1855,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Foutput_utils.R",{"path":79,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":80,"sourceHtmlUrl":81},"scripts\u002Fplotting.R",4358,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Fplotting.R",{"path":83,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":84,"sourceHtmlUrl":85},"scripts\u002Frun_analysis.R",1225,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Frun_analysis.R",{"path":87,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":88,"sourceHtmlUrl":89},"scripts\u002Futils.R",3937,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Fscripts\u002Futils.R",{"path":91,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":94,"sourceHtmlUrl":95},"tests\u002Fdata\u002Fexpression_matrix_merged.csv","ASSET","资产文件",107084,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Fdata\u002Fexpression_matrix_merged.csv",{"path":97,"resourceType":92,"resourceTypeDesc":93,"sizeBytes":98,"sourceHtmlUrl":99},"tests\u002Fdata\u002Fsample_info.csv",2452,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Fdata\u002Fsample_info.csv",{"path":101,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":104,"sourceHtmlUrl":105},"tests\u002Frun_tests.R","OTHER","其他",894,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Frun_tests.R",{"path":107,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":108,"sourceHtmlUrl":109},"tests\u002Ftestthat\u002Fhelper-load-scripts.R",459,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Ftestthat\u002Fhelper-load-scripts.R",{"path":111,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":112,"sourceHtmlUrl":113},"tests\u002Ftestthat\u002Fsetup.R",247,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Ftestthat\u002Fsetup.R",{"path":115,"resourceType":102,"resourceTypeDesc":103,"sizeBytes":116,"sourceHtmlUrl":117},"tests\u002Ftestthat\u002Ftest-batch-correction.R",6520,"https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialist-src\u002Fpublished-skills\u002Fbatch-effect-correction\u002Ftests\u002Ftestthat\u002Ftest-batch-correction.R",[119,127,134,141,148,155],{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":124,"categories":125,"keywords":126,"publishedAt":19},"01M7CW36A6QAGWFE2C008M1XPG","bio-workflows-metabolomics-pipeline","Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC\u002Fdrift\u002Fnormalization, confidence-stratified annotation, permutation-validated statistics, background-aware pathway mapping), naming what each stage decides and where it silently fails. Use when running a full LC-MS metabolomics study from raw mzML to enriched pathways and needing the honest handoffs between stages. Each stage defers to its component skill for parameters and traps; for stable-isotope flux (a separate branch, not this untargeted flow) see metabolomics\u002Fisotope-tracing.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-workflows-metabolomics-pipeline\u002FSKILL.md",[],[],{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":133,"publishedAt":19},"01M7CW2Y18623NA2S1Y30FRQW1","bio-metabolomics-xcms-preprocessing","Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment\u002FXcmsExperiment API, taking raw mzML to a feature table via CentWave peak detection, retention-time alignment, peak-density correspondence, gap-filling, CAMERA redundancy collapse, and built-in QC feature filtering. Use when converting centroided LC-MS runs into a features-by-samples matrix and deciding centWave\u002Fgrouping\u002Falignment parameters. For drift correction and QC\u002FCV filtering execution see metabolomics\u002Fnormalization-qc; for metabolite identification see metabolomics\u002Fmetabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics\u002Fmsdial-preprocessing; for downstream statistics see metabolomics\u002Fstatistical-analysis.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-xcms-preprocessing\u002FSKILL.md",[],[],{"skillNo":135,"name":136,"nameZh":6,"description":137,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":138,"categories":139,"keywords":140,"publishedAt":19},"01M7CW2M364HVWPNQEKE2WP4PP","bio-metabolomics-statistical-analysis","Decision-grade statistical analysis for metabolomics intensity tables. Covers transformation and scaling (Pareto vs unit-variance as a hidden hypothesis), unsupervised structure (PCA\u002FHCA for QC), permutation-validated PLS-DA\u002FOPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch\u002FMann-Whitney\u002FANOVA\u002FLMM with covariate adjustment), and dependence-aware multiple testing. Use when testing which metabolites differ, building or validating a discriminant model, choosing a scaling, or correcting many correlated tests. For sample-wise normalization\u002Fdrift correction see metabolomics\u002Fnormalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning\u002Fbiomarker-discovery and machine-learning\u002Fmodel-validation; for pathway interpretation see metabolomics\u002Fpathway-mapping; for design\u002Fpower\u002Fmultiplicity regime see experimental-design\u002Fmultiple-testing.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-statistical-analysis\u002FSKILL.md",[],[],{"skillNo":142,"name":143,"nameZh":6,"description":144,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":145,"categories":146,"keywords":147,"publishedAt":19},"01M7CW2BCBF851WYE03Z8XPEDQ","bio-metabolomics-pathway-mapping","Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA\u002FQEA), mummichog\u002FPSEA on raw m\u002Fz peaks, and network-diffusion enrichment (FELLA), with correct background-set construction and honest interpretive ceilings. Use when interpreting differential metabolites or an untargeted LC-MS feature table in pathway context, choosing ORA vs MSEA vs mummichog vs topology, or setting the reference\u002Fbackground set. For annotation confidence levels feeding ORA see metabolomics\u002Fmetabolite-annotation; for gene-set concepts see pathway-analysis\u002Fgo-enrichment and pathway-analysis\u002Fgsea; for joint gene+metabolite pathways see multi-omics-integration\u002Fmofa-integration.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-pathway-mapping\u002FSKILL.md",[],[],{"skillNo":149,"name":150,"nameZh":6,"description":151,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":152,"categories":153,"keywords":154,"publishedAt":19},"01M7CW21NSZMCPMF7D9CHJM718","bio-metabolomics-normalization-qc","Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS\u002FGC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak\u002Ffeature table before statistical analysis, choosing a drift-correction or sample-normalization method, deciding QC RSD vs D-ratio filtering, or handling left-censored missing values. The feature table is produced by metabolomics\u002Fxcms-preprocessing or metabolomics\u002Fmsdial-preprocessing; transformation\u002Fscaling for modeling defers to metabolomics\u002Fstatistical-analysis; cross-study design issues link to experimental-design\u002Fbatch-design.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-normalization-qc\u002FSKILL.md",[],[],{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":123,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":161,"publishedAt":19},"01M7CW1SWVM0NYHVE6Q7MA3G7R","bio-metabolomics-msdial-preprocessing","Runs the MS-DIAL preprocessing workflow (peak picking, MS2Dec spectral deconvolution, alignment, gap-filling) and imports the alignment-result table into R or Python with honest filtering. Use when preprocessing LC-MS DDA\u002FDIA (SWATH) or GC-MS raw data with MS-DIAL, deciding MS-DIAL vs XCMS, configuring the MSDIALCUI console run, or parsing an MS-DIAL export into a clean feature matrix. For programmatic R peak detection and the feature-table-as-artifact framing see metabolomics\u002Fxcms-preprocessing; for lipid annotation mode see metabolomics\u002Flipidomics; for MSI-level confidence honesty see metabolomics\u002Fmetabolite-annotation; for drift correction and QC see metabolomics\u002Fnormalization-qc.","https:\u002F\u002Fgithub.com\u002Fmrsonord2240\u002Fopenscience-specialists\u002Fblob\u002Fmain\u002Fspecialists\u002Funtargeted-metabolomics-analyst\u002Fversions\u002F1.0.0\u002Fpackage\u002Fskills\u002Fbio-metabolomics-msdial-preprocessing\u002FSKILL.md",[],[]]