@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-pdb-structure-navigation/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: bio-pdb-structure-navigation
+description: Navigate protein structure hierarchy using Biopython Bio.PDB SMCRA model. Use when accessing models, chains, residues, and atoms, iterating over structure levels, or extracting sequences from PDB files.
+tool_type: python
+primary_tool: Bio.PDB
+---
+
+## Version Compatibility
+
+Reference examples tested with: BioPython 1.83+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Structure Navigation
+
+**"Access residues and atoms in a PDB structure"** → Navigate the Structure-Model-Chain-Residue-Atom hierarchy to iterate over components, extract sequences, and access atomic coordinates.
+- Python: `structure[0]['A'][100]['CA'].get_vector()` for direct access
+
+Navigate the Structure-Model-Chain-Residue-Atom (SMCRA) hierarchy to access and iterate over structure components.
+
+## Required Imports
+
+```python
+from Bio.PDB import PDBParser, PPBuilder, Selection
+from Bio.Data.PDBData import protein_letters_3to1
+```
+
+## SMCRA Hierarchy
+
+```
+Structure
+    |
+    +-- Model (0, 1, ...)      # NMR ensembles, crystal asymmetric unit
+          |
+          +-- Chain (A, B, ...) # Polypeptide chains, ligands
+                |
+                +-- Residue     # Amino acids, nucleotides, hetero groups
+                      |
+                      +-- Atom  # Individual atoms
+```
+
+## Accessing Hierarchy Levels
+
+```python
+from Bio.PDB import PDBParser
+
+parser = PDBParser(QUIET=True)
+structure = parser.get_structure('protein', 'protein.pdb')
+
+# Access by index/ID
+model = structure[0]          # First model
+chain = model['A']            # Chain A
+residue = chain[100]          # Residue 100 (simple numbering)
+residue = chain[(' ', 100, ' ')]  # Full residue ID (hetfield, resseq, icode)
+atom = residue['CA']          # C-alpha atom
+```
+
+## Iterating Over Structure
+
+```python
+# Iterate all levels
+for model in structure:
+    for chain in model:
+        for residue in chain:
+            for atom in residue:
+                print(f'{chain.id}:{residue.id[1]}:{atom.name}')
+
+# Shortcut iterators (all levels below current)
+for chain in structure.get_chains():
+    print(f'Chain: {chain.id}')
+
+for residue in structure.get_residues():
+    print(f'Residue: {residue.resname}')
+
+for atom in structure.get_atoms():
+    print(f'Atom: {atom.name} at {atom.coord}')
+```
+
+## Residue Identification
+
+```python
+# Residue ID is a tuple: (hetfield, resseq, icode)
+for residue in chain:
+    hetfield, resseq, icode = residue.id
+    print(f'Residue {resseq}{icode}: {residue.resname}')
+
+# hetfield values:
+#   ' '  - standard amino acid
+#   'W'  - water
+#   'H_xxx' - hetero residue (ligand, modified residue)
+
+# Filter standard residues only
+standard_residues = [r for r in chain if r.id[0] == ' ']
+
+# Filter water
+waters = [r for r in chain if r.id[0] == 'W']
+
+# Filter hetero atoms (ligands)
+hetero = [r for r in chain if r.id[0].startswith('H_')]
+```
+
+## Atom Properties
+
+```python
+for atom in residue:
+    print(f'Name: {atom.name}')
+    print(f'Element: {atom.element}')
+    print(f'Coordinates: {atom.coord}')
+    print(f'B-factor: {atom.bfactor}')
+    print(f'Occupancy: {atom.occupancy}')
+    print(f'Full ID: {atom.full_id}')
+    print(f'Serial number: {atom.serial_number}')
+```
+
+## Getting Full Identifiers
+
+```python
+# Full hierarchical ID from any entity
+atom = structure[0]['A'][100]['CA']
+print(atom.get_full_id())
+# ('protein', 0, 'A', (' ', 100, ' '), ('CA', ' '))
+
+# Components: (structure_id, model_id, chain_id, residue_id, atom_id)
+```
+
+## Checking for Children
+
+```python
+# Check if entity has child
+if chain.has_id(100):
+    residue = chain[100]
+
+# Check if residue has atom
+if residue.has_id('CA'):
+    ca = residue['CA']
+
+# Get list of all children
+chains = structure[0].get_list()
+residues = chain.get_list()
+atoms = residue.get_list()
+```
+
+## Getting Parent Entity
+
+```python
+# Navigate up hierarchy
+atom = structure[0]['A'][100]['CA']
+
+residue = atom.get_parent()
+chain = residue.get_parent()
+model = chain.get_parent()
+structure = model.get_parent()
+```
+
+## Extracting Polypeptide Sequences
+
+```python
+from Bio.PDB import PDBParser, PPBuilder
+
+parser = PDBParser(QUIET=True)
+structure = parser.get_structure('protein', 'protein.pdb')
+
+ppb = PPBuilder()
+for pp in ppb.build_peptides(structure):
+    seq = pp.get_sequence()
+    print(f'Polypeptide: {seq}')
+    print(f'Length: {len(seq)}')
+
+# Get all sequences as list
+sequences = [pp.get_sequence() for pp in ppb.build_peptides(structure)]
+```
+
+## Using CaPPBuilder for Broken Chains
+
+```python
+from Bio.PDB import CaPPBuilder
+
+# Use when backbone is incomplete
+# Connects residues if CA atoms are within 4.3 Angstroms
+ppb = CaPPBuilder()
+for pp in ppb.build_peptides(structure):
+    print(f'Fragment: {pp.get_sequence()}')
+```
+
+## Converting Residue Names
+
+```python
+from Bio.Data.PDBData import protein_letters_3to1
+
+# Three-letter to one-letter conversion
+three_letter = 'ALA'
+one_letter = protein_letters_3to1.get(three_letter, 'X')
+print(f'{three_letter} -> {one_letter}')  # ALA -> A
+
+# Build sequence manually
+sequence = ''
+for residue in chain:
+    if residue.id[0] == ' ':  # Standard residue
+        code = protein_letters_3to1.get(residue.resname, 'X')
+        sequence += code
+print(f'Sequence: {sequence}')
+```
+
+## Using Selection.unfold_entities
+
+```python
+from Bio.PDB import Selection
+
+# Extract entities at specific level
+# Codes: S=structure, M=model, C=chain, R=residue, A=atom
+
+# Get all residues from structure
+residues = Selection.unfold_entities(structure, 'R')
+print(f'Total residues: {len(residues)}')
+
+# Get all atoms from a chain
+atoms = Selection.unfold_entities(chain, 'A')
+print(f'Atoms in chain: {len(atoms)}')
+
+# Get all chains from model
+chains = Selection.unfold_entities(model, 'C')
+```
+
+## Handling Disordered Atoms
+
+```python
+# Check for disorder
+if atom.is_disordered():
+    print(f'Atom {atom.name} has multiple conformations')
+    print(f'Alt locations: {atom.disordered_get_id_list()}')
+
+    # Select specific conformation
+    atom.disordered_select('A')
+    print(f'Coord for alt A: {atom.coord}')
+
+    # Get all conformations
+    for altloc in atom.disordered_get_id_list():
+        atom.disordered_select(altloc)
+        print(f'  {altloc}: {atom.coord}')
+
+# Get unpacked list (all conformations)
+all_atoms = atom.disordered_get_list()
+```
+
+## Handling Disordered Residues
+
+```python
+# Point mutations at same position
+if residue.is_disordered():
+    print(f'Disordered residue at {residue.id}')
+    names = residue.disordered_get_id_list()
+    print(f'Alternative residues: {names}')
+
+    # Select specific residue type
+    residue.disordered_select('ALA')
+```
+
+## Finding Specific Atoms
+
+```python
+# Get backbone atoms
+backbone_names = ['N', 'CA', 'C', 'O']
+for residue in chain:
+    backbone = [residue[name] for name in backbone_names if residue.has_id(name)]
+
+# Get all C-alpha atoms
+ca_atoms = [r['CA'] for r in structure.get_residues() if r.has_id('CA')]
+print(f'Found {len(ca_atoms)} CA atoms')
+
+# Get sidechain atoms
+for residue in chain:
+    sidechain = [a for a in residue if a.name not in ['N', 'CA', 'C', 'O']]
+```
+
+## Filtering by Residue Type
+
+```python
+# Get only amino acids
+amino_acids = [r for r in chain if r.id[0] == ' ']
+
+# Get specific amino acid types
+arginines = [r for r in chain if r.resname == 'ARG']
+charged = [r for r in chain if r.resname in ['ARG', 'LYS', 'ASP', 'GLU']]
+
+# Get hetero atoms
+ligands = [r for r in chain if r.id[0].startswith('H_')]
+for lig in ligands:
+    print(f'Ligand: {lig.resname} at position {lig.id[1]}')
+```
+
+## Counting Entities
+
+```python
+# Count at each level
+n_models = len(list(structure.get_models()))
+n_chains = len(list(structure.get_chains()))
+n_residues = len(list(structure.get_residues()))
+n_atoms = len(list(structure.get_atoms()))
+
+print(f'Models: {n_models}, Chains: {n_chains}')
+print(f'Residues: {n_residues}, Atoms: {n_atoms}')
+
+# Count per chain
+for chain in structure.get_chains():
+    n_res = len([r for r in chain if r.id[0] == ' '])
+    print(f'Chain {chain.id}: {n_res} amino acids')
+```
+
+## Working with NMR Ensembles
+
+```python
+# NMR structures have multiple models
+parser = PDBParser(QUIET=True)
+structure = parser.get_structure('nmr', 'nmr_structure.pdb')
+
+n_models = len(list(structure.get_models()))
+print(f'NMR ensemble with {n_models} conformers')
+
+# Iterate over models
+for model in structure:
+    # Each model is a separate conformation
+    ca_coords = [r['CA'].coord for r in model.get_residues() if r.has_id('CA')]
+    print(f'Model {model.id}: {len(ca_coords)} CA atoms')
+```
+
+## Related Skills
+
+- structure-io - Parse and write structure files
+- geometric-analysis - Measure distances, angles, RMSD
+- structure-modification - Modify coordinates and properties
+- sequence-manipulation/seq-objects - Work with extracted sequences

