AGENT SKILL

gene-protein-expression-matrix-normalization

Use when normalizing bulk gene or protein expression matrices with log2 transform, z-score standardization, or min-max scaling before downstream visualization or exploratory analysis. NOT for count-model normalization such as TPM/DESeq2 size factors, batch correction, or single-cell preprocessing.

License 许可
MIT
最近更新
2026-10-12
Stars
★ 2
Forks
0

01 前言 Front Matter

name
gene-protein-expression-matrix-normalization
author
AIPOCH
license
MIT
description
Use when normalizing bulk gene or protein expression matrices with log2 transform, z-score standardization, or min-max scaling before downstream visualization or exploratory analysis. NOT for count-model normalization such as TPM/DESeq2 size factors, batch correction, or single-cell preprocessing.

02 资源文件 13

03 SKILL.md 正文

Source: https://github.com/aipoch/medical-research-skills

Gene Protein Expression Matrix Normalization

When to Use

Use this skill when the user wants to normalize a numeric expression matrix before plotting, clustering, or exploratory comparison.

Typical requests:

  • "Normalize this gene expression matrix with log2"
  • "Do z-score scaling across samples"
  • "Map protein abundance values into 0 to 1"

When Not to Use

Do not use this skill for:

  • Count-model normalization such as CPM, TPM, TMM, or DESeq2 size factors
  • Batch correction or covariate adjustment
  • Single-cell preprocessing workflows
  • Matrices that contain missing, Inf, or NaN values unless they are cleaned first

When to Read External Files

When executing the analysis, run:

Rscript scripts/main.R --input_file <matrix.csv> --output_dir <output_dir> --method <log2|zscore|minmax>
Situation File to Read Purpose
Need to execute the workflow scripts/main.R CLI entry point
Need algorithm details references/algorithm.md Method definitions and assumptions
Encounter an error references/troubleshooting.md Standard error codes and fixes
Need examples or baseline run details references/cli-guide.md Ready-to-run commands and test record
Need dependency declarations DESCRIPTION Runtime package list

Usage

Rscript scripts/main.R \
  --input_file tests/data/expression_matrix.csv \
  --output_dir ./output \
  --method log2 \
  --pseudo_count 1 \
  --seed 42

Arguments

Short Long Type Default Description
-i --input_file file required Expression matrix in CSV or TSV format
-o --output_dir dir ./output Output directory
-m --method string log2 Normalization method: log2, zscore, minmax
-r --margin string column Apply normalization by row or column
-p --pseudo_count numeric 1 Added before log2 transformation
-c --center boolean true Center values for z-score
-s --scale_values boolean true Scale values for z-score
-t --timeout_seconds integer 0 Optional timeout; 0 disables it
-d --delimiter string auto Input delimiter: auto, csv, or tsv
--seed integer 42 Random seed
--verbose boolean true Print progress logs

Input Format

The first column must contain feature identifiers. Remaining columns must be finite numeric sample values.

Missing values and non-finite values such as NA, NaN, Inf, and -Inf are rejected.

feature,S1,S2,S3
TP53,10,20,30
EGFR,3,5,9

This skill accepts gene or protein expression matrices. It does not infer count-model normalization such as CPM, TPM, TMM, or DESeq2 size factors.

Output Files

If --output_dir already exists, result files with the same names are overwritten. When --verbose=true, the workflow prints a warning before writing into a non-empty output directory.

For single-sample inputs, feature_summary.csv reports per-feature standard deviations as 0 by design because each feature contributes one observed value.

File Description
table/normalized_matrix.csv Normalized matrix with the original feature column preserved
table/feature_summary.csv Per-feature min, max, mean, and SD before and after normalization
table/sample_summary.csv Per-sample min, max, mean, and SD before and after normalization
data/normalized_matrix.rds Serialized normalized matrix and run metadata
run_record.txt Structured execution record
output_manifest.txt Output file manifest
session_info.txt R session information

Methods

log2

Computes log2(x + pseudo_count) for each numeric value.

