Add FermiLink skills for gwaslab

Author: TaoELi

skills/.compile_report.json

@@ -0,0 +1 @@
+.evidence/

skills/.gitignore

@@ -0,0 +1,65 @@
+---
+name: gwaslab-advanced-topics
+description: Use this skill for consolidated low-frequency GWASLab topics (reference-data management, VCF/FASTA/GTF IO, reserved headers, ancestry inference, update logs, and utility docs) that were merged to avoid one-doc routing fragmentation.
+---
+
+# gwaslab: Advanced Topics
+
+## High-Signal Playbook
+### Route Conditions
+- Use this skill for specialized references/utilities not covered by core workflow skills.
+- Route to `gwaslab-simulation-workflows` for end-to-end harmonization pipelines.
+- Route to `gwaslab-inputs-and-modeling` for generic format/header mapping.
+
+### Canonical Workflow
+1. Open the exact topic doc first (`Download`, `Reference`, VCF/FASTA/GTF, `InferAncestry`, `reserved_header`).
+2. Run the smallest reproducible check using local test/reference data.
+3. Escalate to `references/source_map.md` only for implementation-level behavior.
+
+### Minimal Checks
+```python
+import gwaslab as gl
+
+print(gl.check_available_ref(show_all=False, verbose=False))
+print(gl.get_path("1kg_eas_hg19"))
+```
+
+```bash
+pytest -q test/test_read_fasta_chromosome_formats.py test/test_read_gtf_chromosome_formats.py
+```
+
+### Validation Checkpoints
+- Reference key lookup returns a non-empty path or a clear missing-reference message.
+- FASTA/GTF/VCF readers load expected chromosome naming styles.
+- Reserved-header checks match expected column contracts.
+
+## Scope
+- Consolidated routing for specialized topics that each had narrow single-doc coverage.
+- Keeps uncommon but important reference and utility content discoverable without fragmented routing.
+
+## Route the request
+- Reference asset catalogs/download paths/configuration -> `docs/Download.md`, `docs/Download_reference.md`, `docs/Reference.md`, `docs/CommonData.md`
+- File-format internals (VCF/FASTA/GTF) -> `docs/VCF.md`, `docs/FASTA.md`, `docs/GTF.md`
+- Data model/header contracts -> `docs/SumstatsObject.md`, `docs/reserved_header.md`
+- Population and panel utilities -> `docs/InferAncestry.md`, `docs/Hapmap3.md`
+- Lead/novel utility details -> `docs/utility_get_lead_novel.md`
+- Release and method reference context -> `docs/UpdateLogs.md`, `docs/PaperReference.md`
+
+## Workflow
+- Start with the exact doc matching the specialized request.
+- Use `references/doc_map.md` for full inventory and headings.
+- Escalate to `references/source_map.md` only when behavior details are not explicit in docs.
+- Cite exact documentation paths.
+
+## Source entry points for unresolved issues
+- `src/gwaslab/bd/bd_download.py`
+- `src/gwaslab/bd/bd_common_data.py`
+- `src/gwaslab/bd/bd_get_hapmap3.py`
+- `src/gwaslab/io/io_vcf.py`
+- `src/gwaslab/io/io_fasta.py`
+- `src/gwaslab/io/io_gtf.py`
+- `src/gwaslab/qc/qc_reserved_headers.py`
+- `src/gwaslab/util/util_ex_infer_ancestry.py`
+- `src/gwaslab/util/util_in_get_sig.py`
+- `src/gwaslab/g_Sumstats.py`
+- Prefer targeted search: `rg -n "<symbol_or_keyword>" src/gwaslab`

skills/gwaslab-advanced-topics/SKILL.md

