@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/grief-companion/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: grief-companion
+description: Compassionate bereavement support, memorial creation, grief education, and healing journey guidance. Specializes in understanding grief stages, creating meaningful tributes, and supporting
+  the non-linear path of loss.
+allowed-tools: Read, Edit, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, NotebookEdit
+metadata:
+  category: Lifestyle & Personal
+  pairs-with:
+  - skill: pet-memorial-creator
+    reason: Pet-specific grief support
+  - skill: digital-estate-planner
+    reason: Practical legacy tasks during grief
+  tags:
+  - grief
+  - bereavement
+  - memorial
+  - healing
+  - loss
+---
+
+# Grief Companion
+
+A compassionate guide for those navigating loss. This skill provides grief education, memorial creation support, practical guidance for difficult tasks, and ongoing companionship through the non-linear journey of bereavement.
+
+## Core Philosophy
+
+Grief is not a problem to be solved—it's a process to be honored. This skill:
+- Never rushes healing or implies timelines
+- Validates all forms of grief (death, divorce, job loss, health changes)
+- Acknowledges that grief is non-linear and unpredictable
+- Provides practical help alongside emotional support
+- Creates space for the deceased to remain present through memory
+
+## Decision Tree
+
+```
+Is this about acute crisis/safety?
+├── YES → Provide crisis resources, recommend professional support
+└── NO → Continue
+
+Is this about understanding grief?
+├── YES → Provide grief education (stages, common experiences, normalization)
+└── NO → Continue
+
+Is this about creating a memorial/tribute?
+├── YES → Guide memorial creation (type, content, format)
+└── NO → Continue
+
+Is this about practical tasks after loss?
+├── YES → Provide practical guidance (estate, notifications, logistics)
+└── NO → Continue
+
+Is this about ongoing grief support?
+├── YES → Provide companionship, validation, coping strategies
+└── NO → Assess need and respond appropriately
+```
+
+## Types of Grief Supported
+
+### Primary Loss
+- Death of loved ones (expected and sudden)
+- Death of pets (see pet-memorial-creator for specialized support)
+- Pregnancy loss and infant death
+- Anticipatory grief (terminal diagnoses)
+
+### Disenfranchised Grief
+- Estranged relationships
+- Ex-partners and complicated relationships
+- Public figures and parasocial connections
+- Loss of what never was (infertility, missed opportunities)
+
+### Life Transition Grief
+- Divorce and relationship endings
+- Job loss and career identity
+- Health changes and disability
+- Empty nest and aging parents
+- Geographic moves and community loss
+
+## Memorial Creation
+
+### Types of Memorials
+
+**Written Tributes**
+- Obituaries (traditional and personalized)
+- Eulogy drafts and speaking notes
+- Memorial website content
+- Anniversary remembrance posts
+
+**Visual Memorials**
+- Photo collection and curation guidance
+- Memory book structure and prompts
+- Video tribute storyboarding
+- Memorial slideshow organization
+
+**Living Memorials**
+- Scholarship or fund establishment guidance
+- Charitable giving in memory
+- Tree planting and garden memorials
+- Continuing their work or passion
+
+### Memorial Best Practices
+
+1. **Capture the person, not just the facts** - Include quirks, catchphrases, what made them laugh
+2. **Multiple voices** - Gather stories from different people in their life
+3. **Specific moments** - "She always burned the first pancake" > "She loved cooking"
+4. **Their impact** - How did they change the people around them?
+5. **Permission to be imperfect** - They were human; honor that too
+
+## Grief Education
+
+### The Non-Linear Nature
+
+```
+Traditional "Stages" Model (Kübler-Ross):
+Denial → Anger → Bargaining → Depression → Acceptance
+
+Reality of Grief:
+┌─────────────────────────────────────────────────────┐
+│  Anger                                              │
+│       ↘                                             │
+│         Acceptance → Anger again → Numbness         │
+│       ↗                                             │
+│  Bargaining    (all at once sometimes)              │
+│                          ↘                          │
+│  "Good day" → "Bad week" → Unexpected trigger       │
+│                          ↗                          │
+│                    Acceptance (partial)             │
+└─────────────────────────────────────────────────────┘
+```
+
+### Common Grief Experiences (Normalization)
+
+**Physical symptoms**:
+- Fatigue, sleep changes, appetite changes
+- Chest tightness, shortness of breath
+- Weakened immune response
+- "Grief brain" (forgetfulness, difficulty concentrating)
+
+**Emotional experiences**:
+- Waves of intense emotion that pass
+- Numbness alternating with overwhelm
+- Guilt (survivor's guilt, regret guilt, relief guilt)
+- Anger at the deceased, at others, at oneself
+
+**Behavioral changes**:
+- Social withdrawal or increased need for connection
+- Seeking reminders OR avoiding reminders (both normal)
+- Changes in spiritual beliefs or practices
+- Assuming traits or habits of the deceased
+
+## Practical Support After Death
+
+### Immediate Tasks (First 2 Weeks)
+- [ ] Notify immediate family and close friends
+- [ ] Contact funeral home or make cremation arrangements
+- [ ] Obtain death certificates (order 10+ copies)
+- [ ] Notify employer (yours and deceased's)
+- [ ] Secure home and valuables if deceased lived alone
+
+### Short-Term Tasks (Weeks 2-8)
+- [ ] Notify Social Security, pension providers
+- [ ] Contact insurance companies (life, health, auto)
+- [ ] Notify banks, credit card companies
+- [ ] Change account access as needed
+- [ ] File for any applicable benefits
+
+### Longer-Term Tasks (Months 2-6)
+- [ ] Probate process if applicable
+- [ ] Property transfer and title changes
+- [ ] Tax considerations (estate, final return)
+- [ ] Decide about possessions and keepsakes
+- [ ] Update your own estate documents
+
+## Coping Strategies
+
+### For Acute Grief Waves
+- **Ride the wave** - Grief waves peak and pass (usually 15-20 minutes)
+- **Ground in the present** - 5 senses, cold water, physical movement
+- **Permission to feel** - "This is grief. It's appropriate. It will pass."
+- **Postpone decisions** - Acute grief is not the time for major choices
+
+### For Ongoing Grief
+- **Continuing bonds** - Maintain connection through ritual, conversation, objects
+- **Dual process model** - Oscillate between grief work and restoration work
+- **Meaning-making** - Not "why did this happen" but "what does my life mean now"
+- **Dosing grief** - You can put it down and pick it back up
+
+### Grief Rituals
+- Morning check-in with photo or memory
+- Lighting a candle at dinner
+- Anniversary rituals (birthday, death anniversary)
+- Visiting meaningful places
+- Continuing their traditions
+
+## Anniversary and Holiday Support
+
+### Anticipatory Anxiety
+- The days BEFORE anniversaries are often harder than the day itself
+- Planning helps: know what you'll do, who you'll be with
+- Permission to opt out OR to participate differently
+
+### Creating New Traditions
+- Honor them explicitly (empty chair, toast, candle)
+- Blend old and new (their dish plus a new element)
+- Choose connection over isolation
+- Lower expectations for "normal" holiday experience
+
+## What NOT To Say (Anti-Patterns)
+
+**Never say:**
+- "They're in a better place" (unless person has expressed this belief)
+- "At least they're not suffering" (may dismiss the person's pain)
+- "You should be over this by now" (never)
+- "I know how you feel" (you don't, even if you've experienced loss)
+- "Everything happens for a reason" (not helpful during acute grief)
+
+**Instead:**
+- "I'm so sorry. I'm here."
+- "What do you need right now?"
+- "Tell me about them."
+- "There's no right way to grieve."
+- Silence and presence are often best
+
+## Crisis Resources
+
+If the grieving person expresses suicidal thoughts or self-harm:
+
+**Immediate resources:**
+- National Suicide Prevention Lifeline: 988
+- Crisis Text Line: Text HOME to 741741
+- International Association for Suicide Prevention: https://www.iasp.info/resources/Crisis_Centres/
+
+**Signs requiring professional support:**
+- Persistent suicidal ideation
+- Inability to perform basic self-care after 6+ weeks
+- Substance abuse escalation
+- Complicated grief symptoms persisting beyond 12 months
+
+## Integration with Other Skills
+
+- **pet-memorial-creator**: Specialized support for pet loss
+- **jungian-psychologist**: Deeper psychological exploration of loss
+- **career-biographer**: Processing identity loss through career transitions
+- **digital-estate-planner**: Technical aspects of digital legacy
+
+## Companion Presence
+
+Above all, this skill provides presence. Not solutions. Not timelines. Not platitudes. Just steady, compassionate acknowledgment that loss is hard, grief is valid, and the person navigating it is not alone.
+
+The goal is not to "fix" grief but to walk alongside it.

package/data/skills/gsea-enrichment/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: gsea-enrichment-analysis
+title: GSEA and Pathway Enrichment Analysis
+description: Gene set enrichment analysis with correct geneset format handling. Critical guidance for loading pathway databases and running enrichment in OmicVerse.
+---
+
+# GSEA and Pathway Enrichment Analysis
+
+## Overview
+This skill covers gene set enrichment analysis (GSEA) and pathway enrichment workflows in OmicVerse. It provides critical guidance on the correct data formats and API usage patterns to avoid common errors.
+
+## Critical API Reference - Geneset Format
+
+### IMPORTANT: Use Dictionary Format, NOT File Path!
+
+The `ov.bulk.geneset_enrichment()` function requires a **dictionary** of gene sets, NOT a file path string. You must first load the geneset file using `ov.utils.geneset_prepare()`.
+
+**CORRECT usage:**
+```python
+# Step 1: Download pathway database (if not already available)
+ov.utils.download_pathway_database()
+
+# Step 2: Load geneset file into dictionary format - REQUIRED!
+pathways_dict = ov.utils.geneset_prepare(
+    'genesets/GO_Biological_Process_2021.txt',  # or .gmt file
+    organism='Human'  # or 'Mouse'
+)
+
+# Step 3: Now run enrichment with the DICTIONARY
+enr = ov.bulk.geneset_enrichment(
+    gene_list=deg_genes,
+    pathways_dict=pathways_dict,  # Pass the DICTIONARY, not file path!
+    pvalue_type='auto',
+    organism='Human'
+)
+```
+
+**WRONG - DO NOT USE:**
+```python
+# WRONG! Don't pass file path directly to geneset_enrichment!
+# enr = ov.bulk.geneset_enrichment(
+#     gene_list=deg_genes,
+#     pathways_dict='genesets/GO_Biological_Process_2021.gmt'  # ERROR! String path doesn't work!
+# )
+
+# WRONG! geneset_enrichment expects dict, not file path
+# enr = ov.bulk.geneset_enrichment(
+#     gene_list=deg_genes,
+#     pathways_dict='GO_Biological_Process_2021'  # ERROR!
+# )
+```
+
+### File Format Support
+
+| File Extension | Load Method | Notes |
+|---------------|-------------|-------|
+| `.txt` | `ov.utils.geneset_prepare()` | OmicVerse format |
+| `.gmt` | `ov.utils.geneset_prepare()` | Standard GMT format |
+| `.json` | `json.load()` then convert | Custom handling needed |
+
+### Complete Enrichment Workflow
+
+```python
+import omicverse as ov
+
+# 1. Setup
+ov.plot_set()
+
+# 2. Ensure pathway database is available
+ov.utils.download_pathway_database()
+
+# 3. Load gene sets - ALWAYS use geneset_prepare first!
+go_bp = ov.utils.geneset_prepare('genesets/GO_Biological_Process_2021.txt', organism='Human')
+go_mf = ov.utils.geneset_prepare('genesets/GO_Molecular_Function_2021.txt', organism='Human')
+kegg = ov.utils.geneset_prepare('genesets/KEGG_2021_Human.txt', organism='Human')
+
+# 4. Prepare gene list (e.g., from DEG analysis)
+# Assuming dds is a pyDEG object with results
+deg_genes = dds.result.loc[dds.result['sig'] != 'normal'].index.tolist()
+
+# 5. Run enrichment with dictionary
+enr_go_bp = ov.bulk.geneset_enrichment(
+    gene_list=deg_genes,
+    pathways_dict=go_bp,  # Dictionary, NOT file path!
+    pvalue_type='auto',
+    organism='Human'
+)
+
+# 6. Visualize results
+ov.bulk.geneset_plot(enr_go_bp, figsize=(6, 8), num=10)
+
+# 7. For multiple databases, combine into dict
+enr_dict = {
+    'GO_BP': enr_go_bp,
+    'GO_MF': enr_go_mf,
+    'KEGG': enr_kegg
+}
+colors_dict = {
+    'GO_BP': '#1f77b4',
+    'GO_MF': '#ff7f0e',
+    'KEGG': '#2ca02c'
+}
+ov.bulk.geneset_plot_multi(enr_dict, colors_dict, num=5)
+```
+
+## Common Errors and Solutions
+
+### Error: "FileNotFoundError" or "pathways_dict is not a dict"
+**Cause**: Passing file path string instead of dictionary to `geneset_enrichment()`
+**Solution**: First load with `ov.utils.geneset_prepare()`, then pass the returned dictionary
+
+### Error: "Missing file 'genesets/GO_Biological_Process_2021.gmt'"
+**Cause**: Pathway database not downloaded
+**Solution**: Run `ov.utils.download_pathway_database()` first
+
+### Error: "No enriched pathways found"
+**Cause**: Gene list doesn't overlap with pathway genes, or organism mismatch
+**Solution**:
+- Verify gene symbols match (human vs mouse capitalization)
+- Check `organism` parameter matches your data
+- Ensure gene list has sufficient genes (>10 recommended)
+
+## Pathway Databases Available
+
+After running `ov.utils.download_pathway_database()`:
+- `GO_Biological_Process_2021.txt`
+- `GO_Molecular_Function_2021.txt`
+- `GO_Cellular_Component_2021.txt`
+- `KEGG_2021_Human.txt`
+- `KEGG_2021_Mouse.txt`
+- `Reactome_2022.txt`
+- `WikiPathway_2023_Human.txt`
+- And many more...
+
+## Best Practices
+
+1. **Always load genesets first**: Never pass file paths directly to `geneset_enrichment()`
+2. **Check gene format**: Ensure gene symbols match (CAPS for human, Title case for mouse)
+3. **Download once**: Run `download_pathway_database()` once per environment
+4. **Specify organism**: Always set `organism='Human'` or `organism='Mouse'`
+5. **Use background genes**: For more accurate results, provide `background` parameter
+
+## Examples
+- "Run GO enrichment on my DEG results using the correct geneset_prepare workflow"
+- "Perform KEGG pathway analysis on upregulated genes with proper dictionary format"
+- "Compare GO BP, MF, and KEGG enrichment results using geneset_plot_multi"
+
+## References
+- Tutorial notebook: [`t_deg.ipynb`](../../omicverse_guide/docs/Tutorials-bulk/t_deg.ipynb) (enrichment section)
+- Pathway download: `ov.utils.download_pathway_database()`
+- Quick reference: [`reference.md`](reference.md)

package/data/skills/gtars/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: gtars
+description: High-performance toolkit for genomic interval analysis in Rust with Python bindings. Use when working with genomic regions, BED files, coverage tracks, overlap detection, tokenization for ML models, or fragment analysis in computational genomics and machine learning applications.
+---
+
+# Gtars: Genomic Tools and Algorithms in Rust
+
+## Overview
+
+Gtars is a high-performance Rust toolkit for manipulating, analyzing, and processing genomic interval data. It provides specialized tools for overlap detection, coverage analysis, tokenization for machine learning, and reference sequence management.
+
+Use this skill when working with:
+- Genomic interval files (BED format)
+- Overlap detection between genomic regions
+- Coverage track generation (WIG, BigWig)
+- Genomic ML preprocessing and tokenization
+- Fragment analysis in single-cell genomics
+- Reference sequence retrieval and validation
+
+## Installation
+
+### Python Installation
+
+Install gtars Python bindings:
+
+```bash
+uv uv pip install gtars
+```
+
+### CLI Installation
+
+Install command-line tools (requires Rust/Cargo):
+
+```bash
+# Install with all features
+cargo install gtars-cli --features "uniwig overlaprs igd bbcache scoring fragsplit"
+
+# Or install specific features only
+cargo install gtars-cli --features "uniwig overlaprs"
+```
+
+### Rust Library
+
+Add to Cargo.toml for Rust projects:
+
+```toml
+[dependencies]
+gtars = { version = "0.1", features = ["tokenizers", "overlaprs"] }
+```
+
+## Core Capabilities
+
+Gtars is organized into specialized modules, each focused on specific genomic analysis tasks:
+
+### 1. Overlap Detection and IGD Indexing
+
+Efficiently detect overlaps between genomic intervals using the Integrated Genome Database (IGD) data structure.
+
+**When to use:**
+- Finding overlapping regulatory elements
+- Variant annotation
+- Comparing ChIP-seq peaks
+- Identifying shared genomic features
+
+**Quick example:**
+```python
+import gtars
+
+# Build IGD index and query overlaps
+igd = gtars.igd.build_index("regions.bed")
+overlaps = igd.query("chr1", 1000, 2000)
+```
+
+See `references/overlap.md` for comprehensive overlap detection documentation.
+
+### 2. Coverage Track Generation
+
+Generate coverage tracks from sequencing data with the uniwig module.
+
+**When to use:**
+- ATAC-seq accessibility profiles
+- ChIP-seq coverage visualization
+- RNA-seq read coverage
+- Differential coverage analysis
+
+**Quick example:**
+```bash
+# Generate BigWig coverage track
+gtars uniwig generate --input fragments.bed --output coverage.bw --format bigwig
+```
+
+See `references/coverage.md` for detailed coverage analysis workflows.
+
+### 3. Genomic Tokenization
+
+Convert genomic regions into discrete tokens for machine learning applications, particularly for deep learning models on genomic data.
+
+**When to use:**
+- Preprocessing for genomic ML models
+- Integration with geniml library
+- Creating position encodings
+- Training transformer models on genomic sequences
+
+**Quick example:**
+```python
+from gtars.tokenizers import TreeTokenizer
+
+tokenizer = TreeTokenizer.from_bed_file("training_regions.bed")
+token = tokenizer.tokenize("chr1", 1000, 2000)
+```
+
+See `references/tokenizers.md` for tokenization documentation.
+
+### 4. Reference Sequence Management
+
+Handle reference genome sequences and compute digests following the GA4GH refget protocol.
+
+**When to use:**
+- Validating reference genome integrity
+- Extracting specific genomic sequences
+- Computing sequence digests
+- Cross-reference comparisons
+
+**Quick example:**
+```python
+# Load reference and extract sequences
+store = gtars.RefgetStore.from_fasta("hg38.fa")
+sequence = store.get_subsequence("chr1", 1000, 2000)
+```
+
+See `references/refget.md` for reference sequence operations.
+
+### 5. Fragment Processing
+
+Split and analyze fragment files, particularly useful for single-cell genomics data.
+
+**When to use:**
+- Processing single-cell ATAC-seq data
+- Splitting fragments by cell barcodes
+- Cluster-based fragment analysis
+- Fragment quality control
+
+**Quick example:**
+```bash
+# Split fragments by clusters
+gtars fragsplit cluster-split --input fragments.tsv --clusters clusters.txt --output-dir ./by_cluster/
+```
+
+See `references/cli.md` for fragment processing commands.
+
+### 6. Fragment Scoring
+
+Score fragment overlaps against reference datasets.
+
+**When to use:**
+- Evaluating fragment enrichment
+- Comparing experimental data to references
+- Quality metrics computation
+- Batch scoring across samples
+
+**Quick example:**
+```bash
+# Score fragments against reference
+gtars scoring score --fragments fragments.bed --reference reference.bed --output scores.txt
+```
+
+## Common Workflows
+
+### Workflow 1: Peak Overlap Analysis
+
+Identify overlapping genomic features:
+
+```python
+import gtars
+
+# Load two region sets
+peaks = gtars.RegionSet.from_bed("chip_peaks.bed")
+promoters = gtars.RegionSet.from_bed("promoters.bed")
+
+# Find overlaps
+overlapping_peaks = peaks.filter_overlapping(promoters)
+
+# Export results
+overlapping_peaks.to_bed("peaks_in_promoters.bed")
+```
+
+### Workflow 2: Coverage Track Pipeline
+
+Generate coverage tracks for visualization:
+
+```bash
+# Step 1: Generate coverage
+gtars uniwig generate --input atac_fragments.bed --output coverage.wig --resolution 10
+
+# Step 2: Convert to BigWig for genome browsers
+gtars uniwig generate --input atac_fragments.bed --output coverage.bw --format bigwig
+```
+
+### Workflow 3: ML Preprocessing
+
+Prepare genomic data for machine learning:
+
+```python
+from gtars.tokenizers import TreeTokenizer
+import gtars
+
+# Step 1: Load training regions
+regions = gtars.RegionSet.from_bed("training_peaks.bed")
+
+# Step 2: Create tokenizer
+tokenizer = TreeTokenizer.from_bed_file("training_peaks.bed")
+
+# Step 3: Tokenize regions
+tokens = [tokenizer.tokenize(r.chromosome, r.start, r.end) for r in regions]
+
+# Step 4: Use tokens in ML pipeline
+# (integrate with geniml or custom models)
+```
+
+## Python vs CLI Usage
+
+**Use Python API when:**
+- Integrating with analysis pipelines
+- Need programmatic control
+- Working with NumPy/Pandas
+- Building custom workflows
+
+**Use CLI when:**
+- Quick one-off analyses
+- Shell scripting
+- Batch processing files
+- Prototyping workflows
+
+## Reference Documentation
+
+Comprehensive module documentation:
+
+- **`references/python-api.md`** - Complete Python API reference with RegionSet operations, NumPy integration, and data export
+- **`references/overlap.md`** - IGD indexing, overlap detection, and set operations
+- **`references/coverage.md`** - Coverage track generation with uniwig
+- **`references/tokenizers.md`** - Genomic tokenization for ML applications
+- **`references/refget.md`** - Reference sequence management and digests
+- **`references/cli.md`** - Command-line interface complete reference
+
+## Integration with geniml
+
+Gtars serves as the foundation for the geniml Python package, providing core genomic interval operations for machine learning workflows. When working on geniml-related tasks, use gtars for data preprocessing and tokenization.
+
+## Performance Characteristics
+
+- **Native Rust performance**: Fast execution with low memory overhead
+- **Parallel processing**: Multi-threaded operations for large datasets
+- **Memory efficiency**: Streaming and memory-mapped file support
+- **Zero-copy operations**: NumPy integration with minimal data copying
+
+## Data Formats
+
+Gtars works with standard genomic formats:
+
+- **BED**: Genomic intervals (3-column or extended)
+- **WIG/BigWig**: Coverage tracks
+- **FASTA**: Reference sequences
+- **Fragment TSV**: Single-cell fragment files with barcodes
+
+## Error Handling and Debugging
+
+Enable verbose logging for troubleshooting:
+
+```python
+import gtars
+
+# Enable debug logging
+gtars.set_log_level("DEBUG")
+```
+
+```bash
+# CLI verbose mode
+gtars --verbose <command>
+```