working implementation of resolvi routine

Author: ctastad

README.md

@@ -147,21 +147,183 @@ You can provide custom comparison specifications for both differential abundance
 --scviva_comparisons /path/to/scviva_comparisons.json
 ```
 
-**JSON format example:**
+## scVIVA Conditions Setup
+
+The scVIVA workflow supports flexible condition specifications for niche-aware differential expression analysis. Conditions can be established through multiple approaches to enable sophisticated spatial comparisons.
+
+### Condition Types
+
+#### 1. **Cell Type Comparisons** (Simple)
+Compare different cell types without specific conditions:
+
+```json
+[
+  {
+    "name": "tcells_vs_bcells_niche",
+    "group1": "T cells",
+    "group2": "B cells"
+  }
+]
+```
+
+#### 2. **Treatment/Disease Conditions**
+Compare the same cell type across different treatments or disease states:
 
 ```json
 [
   {
-    "name": "tumor_vs_normal_tcells",
+    "name": "treated_vs_control_tcells",
     "group1": "T cells",
     "group2": "T cells",
+    "condition1": "treated",
+    "condition2": "control",
+    "condition_column": "treatment"
+  }
+]
+```
+
+#### 3. **Spatial Region Conditions**
+Compare cell types or conditions across different spatial regions:
+
+```json
+[
+  {
+    "name": "core_vs_periphery_macrophages",
+    "group1": "Macrophages",
+    "group2": "Macrophages",
+    "condition1": "tumor_core",
+    "condition2": "tumor_periphery",
+    "condition_column": "spatial_region"
+  }
+]
+```
+
+#### 4. **Sample-Based Conditions**
+Map specific samples to conditions when metadata isn't directly encoded:
+
+```json
+[
+  {
+    "name": "tumor_vs_normal_epithelial",
+    "group1": "Epithelial",
+    "group2": "Epithelial",
     "condition1": "tumor",
-    "condition2": "normal"
+    "condition2": "normal",
+    "condition_column": "tissue_type",
+    "samples_condition1": ["tumor_sample1", "tumor_sample2", "tumor_sample3"],
+    "samples_condition2": ["normal_sample1", "normal_sample2", "normal_sample3"]
   }
 ]
 ```
 
-Both parameters also support CSV format with equivalent column names.
+#### 5. **Cross-Condition Cell Type Comparisons**
+Compare different cell types across different conditions:
+
+```json
+[
+  {
+    "name": "tumor_tcells_vs_normal_bcells",
+    "group1": "T cells",
+    "group2": "B cells",
+    "condition1": "tumor",
+    "condition2": "normal",
+    "condition_column": "tissue_type"
+  }
+]
+```
+
+### Condition Establishment Methods
+
+The pipeline automatically detects and establishes conditions using the following priority order:
+
+1. **Explicit condition column**: Uses the column specified in ```condition_column```
+2. **Sample mapping**: Creates conditions from ```samples_condition1``` and ```samples_condition2``` lists
+3. **Spatial regions**: Uses ```spatial_region``` column if available
+4. **Common metadata columns**: Automatically detects ```treatment```, ```tissue_type```, etc.
+5. **Sample ID fallback**: Uses ```sample_id``` as conditions if no other method works
+
+### Required Data Preparation
+
+Ensure your AnnData objects contain the necessary metadata:
+
+#### Essential Columns
+- **Cell type predictions**: ```resolvi_predicted``` (automatically generated by ResolVI)
+- **Sample information**: ```sample_id``` (automatically added during preprocessing)
+
+#### Optional Condition Columns
+- ```condition```: General condition labels
+- ```treatment```: Treatment/control labels  
+- ```tissue_type```: Tissue or disease state labels
+- ```spatial_region```: Spatial region annotations
+- ```timepoint```: Temporal conditions
+- Custom condition columns as specified in your comparisons
+
+### File Formats
+
+#### JSON Format (Recommended)
+```json
+[
+  {
+    "name": "comparison_name",
+    "group1": "Cell_Type_1",
+    "group2": "Cell_Type_2", 
+    "condition1": "condition_A",
+    "condition2": "condition_B",
+    "condition_column": "metadata_column",
+    "samples_condition1": ["sample1", "sample2"],
+    "samples_condition2": ["sample3", "sample4"]
+  }
+]
+```
+
+#### CSV Format
+```csv
+name,group1,group2,condition1,condition2,condition_column
+tcells_vs_bcells,T cells,B cells,,,
+treated_vs_control_tcells,T cells,T cells,treated,control,treatment
+```
+
+### Usage Examples
+
+#### Basic cell type comparison:
+```bash
+nextflow run nf-core/resolvinf \
+  --input samplesheet.csv \
+  --scviva_comparisons simple_comparisons.json \
+  --outdir results
+```
+
+#### Complex condition-based analysis:
+```bash
+nextflow run nf-core/resolvinf \
+  --input samplesheet.csv \
+  --scviva_comparisons complex_comparisons.json \
+  --annotation_label cell_type \
+  --outdir results
+```
+
+### Best Practices
+
+1. **Minimum cell numbers**: Ensure each comparison group has ≥10 cells for reliable DE analysis
+2. **Balanced comparisons**: Try to have reasonably balanced group sizes when possible
+3. **Clear naming**: Use descriptive comparison names for easier interpretation
+4. **Condition validation**: Verify that your condition columns exist in the data
+5. **Sample mapping**: When using sample mapping, ensure sample IDs match exactly
+
+### Troubleshooting
+
+#### Common Issues:
+- **"Cannot establish conditions"**: Check that specified condition columns exist in your data
+- **"Insufficient cells"**: Reduce the number of comparisons or combine similar conditions
+- **"Sample not found"**: Verify sample IDs in ```samples_condition1/2``` match your data exactly
+
+#### Debug Information:
+The pipeline logs detailed information about:
+- Available metadata columns
+- Condition establishment methods used
+- Cell counts for each comparison group
+- Success/failure status for each comparison
+
 
 ## Key Parameters