Plotting (`gl.plot_*`)

Top-level plotting functions exported by import gwaslab as gl. For mysumstats.plot_* methods, see Sumstats → Plot.

`compare_effect`

Compare effect sizes between two GWAS summary-statistics files.

Parameters:

Name	Type	Description	Default
`path1`	`str`	Path to the first summary-statistics file.	required
`path2`	`str`	Path to the second summary-statistics file.	required
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	required
`build`	`str`	Genome build (e.g., '19'/'38') for annotation/coordinate resources.	required
`sig_level`	`float`	Significance threshold for reference line and marker sizing.	`5e-08`
`adjust_text_kwargs`	`Any`	AdjustText kwargs for annotations.	required
`adjust_text_kwargs_l`	`Any`	AdjustText kwargs (left side).	required
`adjust_text_kwargs_r`	`Any`	AdjustText kwargs (right side).	required
`allele_match`	`Any`	Align alleles before comparison.	required
`anno`	`bool`	Annotation source or column (e.g., 'GENENAME', True, or column name).	`False`
`anno_diff`	`Any`	Annotation difference threshold.	required
`anno_het`	`Any`	Enable heterogeneity annotation.	required
`anno_kwargs`	`dict`	Default styling kwargs for annotations.	`{}`
`anno_kwargs_single`	`dict`	Per-SNP styling kwargs for annotations.	`{}`
`anno_max_iter`	`int`	Maximum iterations for text repulsion algorithm.	`100`
`anno_max_rows`	`int`	Maximum number of annotation rows to display. If more variants are provided, they will be sorted by p-value or -log10(p-value) and only the top ones will be shown.	`40`
`anno_min`	`Any`	Minimum -log10(P) for annotation.	required
`anno_min1`	`Any`	Min threshold for series 1 annotation.	required
`anno_min2`	`Any`	Min threshold for series 2 annotation.	required
`anno_set`	`list`	Set of variant IDs to annotate.	`[]`
`clean_output`	`Any`	clean_output.	required
`drop`	`Any`	Drop variants by condition.	required
`err_kwargs`	`dict`	Errorbar styling kwargs.	`{'ecolor': '#cccccc', 'elinewidth': 1}`
`fdr`	`Any`	fdr.	required
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [8, 8], 'dpi': 200}`
`font_kwargs`	`dict`	Font configuration kwargs.	`{'fontsize': 9}`
`get_lead_kwargs`	`dict`	Kwargs for extracting lead variants.	`{}`
`helper_line_kwargs`	`dict`	45-degree helper line styling for AF comparison.	`{'color': 'black', 'linestyle': '-', 'lw': 1}`
`highlight`	`list`	List of focal variants to highlight.	`[]`
`include_all`	`Any`	Include all variants for plotting.	required
`is_45_helper_line`	`Any`	Draw 45-degree helper line.	required
`is_q`	`Any`	Treat inputs as odds ratios.	required
`is_q_mc`	`Any`	Monte Carlo mode for OR inputs.	required
`is_reg`	`Any`	Enable regression line computation.	required
`label`	`Any`	Legend labels or series labels.	required
`legend_kwargs`	`dict`	Legend styling kwargs.	`{}`
`legend_mode`	`Any`	Legend layout: int code (plot_effect) or string mode (compare_effect).	required
`legend_pos`	`str`	Legend position.	`'upper left'`
`legend_title`	`str`	Legend title.	`'$\\mathregular{ P < 5 x 10^{-8}}$ in:'`
`legend_title2`	`str`	Second legend title.	`'Heterogeneity test:'`
`maf_level`	`Any`	Minor allele frequency stratification level.	required
`null_beta`	`int`	Null beta for hypothesis testing.	`0`
`q_level`	`Any`	Quantile level for thresholds.	required
`r_or_r2`	`str`	Show r or r^2 statistic.	`'r2'`
`r_se`	`bool`	Show regression standard error.	`False`
`reg_box`	`Any`	Draw regression stats box.	required
`reg_text`	`Any`	Custom text for regression box.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	`False`
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`save_merged`	`bool`	save_merged.	`False`
`scaled`	`bool`	Auto-detected when scaled effect columns exist; not a direct plot kwarg.	`False`
`scaled1`	`bool`	Study-1 scaling flag (legacy registry entry; detected from columns).	`False`
`scaled2`	`bool`	Study-2 scaling flag (legacy registry entry; detected from columns).	`False`
`scatter_kwargs`	`dict`	Extra kwargs passed to the main scatter layer (matplotlib Axes.scatter). Use marker_size for point sizes, not s/size.	`{'s': 20}`
`snplist`	`Any`	List of SNPs to include.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`wc_correction`	`Any`	Winner's curse correction toggle.	required
`wc_sig_level`	`Any`	Significance threshold for WC correction.	required
`xylabel_prefix`	`Any`	Prefix for axis labels.	required

`plot_forest`

Forest plot for meta-analysis study effects.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame or Sumstats`	Study-level effect summary table.	required
`beta_col`	`Any`	Column name for effect size in forest plot.	required
`colors`	`list`	Color palette or list.	`['#597FBD', '#74BAD3']`
`combine_effects_kwargs`	`Any`	combine_effects_kwargs.	required
`compact_factor`	`Any`	compact_factor.	required
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [15, 5], 'dpi': 300}`
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`group_col`	`Any`	group_col.	required
`meta`	`Any`	meta.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	`False`
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	`{'dpi': 300, 'facecolor': 'white'}`
`se_col`	`Any`	Column name for standard error in forest plot.	required
`sharex`	`Any`	sharex.	required
`study_col`	`Any`	study_col.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`width_ratios`	`Any`	width_ratios.	required

Returns:

Type	Description
`tuple`	(fig, axes) where fig is matplotlib Figure and axes is list of axes

`plot_ld_block`

LD block as a 45-degree rotated inverted triangle from LD matrix or VCF.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	required
`region`	`tuple or str`	Genomic locus as (chr, start, end) in base pairs.	required
`vcf_path`	`str`	Reference-panel VCF for LD r² computation.	required
`anno_cell`	`bool`	Annotate LD block matrix cells with r² values.	`False`
`anno_cell_fmt`	`str`	Format string for LD cell annotations (e.g., '{:.2f}' for 2 decimal places).	`'{:.2f}'`
`anno_cell_kwargs`	`Any`	Additional keyword arguments for LD cell text annotations (e.g., {'fontsize': 10, 'weight': 'bold', 'color': 'white'}).	required
`ax`	`Any`	ax.	required
`ax_pos`	`Any`	ax_pos.	required
`cbar`	`bool`	cbar.	`True`
`cbar_kwargs`	`Any`	cbar_kwargs.	required
`cbar_label`	`str`	cbar_label.	`'LD $\\mathregular{r^2}$ with variant'`
`cmap`	`Any`	Colormap selection.	required
`ea_col`	`str`	ea_col.	`'EA'`
`fig_kwargs`	`dict`	Figure kwargs for plot.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`10`
`ld`	`Any`	ld.	required
`ld_block_anno`	`bool`	Whether to add annotations on the left side of the LD block triangle. If True, uses 'chr:pos' format. If a string (e.g., 'SNPID', 'rsID'), uses that column for annotation text. Annotations are styled like axis ticks and labels, with right-aligned text.	`False`
`ld_block_anno_kwargs`	`Any`	Additional keyword arguments for left-side annotations (e.g., {'fontsize': 8, 'color': 'black'}).	required
`ld_block_anno_max_rows`	`int`	Maximum number of variants to annotate. If the number of variants to annotate exceeds this limit, annotations will be skipped.	`100`
`ld_block_anno_set`	`Any`	List of SNPIDs to annotate. If None, annotates all variants. Variants are matched by SNPID column.	required
`ld_block_grid`	`bool`	Draw grid lines on the LD matrix triangle panel.	`False`
`ld_block_grid_kwargs`	`Any`	Additional keyword arguments for LD block grid lines (e.g., {'color': 'gray', 'linewidth': 0.5, 'alpha': 0.5}).	required
`lead_snp_is`	`Any`	lead_snp_is.	required
`lead_snp_is_color`	`str or list`	lead_snp_is_color.	required
`mapper`	`Any`	mapper.	required
`nea_col`	`str`	nea_col.	`'NEA'`
`pos`	`str`	Base-pair position column used with `chrom` for plotting.	`'POS'`
`pos_col`	`str`	pos_col.	`'POS'`
`position_bar_bg`	`bool`	position_bar_bg.	`True`
`region_step`	`int`	Number of major tick intervals on the locus x-axis.	`21`
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sumstats`	`Any`	Sumstats or DataFrame for LD block when using vcf_path+region.	required
`tabix`	`Any`	Tabix index path for fast IO.	required
`title`	`str`	Figure title text.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`vmax`	`float`	vmax.	`1.0`
`vmin`	`float`	vmin.	`0.0`
`xlabel`	`str`	X-axis label.	`'Genomic position'`

