Gene Protein Expression Matrix Normalization

> 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  --output_dir  --method 

| 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aipoch
• Source: aipoch/medical-research-skills
• License: MIT
• Homepage: https://aipoch.com/agent-skills

Install and usage instructions live in the source repository linked above.