--- name: gene-protein-expression-matrix-normalization 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. license: MIT author: AIPOCH --- > **Source**: [https://github.com/aipoch/medical-research-skills](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: ```bash 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 ```bash 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. ```csv 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 ```bash 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 attribution: aipoch Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/awesome-med-research-skills/Data%20Analysis/gene-protein-expression-matrix-normalization/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2026 AIpoch Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: aipoch Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/awesome-med-research-skills/Data%20Analysis/gene-protein-expression-matrix-normalization/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Education & Research Roles: Business Intelligence Analyst, Data Scientist, Researcher Specialties: API Tools: R Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 3bbd38a0c1a3f2d8e738fdda3359e1d2fba4f092afd0f577c6098f33fa0ccf30