Returns:

Type	Description
`matplotlib.figure.Figure`	Figure object. matplotlib.axes.Axes Axes object.

`plot_lead_overlap`

Venn/UpSet overlap of lead loci across studies.

Parameters:

Name	Type	Description	Default
`objects`	`list`	Sumstats objects or lead-variant tables to compare.	required
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	`'auto'`
`build`	`str`	Genome build (e.g., '19'/'38') for annotation/coordinate resources.	required
`sig_level`	`float`	Significance threshold for reference line and marker sizing.	`5e-08`
`anno`	`bool`	Annotation source or column (e.g., 'GENENAME', True, or column name).	`True`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [8, 6], 'dpi': 200}`
`font_kwargs`	`dict`	Font configuration kwargs.	`{'fontsize': 9}`
`get_lead_kwargs`	`dict`	Kwargs for extracting lead variants.	`{}`
`gtf_path`	`str`	Gene annotation GTF for the track below the locus.	`'default'`
`legend_kwargs`	`dict`	Legend styling kwargs.	`{}`
`max_gene_labels`	`int`	max_gene_labels.	`30`
`objects`	`Any`	objects.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	`False`
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`show_counts`	`bool`	show_counts.	`True`
`show_genes`	`bool`	show_genes.	`True`
`sort_by`	`str`	sort_by.	`'count'`
`source`	`str`	source.	`'ensembl'`
`title`	`str`	Figure title text.	required
`titles`	`Any`	Pair plot titles.	required
`upset_kwargs`	`Any`	upset_kwargs.	required
`use_p`	`bool`	use_p.	`False`
`venn_kwargs`	`Any`	venn_kwargs.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`wc_correction`	`bool`	Winner's curse correction toggle.	`False`
`windowsizekb`	`int`	Window size for lead variant extraction (kb).	`500`
`windowsizekb_for_overlap`	`int`	windowsizekb_for_overlap.	`1000`

Returns:

Type	Description
`list`	`[overlap_df, fig, log]`. `overlap_df` has one row per locus group with columns such as `MEMBERSHIP_KEY`, `N_STUDIES`, `GENE`, and `IN_<study>`. For UpSet plots, `overlap_df.attrs["set_list"]` maps set IDs to memberships.

`plot_miami2`

Mirrored Manhattan plot comparing two traits or studies.

Parameters:

Name	Type	Description	Default
`path1`	`str`	Path to the first summary-statistics file.	`None`
`path2`	`str`	Path to the second summary-statistics file.	`None`
`merged_sumstats`	`DataFrame or Sumstats`	Pre-merged sumstats instead of two files.	`None`
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	`'m'`
`build`	`str`	Genome build (e.g., '19'/'38') for annotation/coordinate resources.	required
`sig_level`	`float`	Significance threshold for reference line and marker sizing.	`5e-08`
`anno_sig_level`	`float`	Significance level for extracting lead variants to annotate. Can be set independently from sig_level.	`5e-08`
`skip`	`int`	Minimum -log10(P) for variants shown on the plot (variants below this are omitted).	`0`
`cut`	`int`	Cap variant -log10(P) display above this value (squashes extreme peaks for layout).	`0`
`marker_size`	`list`	Scatter marker size. Use an int for fixed size, or a (small, large) tuple for variants below/above sig_level.	`[5, 20]`
`additional_line`	`Any`	Additional reference lines.	required
`additional_line_color`	`str or list`	Colors for additional lines.	required
`anno`	`DataFrame or list`	Annotation source or column (e.g., 'GENENAME', True, or column name).	required
`anno_adjust`	`bool`	Enable annotation position adjustment.	`False`
`anno_alias`	`dict`	Mapping from SNPID to custom annotation label.	`{}`
`anno_d`	`dict`	Per-annotation positioning options (e.g., left/right).	`{}`
`anno_fixed_arm_length`	`Any`	Fixed arm length for annotations.	required
`anno_fontsize`	`int`	Font size for annotation text.	`9`
`anno_gtf_path`	`str`	Custom GTF path for annotations.	required
`anno_height`	`int`	Height for annotations.	`1`
`anno_kwargs`	`dict`	Default styling kwargs for annotations.	`{}`
`anno_kwargs_single`	`dict`	Per-SNP styling kwargs for annotations.	`{}`
`anno_max_iter`	`int`	Maximum iterations for text repulsion algorithm.	`100`
`anno_max_rows`	`int`	Maximum number of annotation rows to display. If more variants are provided, they will be sorted by p-value or -log10(p-value) and only the top ones will be shown.	`40`
`anno_set`	`list`	Set of variant IDs to annotate.	`[]`
`anno_source`	`str`	Annotation source backend (e.g., 'ensembl', 'refseq').	`'ensembl'`
`anno_style`	`str`	Annotation style ('right', 'tight', 'expand').	`'right'`
`anno_xshift`	`Any`	X-axis shift applied to annotations.	required
`arm_offset`	`Any`	Offset for annotation arms.	required
`arm_scale`	`int`	Scaling factor for arm length.	`1`
`arm_scale_d`	`dict`	Per-annotation arm scaling dict.	`{}`
`arrow_kwargs`	`dict`	Arrow styling kwargs for annotations.	`{}`
`chr_dict`	`Any`	Chromosome number/name mapping.	required
`chr_dict1`	`Any`	chr_dict1.	required
`chr_dict2`	`Any`	chr_dict2.	required
`chrpad`	`float`	Chromosome padding proportion.	`0.03`
`colors`	`list`	Color palette or list.	`['#597FBD', '#74BAD3']`
`cols`	`Any`	cols.	required
`cols1`	`Any`	cols1.	required
`cols2`	`Any`	cols2.	required
`cut_line_color`	`str or list`	Color for shrink line.	required
`cut_log`	`bool`	Use log scale for cut line.	`False`
`cutfactor`	`int`	Factor for shrink line.	`10`
`dpi`	`int`	Figure DPI.	`200`
`expected_min_mlog10p`	`int`	Expected minimum -log10(P) adjustment.	`0`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [15, 10], 'dpi': 200}`
`figax`	`Any`	Existing figure/axes tuple to draw on.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`highlight`	`list`	List of focal variants to highlight.	`[]`
`highlight_anno_kwargs`	`dict`	Annotation style kwargs for highlighted variants.	`{}`
`highlight_chrpos`	`bool`	Highlight by chromosome position flag.	`False`
`highlight_color`	`str or list`	Highlight color.	required
`highlight_lim`	`Any`	Custom highlight limits.	required
`highlight_lim_mode`	`str`	Highlight limit mode ('absolute'\|'relative').	`'absolute'`
`highlight_windowkb`	`int`	Highlight window size (kb).	`500`
`id0`	`Any`	Identifier for miami plot pair base.	required
`id1`	`Any`	Identifier for series 1.	required
`id2`	`Any`	Identifier for series 2.	required
`jagged`	`bool`	Enable jagged axis break markers.	`False`
`jagged_len`	`float`	Jagged marker length.	`0.01`
`jagged_wid`	`float`	Jagged marker width.	`0.01`
`pinpoint`	`list`	Variants to pinpoint.	`[]`
`pinpoint_color`	`str or list`	Color for pinpoint.	required
`qq_line_color`	`str or list`	Reference line color for QQ plot (e.g., 'grey').	required
`qq_scatter_kwargs`	`dict`	Style dict for QQ scatter (e.g., marker, s, edgecolor).	`{}`
`qq_xlabels`	`Any`	Custom x-axis tick labels for QQ plot.	required
`qq_xlim`	`Any`	X-axis limits for QQ plot, e.g., (min, max).	required
`repel_force`	`float`	Text repulsion force parameter.	`0.03`
`same_ylim`	`Any`	Use same ylim across panels.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	`False`
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sc_linewidth`	`int`	Line width for significance lines.	`2`
`scaled`	`bool`	Auto-detected when scaled effect columns exist; not a direct plot kwarg.	`False`
`scaled1`	`bool`	Study-1 scaling flag (legacy registry entry; detected from columns).	`False`
`scaled2`	`bool`	Study-2 scaling flag (legacy registry entry; detected from columns).	`False`
`scatter_kwargs`	`dict`	Extra kwargs passed to the main scatter layer (matplotlib Axes.scatter). Use marker_size for point sizes, not s/size.	`{'s': 20}`
`sig_line`	`bool`	Whether to draw significance reference line.	`True`
`sig_line_color`	`str or list`	Significance line color.	required
`suffixes`	`Any`	suffixes.	required
`suggestive_sig_level`	`float`	Suggestive threshold value, e.g., 5e-6.	`5e-06`
`suggestive_sig_line`	`bool`	Whether to draw suggestive threshold line (e.g., 5e-6).	`False`
`suggestive_sig_line_color`	`str or list`	Suggestive significance line color.	required
`title`	`str`	Figure title text.	required
`title_fontsize`	`int`	Title font size.	`13`
`title_pad`	`float`	Title padding.	`1.08`
`titles`	`Any`	Pair plot titles.	required
`titles_pad`	`Any`	Title padding configuration.	required
`use_rank`	`bool`	Use rank for chrom indexing.	`False`
`verbose`	`bool`	Verbose logging toggle.	`True`
`xlabel`	`Any`	X-axis label.	required
`xlabel_coords`	`list`	X label position adjustment.	`[-0.01, -0.05]`
`xpad`	`Any`	X padding proportion.	required
`xpadl`	`Any`	Left X padding.	required
`xpadr`	`Any`	Right X padding.	required
`xtick_chr_dict`	`Any`	X-axis tick chromosome mapping.	required
`xtick_label_pad`	`int`	Pad between x tick and label.	`0`
`xtick_label_size`	`int`	X tick label size.	`10`
`xtickpad`	`Any`	X tick pad.	required
`xtight`	`bool`	Tight X padding.	`False`
`ylabel`	`Any`	Y-axis label.	required
`ylabels`	`Any`	Custom y-axis labels.	required
`ylim`	`Any`	Y-axis limits.	required
`ystep`	`int`	Step size for y-axis.	`0`
`ytick3`	`bool`	Use 3 y-axis ticks.	`True`

`plot_panels`

Stack multi-panel figure from Panel objects.

Parameters:

Name	Type	Description	Default
`panels`	`list`	Panel layout objects from :class:`gwaslab.Panel`.	required
`region`	`tuple or str`	Genomic locus as (chr, start, end) in base pairs.	required
`align_xaxis`	`bool`	Share genomic x-axis limits across stacked panels.	`True`
`fig_kwargs`	`dict`	Figure kwargs for plot.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`9`
`height_ratios`	`Any`	Panel height ratios.	required
`hspace`	`float`	Vertical space between panels.	`0.1`
`region_step`	`int`	Number of major tick intervals on the locus x-axis.	`21`
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`subplot_height`	`float`	subplot_height.	`1.0`
`title_kwargs`	`Any`	Title styling kwargs (e.g., family, fontsize, weight).	required
`title_pos`	`str`	Title position in axes coordinates (x, y).	`'left'`
`titles`	`Any`	Pair plot titles.	required
`track_start_i`	`float`	track_start_i.	`0.0`
`variant_line_kwargs`	`Any`	Style kwargs for variant guide lines.	required
`variant_positions`	`Any`	Genomic positions for vertical guide lines in plot_panels.	required
`verbose`	`bool`	Verbose logging toggle.	`True`

Returns:

Type	Description
`matplotlib.figure.Figure`	The created matplotlib figure object. list of matplotlib.axes.Axes One axes object per panel.

`plot_power`

Theoretical GWAS power curves (mode='q' quantitative or 'b' binary).

Parameters:

Name	Type	Description	Default
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	`'q'`
`beta_range`	`Any`	Beta range for power computation.	required
`betas`	`Any`	Effect-size grid for plot_power_x.	required
`cmap`	`Any`	Colormap selection.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`maf_range`	`Any`	MAF range for power computation.	required
`mafs`	`Any`	MAF grid for plot_power_x.	required
`n_matrix`	`int`	Power curve smoothness parameter.	`1000`
`ncases`	`Any`	Case count(s) for binary power curves.	required
`ncontrols`	`Any`	Control count(s) for binary power curves.	required
`ns`	`Any`	Sample size(s) for theoretical power curves.	required
`or_to_rr`	`bool`	Convert OR to RR.	`False`
`prevalences`	`Any`	Prevalence value(s) for binary power curves.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sig_levels`	`float`	Significance levels.	`5e-08`
`sizes`	`Any`	Size list for style mapping.	required
`ts`	`Any`	Power thresholds to plot.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`xlabel`	`Any`	X-axis label.	required
`xscale`	`str`	X-axis scale.	`'log'`
`xticklabels`	`Any`	Custom x-axis tick labels.	required
`xticks`	`Any`	Custom x-axis ticks.	required
`ylabel`	`Any`	Y-axis label.	required
`ylim`	`Any`	Y-axis limits.	required
`yscale_factor`	`int`	Y scale factor.	`1`
`yticklabels`	`Any`	Custom y-axis tick labels.	required
`yticks`	`Any`	Custom y-axis ticks.	required

