Skip to content

CONFIGURATION.md

Latest commit

 

History

History
199 lines (154 loc) · 12.2 KB

CONFIGURATION.md

File metadata and controls

199 lines (154 loc) · 12.2 KB
Raw

Configuration

pyLocusZoom is a Python library, so most "configuration" is done through keyword arguments passed to the plotting API rather than through environment variables or config files. This document covers the three places where behavior can be configured:

  1. Environment variables that control on-disk cache locations.
  2. Programmatic configuration via the Pydantic models in src/pylocuszoom/config.py.
  3. Project-level configuration declared in pyproject.toml (for developers working on the package itself).

There is no .env file and no runtime configuration file. The library does not read any PYLOCUSZOOM_* environment variables.

Environment Variables

pyLocusZoom honours a small number of standard OS-level environment variables that control where cached reference data (recombination maps, Ensembl gene annotations) is stored. These are the only environment variables the library reads.

Variable Required Default Description
XDG_CACHE_HOME Optional ~/.cache (Linux) / ~/.cache (macOS) Base directory for the cache on Linux. When set, caches are placed under $XDG_CACHE_HOME/pylocuszoom/. Not consulted on macOS by ensembl.get_ensembl_cache_dir().
LOCALAPPDATA Optional %USERPROFILE% (recombination) / %USERPROFILE%\AppData\Local (ensembl) Base directory for the cache on Windows. Caches are placed under %LOCALAPPDATA%\pylocuszoom\.

Resolved cache paths by platform:

Platform Recombination maps Ensembl gene cache
macOS ~/.cache/pylocuszoom/recombination_maps (or $XDG_CACHE_HOME/pylocuszoom/recombination_maps) ~/.cache/pylocuszoom/ensembl
Linux $XDG_CACHE_HOME/pylocuszoom/recombination_maps or ~/.cache/pylocuszoom/recombination_maps $XDG_CACHE_HOME/pylocuszoom/ensembl or ~/.cache/pylocuszoom/ensembl
Windows %LOCALAPPDATA%\pylocuszoom\recombination_maps %LOCALAPPDATA%\pylocuszoom\ensembl
Databricks /dbfs/FileStore/reference_data/recombination_maps (auto-detected when /dbfs exists) Falls through to the Linux/XDG path

Implementation:

You can also override the cache location explicitly by passing output_dir to download_canine_recombination_maps() / ensure_recomb_maps() — this bypasses the environment variables entirely.

Programmatic Configuration (Pydantic Models)

The user-facing API uses plain keyword arguments (plot(), plot_stacked()). Internally these kwargs are validated by frozen Pydantic models defined in src/pylocuszoom/config.py. You normally do not construct these directly, but they define the canonical set of options and their defaults.

RegionConfig — genomic region (required)

Field Type Default Validation
chrom int | str required Integer >= 1, or non-empty string
start int required >= 1 (1-based coordinates)
end int required > 0 and strictly greater than start

ColumnConfig — GWAS DataFrame column names

Field Type Default Description
pos_col str "pos" Position column name
p_col str "p_value" P-value column name
rs_col str "rs" SNP identifier column

DisplayConfig — visual options

Field Type Default Description
snp_labels bool True Draw SNP labels
label_top_n int (>= 0) 5 Number of top SNPs to label
show_recombination bool True Overlay recombination rate track
figsize tuple[float, float] (12.0, 8.0) Figure size in inches (width, height)

LDConfig — linkage disequilibrium

Field Type Default Description
lead_pos int | None None Position of lead SNP (>= 1 when set)
ld_reference_file str | None None Path to PLINK binary fileset
ld_col str | None None Column with pre-computed R² values

Cross-field rules:

  • ld_col and ld_reference_file are mutually exclusive.
  • If ld_reference_file is set, lead_pos is required (enforced on PlotConfig). On StackedPlotConfig a lead_positions list satisfies it instead.

PanelInputs — optional panels beneath the association track

Field Type Default Description
genes_df DataFrame | None None Gene annotations for the gene track
exons_df DataFrame | None None Exon structure drawn within the gene track
recomb_df DataFrame | None None Recombination rates, replacing the map lookup
eqtl_df DataFrame | None None eQTL results for the eQTL panel
eqtl_gene str | None None Filter the eQTL frame to one gene
eqtl_threshold float 1e-5 Significance line on the eQTL panel
finemapping_df DataFrame | None None Fine-mapping results for the PIP panel
finemapping_cs_col str | None "cs" Credible-set column, None for no colouring
ld_heatmap_df DataFrame | None None Square LD matrix for the heatmap panel
ld_heatmap_snp_ids list[str] | None None Row and column SNP ids of the LD matrix
ld_heatmap_height float 0.25 Heatmap height against the association panel
ld_heatmap_metric str "r2" Colour-bar label, "r2" or "dprime"

Cross-field rules:

  • If ld_heatmap_df is set, ld_heatmap_snp_ids is required.

Composite configs

  • PlotConfig composes RegionConfig, ColumnConfig, DisplayConfig, LDConfig, and PanelInputs. plot() builds one from its arguments and the cross-model rules (a PLINK fileset needs a lead) live on it; callers pass the four nested models to plot() and never build the composite.
  • StackedPlotConfig extends the pattern with n_panels and the list-valued lead_positions, panel_labels, and ld_reference_files fields for multi-panel plots. Each list, when set, must hold exactly n_panels entries.
  • ColocConfig covers colocalisation-specific options.

All config models are frozen=True — construct a new instance rather than mutating an existing one.

Required vs Optional Settings

Because configuration is passed at call time, "required" here means "must be supplied when calling plot() / plot_stacked()".

Setting Required? Notes
chrom, start, end Required Validation error if missing or if start >= end.
pos_col, p_col, rs_col Optional Default to the canonical "pos", "p_value", "rs".
lead_pos Required if ld_reference_file set Otherwise optional.
ld_reference_file Optional Mutually exclusive with ld_col.
ld_col Optional Mutually exclusive with ld_reference_file.
snp_labels, label_top_n, show_recombination, figsize Optional Sensible defaults (see table above).

Validation failures raise pydantic.ValidationError at call time.

Defaults Summary

Defaults defined in source (see config.py):

pos_col            = "pos"
p_col              = "p_value"
rs_col             = "rs"
snp_labels         = True
label_top_n        = 5
show_recombination = True
figsize            = (12.0, 8.0)
lead_pos           = None
ld_reference_file  = None
ld_col             = None

Per-Environment Overrides

pyLocusZoom does not distinguish "development" vs "production" environments at runtime — it is a library, not a service. There are no .env.development / .env.production files and no NODE_ENV-style switch.

If you need per-environment behaviour, do it at the caller level, e.g.:

  • Set XDG_CACHE_HOME / LOCALAPPDATA per machine to control where reference data is cached.
  • Pre-download reference data in CI with ensure_recomb_maps() pointing at a shared directory, then set output_dir= accordingly at runtime.
  • On Databricks, the /dbfs/FileStore/reference_data/recombination_maps path is selected automatically.

Project / Developer Configuration

The following settings live in pyproject.toml and only affect contributors working on pyLocusZoom itself (not library users):

Setting Value
requires-python >= 3.10
build-system.requires hatchling==1.29.0
tool.pytest.ini_options.addopts Parallel workers, per-test timeout, coverage, verbose, integration deselected. See pyproject.toml for the exact string.
tool.ruff.line-length 88
tool.ruff.target-version py310
tool.ruff.lint.select ["E", "F", "I", "W"]
tool.ruff.lint.ignore ["E501"]

Optional dependency groups: dev, spark, all (see pyproject.toml).