Other Sumstats objects

Draft — not in API Reference

This page is kept for internal use only. It is not linked from the site nav until these objects are ready for publication.

Additional Sumstats container types for multi-study workflows.

SumstatsPair

init

__init__(sumstatsObject1: Sumstats, sumstatsObject2: Sumstats, study: Optional[str] = None, suffixes: Tuple[str, str] = ('_1', '_2'), keep_all_variants: bool = True, verbose: bool = True) -> None

Merge and harmonize two Sumstats objects for pairwise analysis.

Parameters:

Name	Type	Description	Default
`sumstatsObject1`	`Sumstats`	Input studies to merge by CHR/POS with allele alignment.	required
`sumstatsObject2`	`Sumstats`	Input studies to merge by CHR/POS with allele alignment.	required
`study`	`str`	Unused legacy parameter kept for API compatibility.	`None`
`suffixes`	`tuple of str`	Suffixes appended to per-study statistic columns.	`("_1", "_2")`
`keep_all_variants`	`bool`	If True, retain variants present in only one study (outer merge).	`True`
`verbose`	`bool`	Print progress messages.	`True`

Returns:

Type	Description
`None`	Initializes `self.data` and metadata on the pair object.

clump

clump(**kwargs: Any) -> None

Perform LD clumping of GWAS summary statistics using PLINK2.

Parameters:

Name	Type	Description	Default
`vcf`	`str or None`	Path or prefix to reference VCF or genotype data compatible with PLINK2. Used when deriving `--pfile` inputs.	required
`bfile`	`str or None`	Prefix to PLINK binary files (`.bed/.bim/.fam`). May include "@" as a chromosome placeholder.	required
`pfile`	`str or None`	Prefix to PLINK2 files (`.pgen/.pvar/.psam`). May include "@" as a chromosome placeholder.	required
`scaled`	`bool`	If True, clump on `mlog10p` using PLINK2 `--clump-log10`. If False, clump on `p`.	required
`out`	`str or None`	Output prefix. If None, uses "./{study}_clumpping".	required
`p`	`str`	Column name of p-values in `gls.data`.	required
`mlog10p`	`str`	Column name of -log10(p) in `gls.data`.	required
`overwrite`	`bool`	Whether to overwrite any intermediate reference files produced while preparing inputs.	required
`study`	`str or None`	Study name used when `out` is None.	required
`threads`	`int`	Number of threads to pass to PLINK2 via `--threads`.	required
`memory`	`int or None`	Memory limit (MB) for PLINK2 via `--memory`.	required
`chrom`	`any`	Unused parameter kept for API compatibility.	required
`clump_p1`	`float`	Primary p-value threshold (`--clump-p1` or `--clump-log10-p1`).	required
`clump_p2`	`float`	Secondary p-value threshold (`--clump-p2` or `--clump-log10-p2`).	required
`clump_r2`	`float`	LD threshold (`--clump-r2`).	required
`clump_kb`	`int`	Window size in kilobases (`--clump-kb`).	required
`log`	`Log`	Logger instance used for progress reporting.	required
`verbose`	`bool`	Whether to emit verbose log messages.	required
`plink`	`str`	Path to PLINK (v1). Not used directly in clumping.	required
`plink2`	`str`	Path to PLINK2 binary.	required

Returns:

Name	Type	Description
`results_sumstats`	`DataFrame`	Subset of input summary statistics for clumped lead variants.
`results`	`DataFrame`	Concatenated PLINK2 `.clumps` output across processed chromosomes.
`plink_log`	`str`	Combined PLINK2 log output captured during execution.

Workflow

The clumping process follows these steps:

Filter significant variants: Extract variants below the p-value threshold (clump_p1 or clump_p2) from the input sumstats.
Process reference files: Convert VCF/BGEN to PLINK format (bfile/pfile) if needed, and load BIM/PVAR variant information for matching.
Match variants with reference: Match sumstats variants with reference BIM using CHR, POS, and optionally EA/NEA to assign reference SNPIDs. This ensures PLINK uses consistent IDs that match the reference panel.
Create temporary input files: For each chromosome, create a temporary SNPIDP file containing variant IDs and p-values in a temporary directory.
Run PLINK2 clumping: Execute PLINK2 clumping for each chromosome separately, using the reference panel and temporary input files. PLINK2 identifies lead variants and their clumped variants based on LD (r²) within the specified window.
Process results: Read and concatenate clumping results from all chromosomes, map BIM SNPIDs back to original sumstats SNPIDs, and filter sumstats to include only clumped lead variants.
Cleanup: Delete temporary files and intermediate clumps output files after successful data reload.

Notes

- Writes temporary files in a temporary directory, which are automatically removed.
- Produces per-chromosome output files "{out}.{chr}.clumps" which are deleted after
  successful reload if delete_files option is used.
- Variant matching uses CHR, POS, EA, NEA to ensure ID consistency between sumstats
  and reference panel, preventing missing matches due to ID mismatches.

Examples:

>>> results_sumstats, results, logstr = _clump(
...     bfile="ref/chr@",
...     clump_p1=5e-8,
...     clump_p2=1e-5,
...     clump_r2=0.1,
...     clump_kb=250,
...     threads=4
... )

filter_value

filter_value(expr: str, inplace: bool = False, **kwargs: Any) -> typing.Optional[ForwardRef(SumstatsPair)]

Filter variants based on a query expression.

Parameters:

Name	Type	Description	Default
`sumstats_obj`	`Sumstats`	Sumstats object containing the data to filter.	required
`expr`	`str`	Query expression using pandas.DataFrame.query syntax	required
`remove`	`bool`	If True, removes variants meeting the condition	`False`
`verbose`	`bool`	If True, writes progress to log	`True`
`inplace`	`bool`	If False, return a new `Sumstats` object containing the filtered results. If True, apply the filter to the current object in place and return None.	`False`

Returns:

Type	Description
`DataFrame`	Filtered summary statistics table. When called via :meth:`Sumstats.filter_value()`, returns a new Sumstats object if `inplace=False`, or updates the Sumstats object in place (modifies `self.data`) and returns `None` if `inplace=True`.

plot_miami

plot_miami(**kwargs: Any) -> None

Parameters:

Name	Type	Description	Default
`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`

stacked_mqq

stacked_mqq(**kwargs: Any) -> None

Create stacked Manhattan/QQ/regional plots by iteratively calling plot_mqq.

Returns:

Name	Type	Description
`fig`	`Figure`	The created matplotlib figure object.
`log`	`Log`	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

Parameters:

Name	Type	Description	Default
`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

compare_af

compare_af(**kwargs: Any) -> typing.Any

Parameters:

Name	Type	Description	Default
`daf`	`str`	Discovery allele frequency column.	`'DAF'`
`eaf`	`str`	Effect allele frequency column for DAF comparison plot.	`'EAF'`
`fig_kwargs`	`dict`	Figure kwargs for plot.	`{'figsize': [8, 4], 'dpi': 300}`
`font_kwargs`	`dict`	Font configuration kwargs.	`{'fontsize': 9}`
`helper_line_kwargs`	`dict`	45-degree helper line styling for AF comparison.	`{'color': 'black', 'linestyle': '-', 'lw': 1}`
`histplot_kwargs`	`dict`	Histogram plotting kwargs for AF distribution.	`{'log_scale': [False, False]}`
`is_45_helper_line`	`bool`	Draw 45-degree helper line.	`True`
`is_reg`	`Any`	Enable regression line computation.	required
`is_threshold`	`Any`	Draw threshold line.	required
`legend1`	`Any`	Toggle first legend block.	required
`legend2`	`Any`	Toggle second legend block.	required
`r2`	`bool`	Show R-squared value.	`False`
`r2_kwargs`	`dict`	Text kwargs for R^2 annotation in AF comparison.	`{'va': 'bottom', 'ha': 'right'}`
`raf`	`str`	Reference allele frequency column.	`'RAF'`
`reg_line_kwargs`	`dict`	Regression line styling for AF comparison.	`{'color': '#cccccc', 'linestyle': '--'}`
`save`	`bool`	Boolean or output filepath; when boolean, uses default naming.	required
`save_kwargs`	`dict`	Save kwargs for GW heatmap.	required
`scatter_kwargs`	`dict`	Extra kwargs passed to the main scatter layer (matplotlib Axes.scatter). Use marker_size for point sizes, not s/size.	`{'s': 1}`
`scatter_kwargs_outlier`	`dict`	Scatter kwargs for outlier points in AF comparison.	`{'s': 3, 'c': 'red'}`
`threshold`	`Any`	AF difference threshold.	required
`threshold_line_kwargs`	`dict`	Threshold helper line styling for AF comparison.	`{'color': '#cccccc', 'linestyle': 'dotted'}`
`verbose`	`bool`	Verbose logging toggle.	`True`
`xlabel`	`Any`	X-axis label.	required
`ylabel`	`Any`	Y-axis label.	required

run_meta_analysis

run_meta_analysis(**kwargs: Any) -> typing.Any

Meta-analyze the two merged studies (fixed or random effects).

Parameters:

Name	Type	Description	Default
`random_effects`	`bool`	Use random-effects inverse-variance weighting when True.	`False`
`match_allele`	`bool`	Require matching alleles across studies.	`True`

Returns:

Type	Description
`Sumstats`	Meta-analyzed summary statistics as a new Sumstats object.

to_pickle

to_pickle(path: str = '~/mysumpair.pickle', overwrite: bool = False) -> None

Serialize the SumstatsPair object to a pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Output pickle path (`~` expands to the home directory).	`"~/mysumpair.pickle"`
`overwrite`	`bool`	Replace an existing file when True.	`False`

Returns:

Type	Description
`None`

SumstatsMulti

init

__init__(sumstatsObjects: List[Union[Sumstats, Sumstatsp]], group_name: Optional[str] = None, build: str = '99', engine: str = 'pandas', merge_by_id: bool = False, keep_all_variants: bool = True, verbose: bool = True) -> None

to_pickle

to_pickle(path: str = '~/mysummulti.pickle', overwrite: bool = False) -> None

Save SumstatsMulti object to a pickle file.

Parameters:

Name	Type	Description	Default
`path`	`str`	File path for the pickle file. Supports `~` for home directory expansion. Defaults to "~/mysummulti.pickle"	`'~/mysummulti.pickle'`
`overwrite`	`bool`	If True, overwrite the file if it already exists. If False, skip saving if file exists. Defaults to False	`False`

Returns:

Type	Description
`None`	Saves the object to disk

SumstatsSet

Bases: gwaslab.g_Sumstats.Sumstats

A class for working with multiple GWAS summary statistics datasets.

SumstatsSet allows you to load and combine variants from multiple studies,
either by providing a dictionary of Sumstats objects or by using a glob pattern
to automatically discover and load multiple files.

Parameters:

Name	Type	Description	Default
`sumstats_dic`	`Union[Dict[str, Any], str]`	Either: - A dictionary mapping study names to Sumstats objects or file paths - A glob pattern string (e.g., "./study_*.txt") to auto-discover files	required
`variant_set`	`Optional[Any]`	Collection of variants to extract. See `_extract_variant` for details.	`None`
`build`	`str`	Genome build version.	`"99"`
`species`	`str`	Species name.	`"homo sapiens"`
`build_infer`	`bool`	Whether to infer genome build.	`False`
`set`	`str`	Name for this set of summary statistics.	`"set1"`
`verbose`	`bool`	Whether to print log messages. **readargs : Any Additional arguments passed to Sumstats initialization when loading from files.	`True`

Examples:

>>> # Load from a dictionary of Sumstats objects
>>> ss = SumstatsSet({"study1": sumstats1, "study2": sumstats2}, variant_set=["rs12345"])

>>> # Load from a glob pattern
>>> ss = SumstatsSet("./data/study_*.txt", variant_set=["rs12345"], fmt="auto")

doc `class-attribute`

__doc__ = 'A class for working with multiple GWAS summary statistics datasets.\n\n    SumstatsSet allows you to load and combine variants from multiple studies,\n    either by providing a dictionary of Sumstats objects or by using a glob pattern\n    to automatically discover and load multiple files.\n\nParameters\n----------\nsumstats_dic : Union[Dict[str, Any], str]\n    Either:\n    - A dictionary mapping study names to Sumstats objects or file paths\n    - A glob pattern string (e.g., "./study_*.txt") to auto-discover files\nvariant_set : Optional[Any], default None\n    Collection of variants to extract. See `_extract_variant` for details.\nbuild : str, default "99"\n    Genome build version.\nspecies : str, default "homo sapiens"\n    Species name.\nbuild_infer : bool, default False\n    Whether to infer genome build.\nset : str, default "set1"\n    Name for this set of summary statistics.\nverbose : bool, default True\n    Whether to print log messages.\n    **readargs : Any\n    Additional arguments passed to Sumstats initialization when loading from files.\nExamples\n--------\n    >>> # Load from a dictionary of Sumstats objects\n    >>> ss = SumstatsSet({"study1": sumstats1, "study2": sumstats2}, variant_set=["rs12345"])\n\n    >>> # Load from a glob pattern\n    >>> ss = SumstatsSet("./data/study_*.txt", variant_set=["rs12345"], fmt="auto")\n'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

module `class-attribute`

__module__ = 'gwaslab.g_SumstatsSet'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

Sumstatsp

module `class-attribute`

__module__ = 'gwaslab.g_Sumstats_polars'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

weakref `property`

__weakref__

list of weak references to the object

fix_chr

fix_chr(**kwargs: Any) -> Sumstatsp

Standardize chromosome notation and handle special chromosome cases (X, Y, MT).

    This method normalizes chromosome labels to a consistent format, extracts chromosome
    numbers from various formats (e.g., "chr1", "1", "chrX"), maps special chromosomes
    (X, Y, mitochondrial) to standardized numeric identifiers, and optionally removes
    invalid chromosome values.

Parameters:

Name	Type	Description	Default
`chrom`	`str`	Column name for chromosome.	`"CHR"`
`status`	`str`	Column name for status.	`"STATUS"`
`add_prefix`	`str`	Prefix to prepend to chromosome labels (e.g., "chr").	`""`
`remove`	`bool`	If True, remove records with invalid or unrecognized chromosome labels.	`False`
`verbose`	`bool`	If True, print progress or diagnostic messages.	`True`

Returns:

Type	Description
`Sumstatsp`	Returns self for method chaining.

fix_pos

fix_pos(**kwargs: Any) -> Sumstatsp

Standardize and validate genomic base-pair positions.

    This method checks that reported genomic positions fall within valid chromosomal bounds
    and optionally removes invalid entries. It handles string-formatted positions with
    thousands separators, converts positions to Int64 type, and filters out positions
    outside the specified range.

Parameters:

Name	Type	Description	Default
`pos`	`str`	Column name for position.	`"POS"`
`status`	`str`	Column name for status.	`"STATUS"`
`remove`	`bool`	If True, remove records with invalid or out-of-range positions.	`False`
`verbose`	`bool`	If True, print progress or diagnostic messages.	`True`
`lower_limit`	`int`	Minimum acceptable genomic position. Default is 0.	required
`upper_limit`	`int`	Maximum acceptable genomic position.	required
`limit`	`int`	Default upper limit applied when `upper_limit` is not provided.	`250000000`

Returns:

Type	Description
`Sumstatsp`	Returns self for method chaining.

SumstatsT

module `class-attribute`

__module__ = 'gwaslab.g_SumstatsT'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

weakref `property`

__weakref__

list of weak references to the object

Other Sumstats objects

SumstatsPair

__init__

clump

filter_value

plot_miami

stacked_mqq

compare_af

run_meta_analysis

to_pickle

SumstatsMulti

__init__

to_pickle

SumstatsSet

__doc__ class-attribute

__module__ class-attribute

Sumstatsp

__module__ class-attribute

__weakref__ property

fix_chr

fix_pos

SumstatsT

__module__ class-attribute

__weakref__ property

init

init

doc `class-attribute`

module `class-attribute`

module `class-attribute`

weakref `property`

module `class-attribute`

weakref `property`