@@ -0,0 +1,24 @@
+# gwaslab documentation map: Advanced Topics
+
+Generated from documentation roots:
+- `docs`
+- `examples`
+- `test`
+
+Total docs grouped in this topic: 14
+
+## File inventory
+- `docs/CommonData.md` | title: Commonly used data in GWASLab | headings: Commonly used data in GWASLab; Chromosome notation conversion dictionary; Full chromosome list
+- `docs/Download.md` | title: Download reference data | headings: Download reference data; Downloading and file management system; Configurations
+- `docs/Download_reference.md` | title: Download reference data | headings: Download reference data; Check available reference data; Check downloaded reference data
+- `docs/FASTA.md` | title: FASTA I/O in GWASLab | headings: FASTA I/O in GWASLab; Supported File Formats; Reading FASTA Files
+- `docs/GTF.md` | title: GTF I/O in GWASLab | headings: GTF I/O in GWASLab; Supported File Formats; Reading GTF Files
+- `docs/Hapmap3.md` | title: Hapmap3 SNPs in GWASLab | headings: Hapmap3 SNPs in GWASLab
+- `docs/InferAncestry.md` | title: Infer Ancestry | headings: Infer Ancestry; How It Works; .infer_ancestry()
+- `docs/Reference.md` | title: Reference data for handling Sumstats | headings: Reference data for handling Sumstats; Reference genome sequence for variant allele alignment; Processed Reference files for harmonization
+- `docs/reserved_header.md` | title: Reserved headers | headings: Reserved headers
+- `docs/SumstatsObject.md` | title: Sumstats Object in GWASLab | headings: Sumstats Object in GWASLab; gl.Sumstats(); Options
+- `docs/PaperReference.md` | title: Academic Paper References | headings: Academic Paper References; GWASLab; Methods Implemented
+- `docs/UpdateLogs.md` | title: Update Logs | headings: Update Logs; v4.1.1 20260208; v4.1.0 20260205
+- `docs/utility_get_lead_novel.md` | title: Lead and novel variants | headings: Lead and novel variants; Load sample data; Get lead variants
+- `docs/VCF.md` | title: VCF I/O in GWASLab | headings: VCF I/O in GWASLab; Supported File Formats; VCF File Detection and Chromosome Handling

skills/gwaslab-advanced-topics/references/doc_map.md

@@ -0,0 +1,40 @@
+# gwaslab source map: Advanced Topics
+
+Generated from source roots:
+- `src`
+
+Use this map only after exhausting the topic docs in `doc_map.md`.
+
+## Topic query tokens
+- `download_ref`
+- `check_available_ref`
+- `get_path`
+- `vcf`
+- `fasta`
+- `gtf`
+- `reserved_header`
+- `infer_ancestry`
+- `hapmap3`
+- `get_lead`
+- `get_novel`
+
+## Fast source navigation
+- `rg -n "<symbol_or_keyword>" src/gwaslab`
+- `rg -n "^(def|class)\s+" src/gwaslab/bd/bd_download.py src/gwaslab/io/io_vcf.py src/gwaslab/io/io_fasta.py src/gwaslab/io/io_gtf.py`
+
+## Suggested source entry points
+- `src/gwaslab/bd/bd_download.py` | key functions: `check_available_ref`, `check_downloaded_ref`, `get_path`, `download_ref`
+- `src/gwaslab/bd/bd_common_data.py` | key functions: `get_chr_to_NC`, `get_recombination_rate`, `get_chain`, `get_format_dict`
+- `src/gwaslab/bd/bd_get_hapmap3.py` | key function: `_get_hapmap3`
+- `src/gwaslab/io/io_vcf.py` | key functions: `is_vcf_file`, `check_vcf_chr_prefix`, `_get_ld_matrix_from_vcf`
+- `src/gwaslab/io/io_fasta.py` | key functions: `parse_fasta`, `load_fasta_auto`, `load_fasta_filtered`, `get_fasta_record`
+- `src/gwaslab/io/io_gtf.py` | key functions: `read_gtf`, `get_gtf`, `gtf_to_protein_coding`, `gtf_to_all_gene`
+- `src/gwaslab/qc/qc_reserved_headers.py` | key functions: `get_default_sanity_ranges`, `_get_headers`, `_check_overlap_with_reserved_keys`
+- `src/gwaslab/util/util_ex_infer_ancestry.py` | key functions: `_infer_ancestry`, `calculate_fst`
+- `src/gwaslab/util/util_in_get_sig.py` | key functions: `_get_sig`, `_get_novel`, `_check_novel_set`
+- `src/gwaslab/g_Sumstats.py` | key methods: `infer_ancestry`, `filter_hapmap3`, `get_lead`, `get_novel`
+
+## Function-level behavior checks
+- `pytest -q test/test_path_manager.py test/test_infer_build_and_hapmap3.py`
+- `pytest -q test/test_read_fasta_chromosome_formats.py test/test_read_gtf_chromosome_formats.py`
+- `pytest -q test/test_get_lead_top.py test/test_get_novel.py`

skills/gwaslab-advanced-topics/references/source_map.md