zscore

Centers and scales along the selected margin. margin=column standardizes each sample; margin=row standardizes each feature.

When center=false and scale_values=true, the workflow divides by standard deviation without subtracting the mean first.

minmax

Rescales values to [0, 1] along the selected margin. Constant vectors are returned as zeros to avoid division-by-zero errors.

Error Handling

Error Cause Solution
SKILL_FILE_NOT_FOUND Input file path is invalid Check the input path
SKILL_MISSING_COLUMNS Matrix has fewer than two columns Provide one feature column and at least one sample column
SKILL_INVALID_PARAMETER CLI value is unsupported or malformed, or the matrix contains non-finite values Review the argument table and inspect the matrix values
SKILL_TIMEOUT The run exceeded --timeout_seconds Increase the timeout or simplify the input size
SKILL_EMPTY_DATA No usable rows or columns remain Check the input matrix

Testing

Rscript scripts/main.R --help

Rscript tests/run_tests.R

Rscript tests/run_tests.R audit_output_check

Rscript tests/test_skill.R

Rscript tests/test_skill.R audit_output_check --skip-prepare

tests/run_tests.R executes bundled log2, zscore, and minmax runs and writes their outputs under tests/output/.

When you pass a relative directory name such as audit_output_check, the test runner writes outputs under tests/output/audit_output_check/.

Run tests/run_tests.R before tests/test_skill.R when you want to validate pre-generated outputs explicitly. The validation script can also prepare missing outputs on its own.

04 同仓库更多 Skills

mrsonord2240
mrsonord2240/openscience-specialists

bio-workflows-metabolomics-pipeline

Orchestrates the untargeted LC-MS metabolomics pipeline end-to-end (xcms 4.x feature extraction, QC/drift/normalization, 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/isotope-tracing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-xcms-preprocessing

Programmatic untargeted LC-MS feature extraction in R with the modern xcms 4.x MsExperiment/XcmsExperiment 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/grouping/alignment parameters. For drift correction and QC/CV filtering execution see metabolomics/normalization-qc; for metabolite identification see metabolomics/metabolite-annotation; for the MS-DIAL GUI alternative with MS2Dec deconvolution see metabolomics/msdial-preprocessing; for downstream statistics see metabolomics/statistical-analysis.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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/HCA for QC), permutation-validated PLS-DA/OPLS-DA (R2 vs Q2, double CV, VIP as heuristic), univariate testing (Welch/Mann-Whitney/ANOVA/LMM 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/drift correction see metabolomics/normalization-qc; for ML classifiers and selection-inside-CV leakage see machine-learning/biomarker-discovery and machine-learning/model-validation; for pathway interpretation see metabolomics/pathway-mapping; for design/power/multiplicity regime see experimental-design/multiple-testing.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-pathway-mapping

Maps metabolomics results to biological pathways via over-representation (ORA), metabolite-set enrichment (MSEA/QEA), mummichog/PSEA on raw m/z 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/background set. For annotation confidence levels feeding ORA see metabolomics/metabolite-annotation; for gene-set concepts see pathway-analysis/go-enrichment and pathway-analysis/gsea; for joint gene+metabolite pathways see multi-omics-integration/mofa-integration.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

bio-metabolomics-normalization-qc

Designs QC, corrects signal drift, removes batch effects, filters features, normalizes samples, and imputes missing values for untargeted LC-MS/GC-MS metabolomics, framing each step as a measurement model that can create or erase biological signal. Use when processing a peak/feature 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/xcms-preprocessing or metabolomics/msdial-preprocessing; transformation/scaling for modeling defers to metabolomics/statistical-analysis; cross-study design issues link to experimental-design/batch-design.

★ 2
mrsonord2240
mrsonord2240/openscience-specialists

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/DIA (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/xcms-preprocessing; for lipid annotation mode see metabolomics/lipidomics; for MSI-level confidence honesty see metabolomics/metabolite-annotation; for drift correction and QC see metabolomics/normalization-qc.

★ 2