package/data/skills/bio-phasing-imputation-genotype-imputation/SKILL.md

@@ -0,0 +1,201 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-phasing-imputation-genotype-imputation
+description: Impute missing genotypes using reference panels with Beagle or Minimac4. Use when increasing variant density for GWAS, harmonizing data across genotyping platforms, or inferring variants not directly typed in array data.
+tool_type: cli
+primary_tool: beagle
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Genotype Imputation
+
+## Beagle Imputation
+
+```bash
+# Basic imputation
+java -jar beagle.jar \
+    gt=study.vcf.gz \
+    ref=reference_panel.vcf.gz \
+    map=genetic_map.txt \
+    out=imputed
+
+# Output: imputed.vcf.gz with imputed genotypes
+```
+
+## Beagle with Options
+
+```bash
+java -Xmx32g -jar beagle.jar \
+    gt=study.vcf.gz \
+    ref=reference_panel.vcf.gz \
+    map=genetic_map.txt \
+    out=imputed \
+    nthreads=8 \
+    gp=true \              # Output genotype probabilities
+    ap=true \              # Output allele probabilities
+    impute=true \          # Perform imputation (default)
+    ne=20000               # Effective population size
+```
+
+## Impute Per Chromosome
+
+```bash
+for chr in {1..22}; do
+    java -Xmx32g -jar beagle.jar \
+        gt=study.chr${chr}.vcf.gz \
+        ref=ref.chr${chr}.vcf.gz \
+        map=genetic_maps/plink.chr${chr}.GRCh38.map \
+        out=imputed.chr${chr} \
+        gp=true \
+        nthreads=8
+done
+
+# Concatenate
+bcftools concat imputed.chr*.vcf.gz -Oz -o imputed.all.vcf.gz
+bcftools index imputed.all.vcf.gz
+```
+
+## IMPUTE5 (Alternative)
+
+```bash
+# Newer IMPUTE software
+impute5 \
+    --h reference.bcf \
+    --m genetic_map.txt \
+    --g study.vcf.gz \
+    --r chr22 \
+    --o imputed.chr22.vcf.gz \
+    --threads 8
+```
+
+## Minimac4 (Michigan Imputation Server)
+
+```bash
+# Often used via web server, but can run locally
+minimac4 \
+    --refHaps reference.m3vcf.gz \
+    --haps study.vcf.gz \
+    --prefix imputed \
+    --format GT,DS,GP \
+    --cpus 8
+```
+
+## Input Preparation
+
+```bash
+# 1. Align to reference (strand, allele order)
+bcftools +fixref study.vcf.gz -Oz -o fixed.vcf.gz -- \
+    -f reference.fa -m flip
+
+# 2. Filter to sites in reference
+bcftools isec -n=2 -w1 fixed.vcf.gz reference_sites.vcf.gz \
+    -Oz -o study_overlap.vcf.gz
+
+# 3. Phase first (if not already phased)
+java -jar beagle.jar gt=study_overlap.vcf.gz out=phased
+
+# 4. Then impute
+java -jar beagle.jar gt=phased.vcf.gz ref=reference.vcf.gz out=imputed
+```
+
+## Extract Imputation Quality
+
+```bash
+# INFO/DR2 or INFO/R2 contains imputation quality
+bcftools query -f '%CHROM\t%POS\t%ID\t%INFO/DR2\n' imputed.vcf.gz > info_scores.txt
+
+# Filter by quality
+bcftools view -i 'INFO/DR2 > 0.3' imputed.vcf.gz -Oz -o imputed_filtered.vcf.gz
+```
+
+## Output Formats
+
+| Format | Field | Description |
+|--------|-------|-------------|
+| GT | 0\|0, 0\|1, 1\|1 | Hard-called genotype |
+| DS | 0.0-2.0 | Dosage (expected ALT allele count) |
+| GP | 0.0-1.0,0.0-1.0,0.0-1.0 | Genotype probabilities (AA,AB,BB) |
+| DR2/R2 | 0.0-1.0 | Imputation quality score |
+
+## Using Dosages for GWAS
+
+```python
+import pandas as pd
+
+# Extract dosages
+# bcftools query -f '%CHROM\t%POS\t%ID[\t%DS]\n' imputed.vcf.gz > dosages.txt
+
+dosages = pd.read_csv('dosages.txt', sep='\t')
+
+# Dosage-based association (treats uncertainty)
+# Use --dosage in PLINK2 or similar
+```
+
+```bash
+# PLINK2 with dosages
+plink2 --vcf imputed.vcf.gz dosage=DS \
+    --glm \
+    --pheno phenotypes.txt \
+    --out gwas_results
+```
+
+## Quality Thresholds
+
+| Analysis | Minimum INFO/R2 |
+|----------|-----------------|
+| GWAS discovery | 0.3 |
+| GWAS fine-mapping | 0.8 |
+| Meta-analysis | 0.5 |
+| Polygenic scores | 0.9 |
+
+## Key Parameters
+
+| Parameter | Beagle | Description |
+|-----------|--------|-------------|
+| gt | input VCF | Study genotypes |
+| ref | reference VCF | Reference panel |
+| map | genetic map | Recombination map |
+| gp | true/false | Output genotype probs |
+| ne | 20000 | Effective population size |
+| nthreads | N | CPU threads |
+| window | 40 | Window size (cM) |
+
+## Imputation Servers
+
+For large-scale imputation, consider web-based servers:
+- **Michigan Imputation Server**: imputationserver.sph.umich.edu
+- **TOPMed Imputation Server**: imputation.biodatacatalyst.nhlbi.nih.gov
+- **Sanger Imputation Server**: imputation.sanger.ac.uk
+
+```bash
+# Prepare input for server
+# Most require VCF.GZ per chromosome
+for chr in {1..22}; do
+    bcftools view -r chr${chr} study.vcf.gz -Oz -o study.chr${chr}.vcf.gz
+done
+```
+
+## Related Skills
+
+- phasing-imputation/haplotype-phasing - Pre-phasing step
+- phasing-imputation/reference-panels - Reference panel setup
+- phasing-imputation/imputation-qc - Quality control
+- population-genetics/association-testing - GWAS with imputed data
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/bio-phasing-imputation-haplotype-phasing/SKILL.md