@@ -0,0 +1,87 @@
+---
+name: gwaslab-analysis-and-output
+description: Use this skill for GWASLab visualization and reporting outputs, including mqq/regional/stacked/miami workflows, lead-variant annotations, and export/report patterns.
+---
+
+# gwaslab: Analysis and Output
+
+## High-Signal Playbook
+### Route Conditions
+- Use this skill for plot generation, output tuning, and report-ready artifacts.
+- Route to `gwaslab-getting-started` if data is not yet loadable/QCed.
+- Route to `gwaslab-simulation-workflows` for harmonization or clumping prerequisites.
+- Route to `gwaslab-inputs-and-modeling` for format-conversion-only requests.
+
+### Triage Questions
+- Which figure is required: `mqq`, `regional`, `stacked`, `miami`, correlation heatmap?
+- Are input objects already QCed and build-tagged?
+- Is region-specific LD annotation needed (VCF/recombination/GTF)?
+- Are there one or two cohorts (for Miami/stacked comparisons)?
+- Is the issue styling/parameter tuning or plotting failure?
+- What final artifact is needed: figure only, lead table, or formatted output package?
+
+### Canonical Workflow
+1. Confirm input data quality and build before plotting (`docs/tutorial_v4.md`, `docs/visualization_mqq.md`).
+2. Generate baseline `plot_mqq()` with `skip/cut` to control scale/performance (`docs/visualization_mqq.md`).
+3. For locus detail, use `plot_mqq(mode="r", region=...)` with optional LD/gene tracks (`docs/visualization_regional.md`).
+4. For comparisons, use `gl.plot_stacked_mqq()` or `gl.plot_miami2()` with `Sumstats` objects (`docs/visualization_stacked_mqq.md`, `docs/visualization_miami2.md`).
+5. Extract/annotate lead variants with `get_lead()` and export with `to_format()` (`docs/utility_get_lead_novel.md`, `docs/Format.md`).
+6. Cross-check known plotting edge cases in `KnownIssues` when outputs look inconsistent (`docs/KnownIssues.md`).
+
+### Minimal Working Example
+```python
+import gwaslab as gl
+
+s = gl.Sumstats("sumstats.tsv.gz", fmt="auto", build="19")
+s.basic_check(verbose=False)
+
+s.plot_mqq(skip=2, cut=20)
+s.plot_mqq(mode="r", region=(7, 156538803, 157538803))
+lead = s.get_lead(sig_level=5e-8)
+s.to_format("analysis_ready", fmt="gwaslab")
+```
+
+### Pitfalls and Fixes
+- `gl.plot_miami2()` called with file paths: pass `Sumstats` objects for `path1` and `path2` (`docs/visualization_miami2.md`).
+- Regional plots missing LD context: provide reference VCF and matching build (`docs/visualization_regional.md`).
+- Plotting full datasets is too slow/noisy: increase `skip` and use `cut`/`mode` adjustments (`docs/visualization_mqq.md`).
+- Unexpected lead extraction in older versions: use updated package and check `KnownIssues` notes (`docs/KnownIssues.md`).
+- Export formatting confusion after plotting: use explicit `to_format()` options and naming rules (`docs/Format.md`).
+
+### Convergence and Validation Checks
+- Figures render with expected panel/layout mode and no build mismatch warnings.
+- Lead-variant counts are consistent with chosen significance/window settings.
+- Annotation labels and highlighted loci map to expected SNPs/genes.
+- Exported tables/files reopen cleanly and preserve plotted variant identifiers.
+
+## Scope
+- Visualization and output generation from QC-ready GWAS summary statistics.
+- Includes parameter tuning and output packaging.
+
+## Primary documentation references
+- `docs/visualization_mqq.md`
+- `docs/visualization_regional.md`
+- `docs/visualization_stacked_mqq.md`
+- `docs/visualization_miami2.md`
+- `docs/visualization_plot_genetic_correlation.md`
+- `docs/Format.md`
+- `docs/format_load_save.md`
+- `docs/KnownIssues.md`
+
+## Workflow
+- Start with docs examples for the requested plot mode.
+- Use `references/doc_map.md` for wider option inventory.
+- Escalate to source maps only when parameter behavior is unclear.
+
+## Source entry points for unresolved issues
+- `src/gwaslab/viz/viz_plot_mqqplot.py`
+- `src/gwaslab/viz/viz_plot_regional2.py`
+- `src/gwaslab/viz/viz_plot_stackedregional.py`
+- `src/gwaslab/viz/viz_plot_stackedpanel.py`
+- `src/gwaslab/viz/viz_plot_miamiplot2.py`
+- `src/gwaslab/viz/viz_plot_rg_heatmap.py`
+- `src/gwaslab/viz/viz_aux_quickfix.py`
+- `src/gwaslab/viz/viz_aux_save_figure.py`
+- `src/gwaslab/util/util_in_get_sig.py`
+- `src/gwaslab/io/io_to_formats.py`
+- Prefer targeted search: `rg -n "<symbol_or_keyword>" src/gwaslab/viz src/gwaslab/util src/gwaslab/io`

