# Tensor Decomposition Analysis Report

**Generated**: 2025-10-12 16:15:20

**Analysis ID**: 20251012_161520

---

## Quick Summary

This directory contains the complete results from a tensor decomposition analysis of gene expression data. This README explains all output files, provides interpretation guidelines, and recommends optimal parameters for your data.

---

## Analysis Summary

### Configuration
- **Method**: CP Decomposition
- **Rank**: 15
- **Tensor Shape**: (10223, 30, 4, 3)
  - Dimension 0 (Genes): 10223
  - Dimension 1 (Individuals): 30
  - Dimension 2 (Time Points): 4
  - Dimension 3 (Species): 3

### Performance Metrics
- **Reconstruction Error**: 0.135900
- **Explained Variance**: 0.9752 (97.52%)
- **Runtime**: 1m 44s
- **Status**: ✅ Analysis Complete

---

## Output Files Explained

This analysis generated the following files:

### Factor Matrices (CSV)

These files contain the decomposed factor matrices for each mode:

1. **`*_factor_genes.csv`**
   - **Size**: Genes × Components
   - **Content**: Gene loadings for each component
   - **Use**: Identify which genes contribute to each pattern
   - **Columns**: `component_0`, `component_1`, ..., `component_N`
   - **Rows**: Gene IDs (e.g., OG_00001, OG_00002, ...)
   
   **Interpretation**:
   - High positive values = gene strongly associated with component
   - Values near zero = gene not involved in this component
   - Can be used for marker gene identification
   - Export for GO enrichment analysis

2. **`*_factor_individuals.csv`**
   - **Size**: Individuals × Components
   - **Content**: Individual-specific expression patterns
   - **Use**: Identify individual variation and clustering
   - **Columns**: `component_0`, `component_1`, ..., `component_N`
   - **Rows**: Individual IDs (e.g., ACR-139, POR-216, ...)
   
   **Interpretation**:
   - Shows how each individual responds
   - Can reveal outliers or distinct groups
   - Use for QC or biological interpretation

3. **`*_factor_timepoints.csv`**
   - **Size**: Time Points × Components
   - **Content**: Temporal dynamics for each component
   - **Use**: Understand how patterns change over time
   - **Columns**: `component_0`, `component_1`, ..., `component_N`
   - **Rows**: Time point labels (e.g., 1, 2, 3, 4)
   
   **Interpretation**:
   - Positive values = pattern increases at that time
   - Negative values = pattern decreases at that time
   - Flat line = time-independent pattern
   - Rising/falling trends = developmental programs

4. **`*_factor_species.csv`**
   - **Size**: Species × Components
   - **Content**: Species-specific patterns
   - **Use**: Compare responses across species
   - **Columns**: `component_0`, `component_1`, ..., `component_N`
   - **Rows**: Species codes (e.g., ACR, POR, POC)
   
   **Interpretation**:
   - Similar values across species = conserved pattern
   - Different values = species-specific response
   - Use to identify adaptation or divergence

### Metadata (JSON)

**`*_metadata.json`**
- Contains dimension labels and analysis parameters
- Use to map indices back to original labels
- Includes gene names, individual IDs, time points, species names

**Fields**:
```json
{
  "genes": ["OG_00001", "OG_00002", ...],
  "individuals": ["ACR-139", "ACR-145", ...],
  "timepoints": [1, 2, 3, 4],
  "species": ["ACR", "POR", "POC"],
  "shape": [genes, individuals, timepoints, species]
}
```

### This README

**`ANALYSIS_README.md`** (this file)
- Complete documentation of the analysis
- Interpretation guidelines
- Parameter recommendations
- Troubleshooting tips

---

## How to Interpret Your Results

### Understanding Components

Your CP decomposition identified **15 components** that capture major patterns in the data.

Each component represents a distinct gene expression pattern characterized by:
1. **Which genes** are involved (gene factor)
2. **How individuals** respond (individual factor)
3. **When** it occurs (time factor)
4. **Where** it's active (species factor)

### Key Findings

- **Temporal Patterns**: Components 14, 13, 2 show the strongest time-dependent changes.
- **Conserved Patterns**: Components 0, 2, 3 are similar across species.
- **Species-Specific**: Components 1, 4, 6 show divergent patterns.

### Reading Factor Values

**Magnitude**:
- Values > 0.5 or < -0.5: Strong association
- Values between -0.5 and 0.5: Moderate association
- Values near 0: No association

**Sign**:
- Positive values: Co-activation or positive correlation
- Negative values: Anti-correlation or repression
- (Note: Sign is relative within each component)

### Typical Analysis Workflow

1. **Identify Components of Interest**
   - Look at time and species factors first
   - Find patterns matching your hypothesis

2. **Extract Marker Genes**
   - From gene factor, get genes with high loadings
   - Export gene lists for functional enrichment

3. **Validate Patterns**
   - Cross-reference with known biology
   - Plot individual genes to confirm

4. **Compare Conditions**
   - Use species factor to identify divergence
   - Use time factor for developmental stages

### Component Examples

**Example 1: Stress Response Component**
- Time factor: Increases at later time points
- Species factor: Strong in all species (conserved)
- Top genes: Heat shock proteins, chaperones

**Example 2: Development Component**
- Time factor: Progressive increase
- Species factor: Variable (species-specific development)
- Top genes: Developmental regulators, morphogens

**Example 3: Baseline Expression**
- Time factor: Flat (time-independent)
- Species factor: Similar across species
- Top genes: Housekeeping genes

---