@@ -0,0 +1,190 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: bio-phasing-imputation-haplotype-phasing
+description: Phase genotypes into haplotypes using Beagle or SHAPEIT. Resolves which alleles are inherited together on each chromosome. Use when preparing VCF files for imputation, HLA typing, or population genetic analyses requiring phased haplotypes.
+tool_type: cli
+primary_tool: beagle
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+# Haplotype Phasing
+
+## Beagle 5.4 Phasing (Recommended)
+
+```bash
+# Download Beagle 5.4
+wget https://faculty.washington.edu/browning/beagle/beagle.22Jul22.46e.jar
+
+# Basic phasing
+java -jar beagle.22Jul22.46e.jar \
+    gt=input.vcf.gz \
+    out=phased
+
+# Output: phased.vcf.gz (phased genotypes)
+
+# With genetic map (improves accuracy)
+java -jar beagle.22Jul22.46e.jar \
+    gt=input.vcf.gz \
+    map=plink.chr22.GRCh38.map \
+    out=phased
+```
+
+## Beagle Options
+
+```bash
+java -jar beagle.22Jul22.46e.jar \
+    gt=input.vcf.gz \
+    out=phased \
+    map=genetic_map.txt \
+    nthreads=8 \
+    window=40 \
+    overlap=4 \
+    ne=20000 \              # Effective population size
+    seed=12345              # For reproducibility
+```
+
+## Phase Per Chromosome
+
+```bash
+# Process each chromosome separately
+for chr in {1..22}; do
+    java -Xmx16g -jar beagle.jar \
+        gt=input.chr${chr}.vcf.gz \
+        map=genetic_maps/plink.chr${chr}.GRCh38.map \
+        out=phased.chr${chr} \
+        nthreads=8
+done
+
+# Concatenate chromosomes
+bcftools concat phased.chr*.vcf.gz -Oz -o phased.all.vcf.gz
+bcftools index phased.all.vcf.gz
+```
+
+## SHAPEIT5 Phasing (for Large Datasets)
+
+```bash
+# Phase common variants first
+shapeit5_phase_common \
+    --input input.vcf.gz \
+    --map genetic_map.txt \
+    --output phased_common.bcf \
+    --thread 8 \
+    --log phased.log
+
+# Then phase rare variants
+shapeit5_phase_rare \
+    --input input.vcf.gz \
+    --scaffold phased_common.bcf \
+    --map genetic_map.txt \
+    --output phased.bcf \
+    --thread 8
+```
+
+## SHAPEIT5 with Reference Panel
+
+```bash
+# Improves phasing using reference haplotypes
+shapeit5_phase_common \
+    --input input.vcf.gz \
+    --reference reference_panel.bcf \
+    --map genetic_map.txt \
+    --output phased.bcf \
+    --thread 8
+```
+
+## Beagle with Reference Panel
+
+```bash
+# Use reference panel for better phasing
+java -jar beagle.22Jul22.46e.jar \
+    gt=input.vcf.gz \
+    ref=reference.vcf.gz \
+    map=genetic_map.txt \
+    out=phased \
+    nthreads=8
+```
+
+## Input Preparation
+
+```bash
+# Filter variants before phasing
+bcftools view -m2 -M2 -v snps input.vcf.gz -Oz -o biallelic_snps.vcf.gz
+
+# Remove missing genotypes (optional)
+bcftools view -g ^miss biallelic_snps.vcf.gz -Oz -o no_missing.vcf.gz
+
+# Normalize (important!)
+bcftools norm -f reference.fa -Oz -o normalized.vcf.gz input.vcf.gz
+```
+
+## Check Phasing Results
+
+```bash
+# View phased genotypes (| instead of /)
+bcftools query -f '%CHROM\t%POS\t[%GT\t]\n' phased.vcf.gz | head
+
+# Unphased: 0/1
+# Phased: 0|1 or 1|0
+
+# Count phased vs unphased
+bcftools query -f '[%GT\n]' phased.vcf.gz | grep -c '|'
+```
+
+## Genetic Maps
+
+```bash
+# Download genetic maps (GRCh38)
+wget https://faculty.washington.edu/browning/beagle/genetic_maps/plink.GRCh38.map.zip
+unzip plink.GRCh38.map.zip
+
+# Format: chromosome position rate(cM/Mb) genetic_position(cM)
+# chr1 55550 2.981822 0.000000
+```
+
+## Key Parameters
+
+| Parameter | Beagle | SHAPEIT5 | Description |
+|-----------|--------|----------|-------------|
+| Threads | nthreads | --thread | CPU threads |
+| Window | window | --window | Analysis window size |
+| Eff. pop size | ne | --effective-size | For LD modeling |
+| Seed | seed | --seed | Random seed |
+
+## Memory Requirements
+
+| Dataset Size | Beagle Memory | SHAPEIT5 Memory |
+|--------------|--------------|-----------------|
+| 1,000 samples | 8 GB | 4 GB |
+| 10,000 samples | 32 GB | 16 GB |
+| 100,000 samples | 64+ GB | 32 GB |
+
+## Phasing Accuracy Metrics
+
+- **Switch error rate**: Rate of phase switches vs truth
+- **Mismatch error rate**: Overall haplotype differences
+- Measure using trio data or known haplotypes
+
+## Related Skills
+
+- phasing-imputation/genotype-imputation - Impute after phasing
+- phasing-imputation/reference-panels - Get reference data
+- variant-calling/filtering-best-practices - Prepare input VCF
+- population-genetics/linkage-disequilibrium - LD analysis
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->