skills/gwaslab-analysis-and-output/SKILL.md

@@ -0,0 +1,22 @@
+# gwaslab documentation map: Analysis and Output
+
+Generated from documentation roots:
+- `docs`
+- `examples`
+- `test`
+
+Total docs grouped in this topic: 12
+
+## File inventory
+- `docs/Visualization.md` | title: Manhattan plot and QQ plot | headings: .plot_mqq(); options
+- `docs/visualization_mqq.md` | title: Manhattan and Q-Q plot | headings: Load data into Sumstats Object; .plot_mqq()
+- `docs/visualization_regional.md` | title: Regional plot | headings: region mode; LD annotation
+- `docs/visualization_stacked_mqq.md` | title: Stacked Manhattan and regional plot | headings: gl.plot_stacked_mqq()
+- `docs/visualization_miami2.md` | title: Miami plot | headings: gl.plot_miami2(); options
+- `docs/visualization_plot_genetic_correlation.md` | title: Correlation heatmap | headings: Full heatmap; selected traits
+- `docs/EffectSize.md` | title: Comparing effect sizes | headings: gl.compare_effect(); scatter options
+- `docs/Format.md` | title: Output sumstats in certain formats | headings: .to_format(); options
+- `docs/format_load_save.md` | title: Input and output sumstats | headings: output handling
+- `docs/utility_get_lead_novel.md` | title: Lead and novel variants | headings: get_lead; get_novel
+- `docs/KnownIssues.md` | title: Known issues | headings: plotting and lead extraction caveats
+- `docs/Gallery.md` | title: GWASLab Gallery | headings: Manhattan/Q-Q; regional; other examples

skills/gwaslab-analysis-and-output/references/doc_map.md

@@ -0,0 +1,40 @@
+# gwaslab source map: Analysis and Output
+
+Generated from source roots:
+- `src`
+
+Use this map only after exhausting the topic docs in `doc_map.md`.
+
+## Topic query tokens
+- `plot_mqq`
+- `plot_region`
+- `plot_stacked_mqq`
+- `plot_miami2`
+- `plot_rg`
+- `compare_effect`
+- `get_lead`
+- `get_novel`
+- `to_format`
+
+## Fast source navigation
+- `rg -n "<symbol_or_keyword>" src/gwaslab/viz src/gwaslab/util src/gwaslab/io`
+- `rg -n "^\s+def\s+(plot_mqq|plot_region|get_lead|get_novel|to_format)" src/gwaslab/g_Sumstats.py`
+
+## Suggested source entry points
+- `src/gwaslab/g_Sumstats.py` | key methods: `plot_mqq`, `plot_region`, `get_lead`, `get_novel`, `to_format`
+- `src/gwaslab/viz/viz_plot_mqqplot.py` | key function: `_mqqplot`
+- `src/gwaslab/viz/viz_plot_regional2.py` | key functions: `_plot_regional`, `process_vcf`, `process_ld`, `process_gtf`
+- `src/gwaslab/viz/viz_plot_stackedregional.py` | key function: `plot_stacked_mqq`
+- `src/gwaslab/viz/viz_plot_miamiplot2.py` | key function: `plot_miami2`
+- `src/gwaslab/viz/viz_plot_rg_heatmap.py` | key function: `plot_rg`
+- `src/gwaslab/viz/viz_plot_compare_effect.py` | key function: `compare_effect`
+- `src/gwaslab/viz/viz_aux_save_figure.py` | key functions: `save_figure`, `get_default_path`
+- `src/gwaslab/util/util_in_get_sig.py` | key functions: `_get_sig`, `_get_novel`, `_anno_gene`
+- `src/gwaslab/io/io_to_formats.py` | key functions: `_to_format`, `_write_tabular`
+- `src/gwaslab/view/view_report.py` | key function: `generate_qc_report`
+
+## Function-level behavior checks
+- `pytest -q test/test_viz_mqqplot.py test/test_viz_related_plots.py test/test_viz_panel.py`
+- `pytest -q test/test_get_lead_top.py test/test_get_novel.py`
+- `pytest -q test/test_read_ldsc_plot_rg.py test/test_viz_compare_effect.py`
+- `pytest -q test/test_io_to_formats.py test/test_report.py`

skills/gwaslab-analysis-and-output/references/source_map.md

