Humanize documentation tone and remove AI-style phrasing

Rewrite prose in READMEs, tutorials, and supporting docs to read more
naturally and remove AI-style formatting (em dashes, decorative emoji).
Code, commands, workflows, and diagrams are unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: challagandla

README.md

@@ -1,15 +1,15 @@
-# 🧬 scRNA-seq Analysis Pipeline
+# scRNA-seq Analysis Pipeline
 
-[![CI](https://github.com/your-org/scrna-pipeline/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/scrna-pipeline/actions)
+[![CI](https://github.com/challagandla/oracle-scrna-seq/actions/workflows/ci.yml/badge.svg)](https://github.com/challagandla/oracle-scrna-seq/actions)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Snakemake](https://img.shields.io/badge/snakemake-≥8.0-green.svg)](https://snakemake.github.io)
+[![Snakemake](https://img.shields.io/badge/snakemake-%3E%3D8.0-green.svg)](https://snakemake.github.io)
 [![Python](https://img.shields.io/badge/python-3.11-blue.svg)](https://www.python.org)
 
-End-to-end single-cell RNA-seq analysis pipeline following **[scverse best practices](https://www.sc-best-practices.org)**. Reproducible, containerised, and fully automated with Snakemake.
+A Snakemake workflow for single-cell RNA-seq analysis following [scverse best practices](https://www.sc-best-practices.org). It covers QC, doublet detection, normalization, batch correction, clustering, marker genes, annotation, and optional trajectory analysis.
 
 ---
 
-## 📋 Table of Contents
+## Table of Contents
 
 - [Pipeline overview](#pipeline-overview)
 - [Quick start](#quick-start)
@@ -85,7 +85,7 @@ open results/report.html   # or xdg-open on Linux
 | Tool | Version | Install |
 |------|---------|---------|
 | conda / mamba | any | [miniforge](https://github.com/conda-forge/miniforge) |
-| Snakemake | ≥ 8.0 | included in `envs/scrna.yaml` |
+| Snakemake | >= 8.0 | included in `envs/scrna.yaml` |
 | Python | 3.11 | included |
 | R + scDblFinder | optional | `envs/r_env.yaml` |
 
@@ -128,9 +128,9 @@ A tab-separated file with one row per sample:
 
 | Column | Required | Description |
 |--------|----------|-------------|
-| `sample` | ✅ | Unique sample identifier |
-| `path` | ✅ | Path to `.h5ad`, `.h5`, or 10X MEX directory |
-| `batch` | ✅ | Batch label (use same value if single batch) |
+| `sample` | yes | Unique sample identifier |
+| `path` | yes | Path to `.h5ad`, `.h5`, or 10X MEX directory |
+| `batch` | yes | Batch label (use same value if single batch) |
 | `condition` | optional | Experimental condition for DE |
 | `description` | optional | Free-text description |
 
@@ -216,16 +216,16 @@ snakemake --use-conda --cores 8 \
 
 ## Step-by-Step Guide
 
-### Step 00 — Quality Control
+### Step 00 - Quality Control
 
 **Purpose**: Remove low-quality cells (empty droplets, dying cells, debris) and lowly-expressed genes.
 
 **Key outputs**:
-- `figures/01_knee_plot.png` — Barcode-rank plot; the "knee" separates real cells from empty droplets
-- `figures/02_qc_violin_before.png` — Distribution of all QC metrics pre-filtering
-- `figures/03_qc_histograms.png` — Histograms with MAD-based threshold lines overlaid
-- `figures/04_counts_vs_genes.png` — Scatter plot coloured by MT%; dying cells cluster bottom-left with high MT%
-- `qc_stats.json` — Machine-readable before/after statistics
+- `figures/01_knee_plot.png` - Barcode-rank plot; the "knee" separates real cells from empty droplets
+- `figures/02_qc_violin_before.png` - Distribution of all QC metrics pre-filtering
+- `figures/03_qc_histograms.png` - Histograms with MAD-based threshold lines overlaid
+- `figures/04_counts_vs_genes.png` - Scatter plot coloured by MT%; dying cells cluster bottom-left with high MT%
+- `qc_stats.json` - Machine-readable before/after statistics
 
 **Algorithm** (MAD = Median Absolute Deviation):
 ```
@@ -247,9 +247,9 @@ qc:
 
 ---
 
-### Step 01 — Doublet Detection
+### Step 01 - Doublet Detection
 
-**Purpose**: Identify and remove doublets — droplets that captured 2+ cells. Doublets appear as fake "intermediate" cell types and inflate cluster counts.
+**Purpose**: Identify and remove doublets - droplets that captured 2+ cells. Doublets appear as fake "intermediate" cell types and inflate cluster counts.
 
 **Methods**:
 
@@ -264,15 +264,15 @@ qc:
 
 ---
 
-### Step 02 — Normalization
+### Step 02 - Normalization
 
 **Purpose**: Remove technical variation in library size (sequencing depth) so cells are comparable.
 
 **Methods**:
 
 | Method | Steps | Best for |
 |--------|-------|----------|
-| `log` (default) | Divide by library size → ×10,000 → log1p | Most datasets |
+| `log` (default) | Divide by library size -> x10,000 -> log1p | Most datasets |
 | `scran` | Pooling-based size factors | Low library size variation, many zeros |
 
 Raw integer counts are always preserved in `adata.layers["counts"]` for:
@@ -284,7 +284,7 @@ Raw integer counts are always preserved in `adata.layers["counts"]` for:
 
 ---
 
-### Step 03 — HVG Selection & PCA
+### Step 03 - HVG Selection & PCA
 
 **Purpose**: Select informative genes and compress expression space.
 
@@ -295,66 +295,66 @@ Raw integer counts are always preserved in `adata.layers["counts"]` for:
 - Non-HVGs are retained in the object but excluded from PCA
 
 **Scaling**: HVGs are zero-mean, unit-variance scaled (capped at 10) before PCA.
-> Do NOT use scaled data for visualization or DE. Only for PCA.
+> Do not use scaled data for visualization or DE. Only for PCA.
 
 **Choosing n_pcs** (from elbow plot):
 - Look for where variance ratio stops decreasing sharply ("elbow")
 - Rule of thumb: use PCs explaining 80% cumulative variance
-- Typical range: 20–50 PCs
+- Typical range: 20-50 PCs
 
 ---
 
-### Step 04 — Batch Correction
+### Step 04 - Batch Correction
 
 **Purpose**: Remove technical batch effects while preserving biological variation.
 
 | Method | Pros | Cons |
 |--------|------|------|
 | Harmony | Fast (seconds), no retraining, works well | May over-integrate |
-| scVI | Most powerful, probabilistic | Slow (minutes–hours), needs counts |
+| scVI | Most flexible, probabilistic | Slow (minutes-hours), needs counts |
 | ComBat | Simple, interpretable | Assumes linear effects only |
 
-> **Skip if you have a single sample.** Over-integration is a real risk — if batches are already well-mixed, skip this step.
+> **Skip if you have a single sample.** Over-integration is a real risk - if batches are already well-mixed, skip this step.
 
 **Diagnostic**: Compare UMAP coloured by batch before vs after correction. After correction, cells should be interleaved without losing biological clusters.
 
 ---
 
-### Step 05 — Neighbor Graph & UMAP
+### Step 05 - Neighbor Graph & UMAP
 
 **Purpose**: Embed cells in 2D for visualization.
 
 **kNN graph**: Finds `n_neighbors` nearest cells in PCA space. This graph is the foundation for both UMAP and Leiden clustering.
 
 **UMAP parameters**:
-- `n_neighbors` (15): higher → more global structure; lower → more local
-- `min_dist` (0.3): lower → tighter clusters; higher → more spread
+- `n_neighbors` (15): higher -> more global structure; lower -> more local
+- `min_dist` (0.3): lower -> tighter clusters; higher -> more spread
 
-> ⚠️ **UMAP is for visualization only.** Distances in UMAP space are not biologically meaningful. Two clusters that look close may not be transcriptionally similar.
+> Note: **UMAP is for visualization only.** Distances in UMAP space are not biologically meaningful. Two clusters that look close may not be transcriptionally similar.
 
 ---
 
-### Step 06 — Leiden Clustering
+### Step 06 - Leiden Clustering
 
 **Purpose**: Group cells into discrete clusters.
 
 The pipeline runs Leiden at 6 resolutions and selects the best by **silhouette score** (measures how well-separated clusters are in PCA space).
 
 > **Resolution guidance**:
-> - Start with 0.4–0.8 for most datasets
-> - More cells → can use higher resolution
+> - Start with 0.4-0.8 for most datasets
+> - More cells -> can use higher resolution
 > - Check: do clusters make biological sense? Is the silhouette curve clearly peaked?
 
 Inspect `figures/01_umap_all_resolutions.png` to see how resolution affects cluster granularity.
 
 ---
 
-### Step 07 — Marker Genes & DE
+### Step 07 - Marker Genes & DE
 
 **A) Cluster markers** (Wilcoxon one-vs-rest):
-- Non-parametric, robust to zero-inflation
+- Non-parametric, stable with zero-inflation
 - Recommended by scverse for scRNA-seq
-- Results filtered by log2FC ≥ 0.25 and fraction expressing ≥ 10%
+- Results filtered by log2FC >= 0.25 and fraction expressing >= 10%
 
 **B) Condition DE** (pseudobulk, requires biological replicates):
 ```yaml
@@ -363,13 +363,13 @@ markers:
   group1: "control"
   group2: "treated"
 ```
-Pseudobulk aggregates counts per sample, then tests with DESeq2 — the only statistically valid approach when you have replicates.
+Pseudobulk aggregates counts per sample, then tests with DESeq2 - the only statistically valid approach when you have replicates.
 
-> ❌ **Do not run per-cell DE between conditions** (inflated degrees of freedom). Always use pseudobulk.
+> **Do not run per-cell DE between conditions** (inflated degrees of freedom). Always use pseudobulk.
 
 ---
 
-### Step 08 — Cell Type Annotation
+### Step 08 - Cell Type Annotation
 
 Three complementary approaches:
 
@@ -386,11 +386,11 @@ Three complementary approaches:
    ```
    Then set `manual_tsv: "config/my_annotations.tsv"`.
 
-**Composition plot**: `figures/06_composition_barplot.png` shows cell type proportions per sample — useful for identifying disease-associated compositional shifts.
+**Composition plot**: `figures/06_composition_barplot.png` shows cell type proportions per sample - useful for identifying disease-associated compositional shifts.
 
 ---
 
-### Step 09 — Trajectory (optional)
+### Step 09 - Trajectory (optional)
 
 **PAGA** (any dataset):
 ```yaml
@@ -524,7 +524,7 @@ Please run tests before submitting: `pytest tests/ -v`
 
 If you use this pipeline, please cite the underlying tools:
 
-- **scverse**: Virshup et al. (2023) *Nature Biotechnology* — anndata, scanpy
+- **scverse**: Virshup et al. (2023) *Nature Biotechnology* - anndata, scanpy
 - **Leiden algorithm**: Traag et al. (2019) *Scientific Reports*
 - **Harmony**: Korsunsky et al. (2019) *Nature Methods*
 - **scrublet**: Wolock et al. (2019) *Cell Systems*
@@ -539,4 +539,4 @@ If you use this pipeline, please cite the underlying tools:
 
 ## License
 
-MIT — see [LICENSE](LICENSE)
+MIT - see [LICENSE](LICENSE)

docs/github_push.md

@@ -39,9 +39,9 @@ git remote add origin git@github.com:<your-username>/scrna-pipeline.git
 git push -u origin main
 ```
 
-## After adding GitHub remote — update README badge
+## After adding GitHub remote - update README badge
 
-Edit `README.md` line 3 and replace `your-org` with your GitHub username:
+The README badge already points at `challagandla/oracle-scrna-seq`. If you fork the repo, update the badge owner/repo path after pushing:
 ```
 [![CI](https://github.com/<your-username>/scrna-pipeline/actions/workflows/ci.yml/badge.svg)]
 ```

docs/parameters.md

@@ -19,8 +19,8 @@ All parameters are set in `config/config.yaml`.
 | `mad_counts` | `5` | MADs for total counts (log-scale). Lower = stricter. |
 | `mad_genes` | `5` | MADs for gene counts (log-scale). |
 | `mad_mt` | `3` | MADs for MT% (raw). More stringent than counts. |
-| `mt_hard` | `8` | Hard MT% ceiling. Raise to 10–15 for neurons. |
-| `min_cells` | `20` | Gene must appear in ≥ N cells. |
+| `mt_hard` | `8` | Hard MT% ceiling. Raise to 10-15 for neurons. |
+| `min_cells` | `20` | Gene must appear in >= N cells. |
 | `min_counts` | `500` | Hard floor for total counts per cell. |
 | `min_genes` | `200` | Hard floor for detected genes per cell. |
 
@@ -42,7 +42,7 @@ All parameters are set in `config/config.yaml`.
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `n_top_genes` | `2000` | HVGs to select. 1500–3000 is typical. |
+| `n_top_genes` | `2000` | HVGs to select. 1500-3000 is typical. |
 | `flavor` | `seurat_v3` | HVG method: `seurat_v3`, `seurat`, `cell_ranger`. |
 | `n_pcs` | `50` | PCs to compute. |
 | `n_pcs_use` | `30` | PCs to use downstream. See elbow plot. |
@@ -59,9 +59,9 @@ All parameters are set in `config/config.yaml`.
 
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `n_neighbors` | `15` | kNN graph neighbors. 10–50. |
+| `n_neighbors` | `15` | kNN graph neighbors. 10-50. |
 | `metric` | `euclidean` | Distance metric for kNN. |
-| `min_dist` | `0.3` | UMAP: controls cluster tightness. 0.1–0.8. |
+| `min_dist` | `0.3` | UMAP: controls cluster tightness. 0.1-0.8. |
 | `spread` | `1.0` | UMAP: scale of embedded space. |
 | `use_rep` | `""` | Auto-set from batch method. Override if needed. |
 
@@ -91,7 +91,7 @@ All parameters are set in `config/config.yaml`.
 | `markers_json` | `""` | Path to `{cell_type: [gene1,...]}` JSON. `""` = built-in PBMC. |
 | `celltypist` | `false` | Run CellTypist automated classification. |
 | `celltypist_model` | `Immune_All_Low.pkl` | CellTypist model name. See [models](https://www.celltypist.org/models). |
-| `manual_tsv` | `""` | Path to cluster→cell_type TSV. `""` = skip. |
+| `manual_tsv` | `""` | Path to cluster->cell_type TSV. `""` = skip. |
 
 ## trajectory