Returns:

Type	Description
`matplotlib.figure.Figure`	The generated power curve plot figure

`plot_power_x`

Extended power curves with custom MAF/beta grids.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	`'q'`
`beta_range`	`Any`	Beta range for power computation.	required
`betas`	`Any`	Effect-size grid for plot_power_x.	required
`cmap`	`Any`	Colormap selection.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`maf_range`	`Any`	MAF range for power computation.	required
`mafs`	`Any`	MAF grid for plot_power_x.	required
`n_matrix`	`int`	Power curve smoothness parameter.	`1000`
`n_range`	`Any`	n_range.	required
`ncases`	`Any`	Case count(s) for binary power curves.	required
`ncontrols`	`Any`	Control count(s) for binary power curves.	required
`ns`	`Any`	Sample size(s) for theoretical power curves.	required
`or_to_rr`	`bool`	Convert OR to RR.	`False`
`prevalence_range`	`Any`	prevalence_range.	required
`prevalences`	`Any`	Prevalence value(s) for binary power curves.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sig_levels`	`float`	Significance levels.	`5e-08`
`ts`	`Any`	Power thresholds to plot.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`xlabel`	`Any`	X-axis label.	required
`xscale`	`str`	X-axis scale.	`'log'`
`xticklabels`	`Any`	Custom x-axis tick labels.	required
`xticks`	`Any`	Custom x-axis ticks.	required
`ylabel`	`Any`	Y-axis label.	required
`ylim`	`Any`	Y-axis limits.	required
`yscale_factor`	`int`	Y scale factor.	`1`
`yticklabels`	`Any`	Custom y-axis tick labels.	required
`yticks`	`Any`	Custom y-axis ticks.	required

Returns:

Type	Description
`matplotlib.figure.Figure or None`	Power curve figure, or `None` when required inputs are missing.

`plot_rg`

Genetic correlation heatmap from LDSC results.

Parameters:

Name	Type	Description	Default
`ldscrg`	`str or DataFrame`	LDSC genetic-correlation log or parsed results table.	required
`asize`	`int`	Annotation size.	`10`
`cmap`	`Any`	Colormap selection.	required
`colorbar_kwargs`	`dict`	Colorbar kwargs.	`{'shrink': 0.82}`
`corrections`	`list`	Multiple testing corrections.	`['non', 'fdr', 'bon']`
`equal_aspect`	`bool`	Keep equal aspect ratio.	`True`
`fdr_method`	`str`	FDR correction method.	`'bh'`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'dpi': 300}`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`full_cell`	`list`	Fill full cell when significant.	`['fdr', 0.05]`
`p`	`str`	P-value column.	`'p'`
`p1`	`str`	Trait column 1.	`'p1'`
`p2`	`str`	Trait column 2.	`'p2'`
`panno`	`bool`	Enable p-value annotation.	`True`
`panno_kwargs`	`dict`	P-value annotation kwargs.	`{}`
`panno_texts`	`Any`	Texts for p-value annotation.	required
`rg`	`str`	Genetic correlation value column.	`'rg'`
`rganno`	`str`	RG annotation mode.	`'non'`
`rganno_kwargs`	`Any`	RG annotation kwargs.	required
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sig_levels`	`list`	Significance levels.	`[0.05]`
`sort_key`	`Any`	Sort key function.	required
`square`	`bool`	Square cells toggle.	`False`
`verbose`	`bool`	Verbose logging toggle.	`True`
`xticklabel_kwargs`	`dict`	X ticklabel kwargs.	`{'rotation': 45, 'horizontalalignment': 'left', 'verticalalignment': 'bottom', 'fontsize': 10, 'fontfamily': 'Arial'}`
`yticklabel_kwargs`	`dict`	Matplotlib kwargs for LDSC rg heatmap y-axis tick labels (rotation, fontsize, …).	`{'fontsize': 10, 'fontfamily': 'Arial'}`

`plot_sankey`

Sankey / alluvial diagram from categorical sumstats columns.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame or Sumstats`	Input sumstats with categorical columns.	required
`columns`	`list of str`	Column names defining Sankey stages (required).	required
`beta_bins`	`Any`	beta_bins.	required
`color_by`	`str`	color_by.	`'first'`
`colors`	`list`	Color palette or list.	`['#597FBD', '#74BAD3']`
`column_map`	`Any`	column_map.	required
`dropna`	`bool`	dropna.	`True`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [10, 6], 'dpi': 300}`
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`12`
`gap_frac`	`float`	gap_frac.	`0.02`
`link_alpha`	`float`	link_alpha.	`0.55`
`node_color_mode`	`str`	node_color_mode.	`'stacked'`
`node_width`	`float`	node_width.	`0.025`
`palette`	`str`	Color palette name or list.	`'auto'`
`ribbon_curvature`	`float`	ribbon_curvature.	`0.5`
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	`False`
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	`{'dpi': 300, 'facecolor': 'white'}`
`stage_labels`	`Any`	stage_labels.	required
`title`	`str`	Figure title text.	required
`verbose`	`bool`	Verbose logging toggle.	`True`
`weight`	`str`	weight.	`'count'`

Returns:

Type	Description
`tuple`	`(fig, ax, tables)` where `tables` contains `nodes`, `links`, `node_bands`, `flow_colors`, `stages`, and `work`. Returns `(None, None, tables)` when no rows remain after filtering.

`plot_stacked_mqq`

Stacked Manhattan/QQ/regional panels from multiple Sumstats objects.

Parameters:

Name	Type	Description	Default
`objects`	`list`	Sumstats objects to stack in one figure.	required
`mode`	`str`	Plot layout mode. Values depend on the plot function; see ctx_desc.	`'r'`
`region`	`tuple or str`	Genomic locus as (chr, start, end) in base pairs.	required
`build`	`str`	Genome build (e.g., '19'/'38') for annotation/coordinate resources.	`'99'`
`sig_level`	`float`	Significance threshold for reference line and marker sizing.	`5e-08`
`anno_sig_level`	`float`	Significance level for extracting lead variants to annotate. Can be set independently from sig_level.	`5e-08`
`skip`	`int`	Minimum -log10(P) for variants shown on the plot (variants below this are omitted).	`0`
`cut`	`int`	Cap variant -log10(P) display above this value (squashes extreme peaks for layout).	`0`
`marker_size`	`list`	Scatter marker size. Use an int for fixed size, or a (small, large) tuple for variants below/above sig_level.	required
`vcf_path`	`str`	Reference-panel VCF for LD r² computation.	required
`ld_block`	`bool`	Add rotated LD matrix (lower triangle) panel below the locus.	`False`
`ld_link`	`bool`	Draw straight lines between variant pairs with LD r² ≥ region_ld_threshold[0].	`False`
`additional_line`	`Any`	Additional reference lines.	required
`additional_line_color`	`str or list`	Colors for additional lines.	required
`anno`	`DataFrame or list`	Annotation source or column (e.g., 'GENENAME', True, or column name).	required
`anno_adjust`	`bool`	Enable annotation position adjustment.	`False`
`anno_alias`	`dict`	Mapping from SNPID to custom annotation label.	`{}`
`anno_cell`	`bool`	Annotate LD block matrix cells with r² values.	`False`
`anno_cell_fmt`	`str`	Format string for LD cell annotations (e.g., '{:.2f}' for 2 decimal places).	`'{:.2f}'`
`anno_cell_kwargs`	`Any`	Additional keyword arguments for LD cell text annotations (e.g., {'fontsize': 10, 'weight': 'bold', 'color': 'white'}).	required
`anno_d`	`dict`	Per-annotation positioning options (e.g., left/right).	`{}`
`anno_fixed_arm_length`	`Any`	Fixed arm length for annotations.	required
`anno_fontsize`	`int`	Font size for annotation text.	`9`
`anno_gtf_path`	`str`	Custom GTF path for annotations.	required
`anno_height`	`int`	Height for annotations.	`1`
`anno_kwargs`	`dict`	Default styling kwargs for annotations.	`{}`
`anno_kwargs_single`	`dict`	Per-SNP styling kwargs for annotations.	`{}`
`anno_max_iter`	`int`	Maximum iterations for text repulsion algorithm.	`100`
`anno_max_rows`	`int`	Maximum number of annotation rows to display. If more variants are provided, they will be sorted by p-value or -log10(p-value) and only the top ones will be shown.	`40`
`anno_set`	`list`	Set of variant IDs to annotate.	`[]`
`anno_source`	`str`	Annotation source backend (e.g., 'ensembl', 'refseq').	`'ensembl'`
`anno_style`	`str`	Annotation style ('right', 'tight', 'expand').	`'right'`
`anno_xshift`	`Any`	X-axis shift applied to annotations.	required
`arm_offset`	`Any`	Offset for annotation arms.	required
`arm_scale`	`int`	Scaling factor for arm length.	`1`
`arm_scale_d`	`dict`	Per-annotation arm scaling dict.	`{}`
`arrow_kwargs`	`dict`	Arrow styling kwargs for annotations.	`{}`
`bwindowsizekb`	`int`	Window size in kilobases for density computation.	`100`
`cbar_bbox_to_anchor`	`list`	Colorbar bbox_to_anchor.	`[0, 0, 1, 1]`
`cbar_borderpad`	`Any`	Colorbar border padding.	required
`cbar_downward_offset`	`float`	Colorbar downward offset.	`1.3`
`cbar_equal_aspect`	`bool`	Equal aspect for colorbar.	`True`
`cbar_font_family`	`str`	Colorbar font family.	`'Arial'`
`cbar_fontsize`	`int`	Colorbar font size.	`12`
`cbar_h_scale`	`int`	Colorbar height scale.	`1`
`cbar_scale`	`bool`	Scale colorbar.	`True`
`cbar_title`	`str`	Title text for the LD r² colorbar inset.	`'LD $\\mathregular{r^2}$ with variant'`
`cbar_w_scale`	`int`	Colorbar width scale.	`1`
`check`	`bool`	Enable input QC and normalization.	`True`
`chr_dict`	`Any`	Chromosome number/name mapping.	required
`chrom`	`str`	Chromosome column used to position variants and x-axis layout.	`'CHR'`
`chrpad`	`float`	Chromosome padding proportion.	`0.03`
`colors`	`list`	Color palette or list.	`['#597FBD', '#74BAD3']`
`common_ylabel`	`bool`	common_ylabel.	`True`
`cs_height`	`float`	cs_height.	`0.5`
`cut_line_color`	`str or list`	Color for shrink line.	required
`cut_log`	`bool`	Use log scale for cut line.	`False`
`cutfactor`	`int`	Factor for shrink line.	`10`
`density_color`	`str or list`	Density palette or boolean to control density track colors.	required
`density_palette`	`str`	Density palette.	`'Reds'`
`density_range`	`Any`	Density value range.	required
`density_threshold`	`int`	Threshold for density highlighting.	`5`
`density_tpalette`	`str`	Palette for threshold coloring.	`'Blues'`
`density_trange`	`list`	Threshold range.	`[0, 10]`
`dpi`	`int`	Figure DPI.	`200`
`drop_chr_start`	`bool`	Drop chromosome start.	`False`
`ea`	`str`	Effect allele column.	`'EA'`
`eaf`	`str`	Effect allele frequency column.	`'EAF'`
`expected_min_mlog10p`	`int`	Expected minimum -log10(P) adjustment.	`0`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'dpi': 200}`
`figax`	`Any`	Existing figure/axes tuple to draw on.	required
`font_family`	`str`	Font family, e.g., 'Arial', for consistent styling.	`'Arial'`
`fontfamily`	`str`	Font family alias.	`'Arial'`
`fontsize`	`int`	Font size for ticks, labels, etc.	`9`
`gc`	`bool`	Compute genomic control lambda.	`True`
`gene_track_height`	`float`	gene_track_height.	`0.5`
`gtf`	`Any`	gtf.	required
`gtf_chr_dict`	`Any`	GTF chromosome dictionary.	required
`gtf_gene_name`	`Any`	GTF gene name column.	required
`gtf_path`	`str`	Gene annotation GTF for the track below the locus.	`'default'`
`highlight`	`list`	List of focal variants to highlight.	`[]`
`highlight_anno_kwargs`	`dict`	Annotation style kwargs for highlighted variants.	`{}`
`highlight_chrpos`	`bool`	Highlight by chromosome position flag.	`False`
`highlight_color`	`str or list`	Highlight color.	required
`highlight_lim`	`Any`	Custom highlight limits.	required
`highlight_lim_mode`	`str`	Highlight limit mode ('absolute'\|'relative').	`'absolute'`
`highlight_windowkb`	`int`	Highlight window size (kb).	`500`
`include_chrXYMT`	`bool`	Include sex/MT chromosomes in QQ.	`True`
`jagged`	`bool`	Enable jagged axis break markers.	`False`
`jagged_len`	`float`	Jagged marker length.	`0.01`
`jagged_wid`	`float`	Jagged marker width.	`0.01`
`ld_block_grid`	`bool`	Draw grid lines on the LD matrix triangle panel.	`False`
`ld_block_grid_kwargs`	`Any`	Additional keyword arguments for LD block grid lines (e.g., {'color': 'gray', 'linewidth': 0.5, 'alpha': 0.5}).	required
`ld_fmt`	`str`	LD format identifier (e.g., 'npz').	`'npz'`
`ld_if_add_T`	`bool`	Add transpose when composing LD.	`False`
`ld_if_square`	`bool`	Treat LD matrix as square.	`False`
`ld_link_alpha_scale`	`float`	Scale line alpha as min(r² × scale, 1.0) for ld_link segments.	`0.2`
`ld_link_color`	`str or list`	API placeholder; ld_link colors follow region_ld_colors, not this parameter.	required
`ld_link_linewidth`	`float`	Line width for all ld_link segments.	`1.0`
`ld_link_sig_level`	`Any`	P-value cutoff for ld_link pairs; at least one variant in the pair must pass.	required
`ld_link_thr`	`float`	API placeholder; minimum ld_link pair r² is region_ld_threshold[0], not this value.	`0.8`
`ld_map_kwargs`	`Any`	Extra kwargs for LD map loader.	required
`ld_map_path`	`str`	Path to LD map file.	required
`ld_map_rename_dic`	`Any`	Rename dictionary for LD map columns.	required
`ld_path`	`str`	Precomputed LD matrix path (alternative to vcf_path).	required
`maf_bin_colors`	`str or list`	Colors for MAF bins.	required
`maf_bins`	`list`	MAF bin definitions for stratified QQ.	`[[0, 0.01], [0.01, 0.05], [0.05, 0.25], [0.25, 0.5]]`
`math_fontfamily`	`str`	Math text font family.	`'dejavusans'`
`mlog10p`	`str`	Negative log10 p-value column; improves performance and stability if provided.	`'MLOG10P'`
`mqq_height`	`int`	mqq_height.	`1`
`mqqratio`	`int`	Layout ratio for combined Manhattan-QQ plot.	`3`
`mtitle`	`Any`	Manhattan title.	required
`mtitle_pad`	`float`	Manhattan title padding.	`1.08`
`nea`	`str`	Non-effect allele column.	`'NEA'`
`objects`	`Any`	objects.	required
`p`	`str`	P-value column.	`'P'`
`pinpoint`	`list`	Variants to pinpoint.	`[]`
`pinpoint_color`	`str or list`	Color for pinpoint.	required
`pm`	`Any`	pm.	required
`pos`	`str`	Base-pair position column used with `chrom` for plotting.	`'POS'`
`qq_line_color`	`str or list`	Reference line color for QQ plot (e.g., 'grey').	required
`qq_scatter_kwargs`	`dict`	Style dict for QQ scatter (e.g., marker, s, edgecolor).	`{}`
`qq_xlabels`	`Any`	Custom x-axis tick labels for QQ plot.	required
`qq_xlim`	`Any`	X-axis limits for QQ plot, e.g., (min, max).	required
`qqscatterargs`	`Any`	QQ scatter kwargs alias.	required
`qtitle`	`Any`	Manhattan/QQ combined title.	required
`qtitle_pad`	`float`	QQ title padding.	`1.08`
`region_anno_bbox_kwargs`	`dict`	Annotation bbox kwargs for region.	`{'ec': 'None', 'fc': 'None'}`
`region_chromatin_files`	`Any`	region_chromatin_files.	required
`region_chromatin_height`	`float`	region_chromatin_height.	`0.1`
`region_flank_factor`	`Any`	Fraction of locus width added as padding on each side.	required
`region_grid`	`bool`	Vertical grid lines at genomic tick positions on the locus scatter panel.	`False`
`region_grid_line`	`dict`	Grid line style for regional plot.	`{'linewidth': 2, 'linestyle': '--'}`
`region_hspace`	`float`	Vertical gap between scatter, recombination, and gene tracks.	`0.07`
`region_ld_colors`	`str or list`	Colors for LD r² bins (single-reference); paired with region_ld_threshold.	required
`region_ld_colors_m`	`list`	Base colors for multi-reference LD coloring (one entry per region_ref).	`['#E51819', '#367EB7', 'green', '#F07818', '#AD5691', 'yellow', 'purple']`
`region_ld_legends`	`Any`	region_ld_legends.	required
`region_ld_threshold`	`list`	LD r² cutoffs (single-reference) that define color bins for scatter markers and ld_link lines.	`[0.2, 0.4, 0.6, 0.8]`
`region_lead_grid_line`	`dict`	Matplotlib kwargs for the reference/lead vertical guide line.	`{'alpha': 0.5, 'linewidth': 2, 'linestyle': '--', 'color': '#FF0000'}`
`region_lead_grids`	`Any`	region_lead_grids.	required
`region_legend_marker`	`bool`	Draw the reference-variant marker symbol in the LD colorbar inset.	`True`
`region_marker_shapes`	`list`	Matplotlib marker shapes by role; LD r² sets color only (region_ld_threshold/colors), not shape.	`['X', 'o', '^', 's', 'D', '*', 'P', 'h', '8']`
`region_protein_coding`	`bool`	Show only protein-coding genes on the GTF annotation track.	`True`
`region_recombination`	`bool`	Plot recombination-rate track under the locus (requires rr_path).	`True`
`region_ref`	`Any`	Reference variant ID(s) for LD coloring relative to vcf_path/ld_path.	required
`region_ref_alias`	`Any`	Map reference variant IDs to display labels in legend/colorbar.	required
`region_ref_second`	`Any`	Legacy second reference ID; prefer multiple entries in region_ref.	required
`region_step`	`Any`	Number of major tick intervals on the locus x-axis.	required
`region_title`	`Any`	Custom title above the locus scatter panel.	required
`region_title_kwargs`	`dict`	Regional plot title styling args.	`{'family': 'Arial', 'size': 12}`
`repel_force`	`float`	Text repulsion force parameter.	`0.03`
`rr_chr_dict`	`Any`	Recombination rate chrom dict.	required
`rr_header_dict`	`Any`	Recombination rate header dict.	required
`rr_lim`	`list`	Y-axis limits (cM/Mb) for the recombination track.	`[0, 100]`
`rr_path`	`str`	Recombination-rate resource path or 'default'.	`'default'`
`rr_ylabel`	`bool`	Whether to show the recombination-rate y-axis label.	`True`
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`sc_linewidth`	`int`	Line width for significance lines.	`2`
`scaled`	`bool`	Auto-detected when scaled effect columns exist; not a direct plot kwarg.	`False`
`scatter_kwargs`	`dict`	Extra kwargs passed to the main scatter layer (matplotlib Axes.scatter). Use marker_size for point sizes, not s/size. Do not set in `scatter_kwargs`: edgecolor, edgecolors, linewidth, ax, palette, hue, data, legend, style, size, sizes, zorder, s.	required
`show_ld_score`	`bool`	Annotate reference variants with LD score and draw LD-scored links.	`False`
`sig_line`	`bool`	Whether to draw significance reference line.	`True`
`sig_line_color`	`str or list`	Significance line color.	required
`snpid`	`str`	SNP identifier column.	`'SNPID'`
`stratified`	`bool`	Enable stratified QQ by MAF.	`False`
`subplot_height`	`int`	subplot_height.	`4`
`suggestive_sig_level`	`float`	Suggestive threshold value, e.g., 5e-6.	`5e-06`
`suggestive_sig_line`	`bool`	Whether to draw suggestive threshold line (e.g., 5e-6).	`False`
`suggestive_sig_line_color`	`str or list`	Suggestive significance line color.	required
`tabix`	`Any`	Tabix index path for fast IO.	required
`taf`	`list`	Track arrangement factors.	`[4, 0, 0.95, 1, 1]`
`title`	`str`	Figure title text.	required
`title_fontsize`	`int`	Title font size.	`13`
`title_kwargs`	`Any`	Title styling kwargs (e.g., family, fontsize, weight).	required
`title_pad`	`float`	Title padding.	`1.08`
`title_pos`	`list`	Title position in axes coordinates (x, y).	`[0.01, 0.97]`
`titles`	`Any`	Pair plot titles.	required
`track_exon_ratio`	`int`	Exon track ratio.	`1`
`track_font_family`	`str`	Font family for region tracks.	`'Arial'`
`track_fontsize_ratio`	`float`	Track fontsize ratio.	`0.95`
`track_n`	`int`	Maximum gene annotation rows (tracks) in the GTF panel.	`4`
`track_n_offset`	`int`	Track offset.	`0`
`track_text_offset`	`int`	Track text offset.	`1`
`use_rank`	`bool`	Use rank for chrom indexing.	`False`
`vcf_chr_dict`	`Any`	Chromosome mapping for VCF resource.	required
`vcfs`	`list`	vcfs.	`[]`
`verbose`	`bool`	Verbose logging toggle.	`True`
`windowsizekb`	`int`	Window size for lead variant extraction (kb).	`500`
`xlabel`	`Any`	X-axis label.	required
`xpad`	`Any`	X padding proportion.	required
`xpadl`	`Any`	Left X padding.	required
`xpadr`	`Any`	Right X padding.	required
`xtick_chr_dict`	`Any`	X-axis tick chromosome mapping.	required
`xtight`	`bool`	Tight X padding.	`False`
`ylabel`	`Any`	Y-axis label.	required
`ylabels`	`Any`	Custom y-axis labels.	required
`ylim`	`Any`	Y-axis limits.	required
`ystep`	`int`	Step size for y-axis.	`0`
`ytick3`	`bool`	Use 3 y-axis ticks.	`True`

Returns:

Type	Description
`matplotlib.figure.Figure`	The created matplotlib figure object. Updated logging object with operation records.

Notes

- By default, LD legends are automatically enabled for all mqq panels
- Duplicate legends are removed only when ALL panels with legends share the same lead variant
- If any panel has a different lead variant, all legends are kept to show the differences

`scatter`

Scatter plot comparing two columns from sumstats.

Parameters:

Name	Type	Description	Default
`df`	`DataFrame or Sumstats`	Input data.	required
`x`	`str`	Column name for the x-axis.	required
`y`	`str`	Column name for the y-axis.	required

Plotting (gl.plot_*)

compare_effect

plot_forest

plot_ld_block

plot_lead_overlap

plot_miami2

plot_panels

plot_power

plot_power_x

plot_rg

plot_sankey

plot_stacked_mqq

scatter

Plotting (`gl.plot_*`)

`compare_effect`

`plot_forest`

`plot_ld_block`

`plot_lead_overlap`

`plot_miami2`

`plot_panels`

`plot_power`

`plot_power_x`

`plot_rg`

`plot_sankey`

`plot_stacked_mqq`

`scatter`