@@ -0,0 +1,73 @@
+---
+name: gwaslab-api-and-scripting
+description: Use this skill for GWASLab Sumstats API lifecycle questions, command-line automation, and Python/CLI interoperability in scripted pipelines.
+---
+
+# gwaslab: API and Scripting
+
+## High-Signal Playbook
+### Route Conditions
+- Use this skill for API/CLI method mapping, batch automation, and script reproducibility.
+- Route to `gwaslab-getting-started` for first-run basics.
+- Route to `gwaslab-inputs-and-modeling` for schema and export-only questions.
+- Route to `gwaslab-simulation-workflows` for harmonization/clumping/downstream pipeline design.
+
+### Canonical Workflow
+1. Load with `gl.Sumstats(...)` and run `basic_check()` when needed (`docs/SumstatsObject.md`, `docs/CLI.md`).
+2. Apply analysis/action methods (`harmonize`, `get_lead`, `to_format`) in deterministic order.
+3. Convert the same flow to CLI for batch reproducibility (`docs/CLIWorkflowExamples.md`).
+4. Validate API/CLI parity on a small subset before full runs.
+
+### Minimal API/CLI Parity Check
+```python
+import gwaslab as gl
+
+s = gl.Sumstats("test/raw/dirty_sumstats.tsv", fmt="gwaslab")
+s.basic_check(remove=True, remove_dup=True, verbose=False)
+out = s.get_lead(sig_level=5e-8)
+print(len(s.data), len(out))
+```
+
+```bash
+gwaslab --input test/raw/dirty_sumstats.tsv --fmt gwaslab --qc --remove --remove-dup --out tmp_api_cli_check --to-fmt gwaslab
+```
+
+### Validation Checkpoints
+- API and CLI both complete without parser/runtime errors.
+- Expected core columns remain after `basic_check()`.
+- Output file from CLI exists and reloads via `gl.Sumstats(..., fmt="gwaslab")`.
+
+## Scope
+- Programmatic `gl.Sumstats` lifecycle: load, QC/harmonize, analysis methods, and output.
+- CLI command construction and translation between API and CLI workflows.
+- Script-level reproducibility and batch processing patterns.
+
+## Primary documentation references
+- `docs/SumstatsObject.md`
+- `docs/CLI.md`
+- `docs/CLIWorkflowExamples.md`
+- `docs/format_load_save.md`
+- `docs/tutorial_v4.md`
+
+## Workflow
+- Start with docs above and map requested operation to API or CLI primitive.
+- Prefer API for in-memory chaining/custom logic; prefer CLI for reproducible batch jobs.
+- Use examples in `docs/CLIWorkflowExamples.md` for multi-step scripting templates.
+- If docs are insufficient, inspect `references/doc_map.md`, then `references/source_map.md`.
+- Cite exact doc paths.
+
+## API lifecycle anchors
+- `gl.Sumstats(...)` -> load/normalize input schema.
+- `basic_check(...)` / `harmonize(...)` -> core data-processing stages.
+- `get_lead(...)`, `plot_mqq(...)`, `clump(...)` -> analysis utilities.
+- `to_format(...)` / `to_pickle(...)` -> persistence and interchange.
+
+## Source entry points for unresolved issues
+- `src/gwaslab/g_Sumstats.py`
+- `src/gwaslab/CLI/cli.py`
+- `src/gwaslab/__init__.py`
+- `src/gwaslab/io/io_preformat_input.py`
+- `src/gwaslab/io/io_to_formats.py`
+- `src/gwaslab/hm/hm_harmonize_sumstats.py`
+- `src/gwaslab/util/util_in_fill_data.py`
+- Prefer targeted search: `rg -n "<symbol_or_keyword>" src/gwaslab`

skills/gwaslab-api-and-scripting/SKILL.md

@@ -0,0 +1,15 @@
+# gwaslab documentation map: API and Scripting
+
+Generated from documentation roots:
+- `docs`
+- `examples`
+- `test`
+
+Total docs grouped in this topic: 5
+
+## File inventory
+- `docs/SumstatsObject.md` | title: Sumstats Object in GWASLab | headings: Sumstats Object in GWASLab; gl.Sumstats(); Options
+- `docs/CLI.md` | title: Command Line Interface (CLI) | headings: Command Line Interface (CLI); Basic Usage; Quick Examples
+- `docs/CLIWorkflowExamples.md` | title: CLI Workflow Examples | headings: CLI Workflow Examples; Example 1: Basic QC Pipeline; Example 2: Harmonization Pipeline
+- `docs/format_load_save.md` | title: Input and output sumstats | headings: Input and output sumstats; Input; Loading data
+- `docs/tutorial_v4.md` | title: Tutorial for gwaslab 4.0.0 | headings: Tutorial for gwaslab 4.0.0; Loading data into gwaslab Sumstats; Harmonization