--- name: pca-dimensionality-reduction-89b118a51852 description: Use when performing PCA principal component dimensionality reduction on tabular numeric data. Supports command-line parameter input, automatic numeric feature selection, parameter validation, result directory creation, and CSV or TXT format result export. license: MIT author: AIPOCH --- > **Source**: [https://github.com/aipoch/medical-research-skills](https://github.com/aipoch/medical-research-skills) # PCA Dimensionality Reduction Analysis Use this skill to run principal component analysis on a tabular dataset and export explained variance, sample scores, feature loadings, and diagnostic figures. ## Use This Skill When - You need to reduce multiple numeric variables into a smaller set of principal components. - You need a command-line PCA workflow with parameter validation. - You need standardized output files for downstream analysis. ## Primary Command ```bash Rscript scripts/main.R \ --data_file \ --output_dir \ --feature_columns ``` ## Prerequisites - `Rscript` is available in the shell. - Required R packages: `optparse`, `data.table`. - Install missing packages with `Rscript -e 'install.packages(c("optparse", "data.table"), repos="https://cloud.r-project.org")'`. ## Core Arguments | Argument | Required | Description | |----------|----------|-------------| | `--data_file` | Yes | Input data file in CSV, TXT, or TSV format | | `--output_dir` | No | Output directory, default `./PCA_Results` | | `--feature_columns` | No | Comma-separated numeric feature columns. Default uses all numeric columns except ID/group columns | | `--sample_id_column` | No | Optional sample ID column. If omitted and the first column is non-numeric with unique values, it is used automatically | | `--group_column` | No | Optional grouping column to carry into score output and score plot | | `--n_components` | No | Maximum number of principal components to export, default `5` | | `--center_data` | No | `true` or `false`, default `true` | | `--scale_data` | No | `true` or `false`, default `true` | | `--top_loadings` | No | Number of top absolute loadings to export per component, default `10` | | `--output_format` | No | `csv` or `txt`, default `csv` | | `--output_prefix` | No | Output filename prefix, default `pca` | ## Input Requirements - The input file must contain at least 2 usable numeric feature columns. - PCA is run on rows as samples and columns as features. - Missing or non-finite values in selected feature columns are removed row-wise before analysis. - At least 2 complete samples must remain after filtering. - Selected feature columns must have non-zero variance after filtering. Example input: ```csv SampleID,Group,GeneA,GeneB,GeneC,GeneD S01,Control,2.1,1.9,8.2,4.3 S02,Control,2.4,2.2,8.0,4.6 S03,Treated,6.1,5.7,2.8,8.1 ``` ## Minimal Workflow 1. Confirm the input file exists and identify the numeric feature columns for PCA. 2. Run `scripts/main.R` with the requested output directory and optional feature, ID, or group columns. 3. Check the output directory for result files under `table/`, `data/`, and `figure/`. If you omit `--data_file`, the script exits with `SKILL_MISSING_INPUT`. ## Outputs Expected output structure: ```text / ├── table/ ├── figure/ └── data/ ``` Primary result files: - `table/_summary.csv` - `table/_scores.csv` - `table/_loadings.csv` - `table/_top_loadings.csv` Figure files: - `figure/_scree_plot.png` - `figure/_score_plot.png` Key fields include: - `component` - `standard_deviation` - `variance` - `proportion_variance` - `cumulative_variance` - `sample_id` - `feature` - `loading` ## Interpretation Guide - Use `proportion_variance` and `cumulative_variance` to decide how many components to retain. - Use the score table to inspect sample separation in PC space. - Use the loading tables to identify which original variables drive each component. ## Read These Files When Needed | Need | File | |------|------| | PCA method details and interpretation | `references/algorithm.md` | | More CLI examples | `references/cli-guide.md` | | Error diagnosis | `references/troubleshooting.md` | | Main execution entry point | `scripts/main.R` | | Sample test data | `tests/data/` | ## Quick Examples Basic PCA with explicit feature columns: ```bash Rscript scripts/main.R \ --data_file tests/data/sample_pca_1.csv \ --sample_id_column SampleID \ --group_column Group \ --feature_columns GeneA,GeneB,GeneC,GeneD,GeneE \ --output_dir tests/output_basic ``` Auto-detect all numeric columns: ```bash Rscript scripts/main.R \ --data_file tests/data/sample_pca_2.csv \ --n_components 3 \ --output_dir tests/output_numeric_only ``` Disable scaling: ```bash Rscript scripts/main.R \ --data_file tests/data/sample_pca_1.csv \ --sample_id_column SampleID \ --group_column Group \ --scale_data false \ --output_dir tests/output_unscaled ``` ## Validation ```bash Rscript scripts/main.R --help ``` ```bash Rscript scripts/main.R \ --data_file tests/data/sample_pca_1.csv \ --sample_id_column SampleID \ --group_column Group \ --feature_columns GeneA,GeneB,GeneC,GeneD,GeneE \ --output_dir tests/validation_output ``` After running analysis, verify that `tests/validation_output/table/pca_summary.csv` exists. ## Common Errors - `SKILL_FILE_NOT_FOUND`: Input file path is wrong or inaccessible. - `SKILL_MISSING_COLUMNS`: A requested feature, sample ID, or group column is missing. - `SKILL_INVALID_DATA`: Input data is malformed or unsuitable for PCA. - `SKILL_INVALID_PARAMETER`: An argument value is invalid. - `SKILL_INSUFFICIENT_DATA`: Too few complete samples or features remain for PCA. - `SKILL_DEPENDENCY_MISSING`: A required R package such as `optparse` or `data.table` is unavailable. If the issue is not obvious, read `references/troubleshooting.md`. --- Source attribution: aipoch Original project: https://github.com/aipoch/medical-research-skills/blob/686e09dfdb45d9fa1a08664f06bb93769b3c9d91/awesome-med-research-skills/Data%20Analysis/pca-dimensionality-reduction/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/pca-dimensionality-reduction/SKILL.md Attribution basis: Source repository record Fields of work: Data & Analytics, Development & Engineering Roles: Data Analyst, Data Scientist, ML / AI Engineer Specialties: API Tools: Rscript Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: f1af293ba26cd68ffdfcfda3d07a81b56a57fbe584cf72be3bb8fae4f40a0eec