API Documentation

XClone: Inference of clonal Copy Number Alterations in single cells.

Import XClone as:

import xclone

Commands 

XCloneRDR: see manual
XCloneBAF: see manual
XCloneCombine: see manual

Functions 

Read / Load 

xclone.preprocessing.xclonedata(Xmtx, data_mode, mtx_barcodes_file, regions_anno_file=None, genome_mode='hg38_genes', data_notes=None)

Extracting xcltk output as anndata for the input of XClone.

Parameters:

Xmtx (csr_mtx or csr_mtx path) – The input data matrix/path; or a list of data matrix/paths to the matrix files.
data_mode (str) – Mode of the data, either ‘BAF’ or ‘RDR’.
mtx_barcodes_file (str) – Path to the barcodes file.
genome_mode (str, optional) – Genome mode, one of ‘hg38_genes’, ‘hg38_blocks’, ‘hg19_genes’, ‘hg19_blocks’, or ‘mm10_genes’. Default is ‘hg38_genes’.

Returns:

Xadataanndata.AnnData: The data customised for XClone as input for both RDR module and BAF module.

Example

import xclone

dat_dir = 'xxx/TNBC1-csp-post/phase-snp-even/'
AD_file = dat_dir + 'kat-csp-post.50kb.block.AD.mtx'
DP_file = dat_dir + 'kat-csp-post.50kb.block.DP.mtx'
mtx_barcodes_file = dat_dir + "cellSNP.samples.tsv"

BAF_adata = xclone.pp.xclonedata([AD_file, DP_file], 'BAF', mtx_barcodes_file,
                                "hg38_blocks", "TNBC1 scRNA-seq data in copyKAT")
dat_dir = 'xxx/TNBC1-rdr/'
RDR_file = dat_dir + 'matrix.mtx'
RDR_adata = xclonedata(RDR_file, 'RDR', mtx_barcodes_file, "hg38_genes")

xclone.preprocessing.readrdr_mtx(path, genome_mode='hg38_genes', data_notes=None, **kwargs)

Extracting cellranger output as anndata for the input of XClone RDR module.

Parameters:

path (Path | str) – Path to directory for .mtx and .tsv files, e.g. ‘./filtered_gene_bc_matrices/hg19/’.
genome_mode (str, optional) – Genome mode, one of ‘hg38_genes’, ‘hg19_genes’ or ‘mm10_genes’. Default is ‘hg38_genes’.
**kwargs (other parameters from scanpy.read_10x_mtx().) – e.g., var_names=’gene_symbols’, make_unique=True, cache=False, cache_compression=None, gex_only=True, prefix=None

Returns:

Xadataanndata.AnnData: The data customised for XClone as input for RDR module.

Example

import xclone

path = './filtered_gene_bc_matrices/hg38/'
Xdata = xclone.pp.readrdr_mtx(path)

xclone.preprocessing.extra_anno(Xdata, anno_file, barcodes_key='barcodes', cell_anno_key='cell_type', sep=',', copy=True)

Add extra annotation for Xdata.obs.

This function adds additional annotations from the provided anno_file to the obs attribute of the Xdata object. The file should contain cell barcodes and other columns with different types of annotations, such as cell types or clones.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix to which the extra annotations will be added.
anno_file (str) – The path to the annotation file. The first column should contain cell/spot barcodes, with the default column name being “barcodes”. Other columns contain different types of annotations.
barcodes_key (str, optional) – The column name in anno_file that contains cell barcodes. Default is “barcodes”.
cell_anno_key (str or list of str, optional) – The key(s) for the cell annotations to be added. Default is “cell_type”.
sep (str, optional) – The delimiter used in the anno_file. Default is “,”.

Returns:

Xadataanndata.AnnData: The data with additional annotations added.

Example

import xclone

anno_dir = "/storage/yhhuang/research/xomics/GEX5/GX109-T1c/"
anno_file = anno_dir + "GX109-T1c_yh.csv"
RDR_adata = xclone.pp.extra_anno(RDR_adata, anno_file, barcodes_key="cell",
                                cell_anno_key="cell_type", sep=",")

Config module-specific parmas 

Main config manager 

class xclone.PreprocessingConfig(dataset_name='XClone_scDATA', module='RDR', cell_anno_file=None, barcodes_key='barcodes', anno_file_sep=',', set_spatial=False, spot_position_file=None, rdr_data_dir=None, baf_data_dir=None)

Bases: object

Configuration manager for preprocessing/loading XClone data.

This class handles the configuration settings required for loading and preprocessing XClone data, including dataset details, module-specific configurations, file paths, and spatial settings.

module

The module to configure (‘pre_check’, ‘RDR’, ‘BAF’, ‘Combine’).

Type:: str

set_spatial

Flag to indicate if spatial data settings should be applied.

Type:: bool

rdr_data_dir

Directory path for RDR data files.

Type:: str or None

baf_data_dir

Directory path for BAF data files.

Type:: str or None

dataset_name

The name of the dataset.

Type:: str

RDR_file

Path to the RDR matrix file.

Type:: str or None

mtx_barcodes_file

Path to the barcodes file for the matrix.

Type:: str or None

regions_anno_file

Path to the regions annotation file.

Type:: str or None

cell_anno_file

Path to the cell annotation file.

Type:: str or None

barcodes_key

Key for barcodes in the cell annotation file.

Type:: str

anno_file_sep

Separator used in the annotation file.

Type:: str

cell_anno_key

Key for cell type annotations.

Type:: str

genome_mode

Genome mode setting. One of ‘hg38_genes’, ‘hg38_blocks’, ‘hg19_genes’, ‘hg19_blocks’, or ‘mm10_genes’. Default is ‘hg38_genes’.

Type:: str

spot_position_file

Path to the spot position file for spatial data.

Type:: str or None

AD_file

Path to the AD matrix file for BAF data.

Type:: str or None

DP_file

Path to the DP matrix file for BAF data.

Type:: str or None

RDR_adata_file

Path to the processed RDR AnnData file. Specific for ‘Combine’ module.

Type:: str or None

BAF_adata_file

Path to the processed BAF AnnData file. Specific for ‘Combine’ module.

Type:: str or None

Initialize the PreprocessingConfig class with various configuration parameters.

Parameters:

dataset_name (str, optional) – The name of the dataset (default is “XClone_scDATA”).
module (str, optional) – The module to configure, must be one of “pre_check”, “RDR”, “BAF”, or “Combine” (default is “RDR”).
cell_anno_file (str or None, optional) – Path to the cell annotation file (default is None).
barcodes_key (str, optional) – Key for barcodes in the cell annotation file (default is “barcodes”).
anno_file_sep (str, optional) – Separator used in the annotation file (default is “,”).
set_spatial (bool, optional) – Flag to set spatial specific configurations (default is False).
spot_position_file (str or None, optional) – Path to the spot position file for spatial data (default is None).
rdr_data_dir (str or None, optional) – Directory path for RDR data files (default is None).
baf_data_dir (str or None, optional) – Directory path for BAF data files (default is None).

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': "\n Configuration manager for preprocessing/loading XClone data.\n\n This class handles the configuration settings required for loading and preprocessing\n XClone data, including dataset details, module-specific configurations, file paths,\n and spatial settings.\n\n Attributes\n ----------\n\n module : str\n The module to configure ('pre_check', 'RDR', 'BAF', 'Combine').\n set_spatial : bool\n Flag to indicate if spatial data settings should be applied.\n rdr_data_dir : str or None\n Directory path for RDR data files.\n baf_data_dir : str or None\n Directory path for BAF data files.\n dataset_name : str\n The name of the dataset.\n RDR_file : str or None\n Path to the RDR matrix file.\n mtx_barcodes_file : str or None\n Path to the barcodes file for the matrix.\n regions_anno_file : str or None\n Path to the regions annotation file.\n cell_anno_file : str or None\n Path to the cell annotation file.\n barcodes_key : str\n Key for barcodes in the cell annotation file.\n anno_file_sep : str\n Separator used in the annotation file.\n cell_anno_key : str\n Key for cell type annotations.\n genome_mode : str\n Genome mode setting. One of 'hg38_genes', 'hg38_blocks', 'hg19_genes', \n 'hg19_blocks', or 'mm10_genes'. Default is 'hg38_genes'.\n spot_position_file : str or None\n Path to the spot position file for spatial data.\n AD_file : str or None\n Path to the AD matrix file for BAF data.\n DP_file : str or None\n Path to the DP matrix file for BAF data.\n RDR_adata_file : str or None\n Path to the processed RDR AnnData file. Specific for 'Combine' module.\n BAF_adata_file : str or None\n Path to the processed BAF AnnData file. Specific for 'Combine' module.\n ", '__init__': <function PreprocessingConfig.__init__>, 'display': <function PreprocessingConfig.display>, '__dict__': <attribute '__dict__' of 'PreprocessingConfig' objects>, '__weakref__': <attribute '__weakref__' of 'PreprocessingConfig' objects>, '__annotations__': {}})

__init__(dataset_name='XClone_scDATA', module='RDR', cell_anno_file=None, barcodes_key='barcodes', anno_file_sep=',', set_spatial=False, spot_position_file=None, rdr_data_dir=None, baf_data_dir=None)

Initialize the PreprocessingConfig class with various configuration parameters.

Parameters:

dataset_name (str, optional) – The name of the dataset (default is “XClone_scDATA”).
module (str, optional) – The module to configure, must be one of “pre_check”, “RDR”, “BAF”, or “Combine” (default is “RDR”).
cell_anno_file (str or None, optional) – Path to the cell annotation file (default is None).
barcodes_key (str, optional) – Key for barcodes in the cell annotation file (default is “barcodes”).
anno_file_sep (str, optional) – Separator used in the annotation file (default is “,”).
set_spatial (bool, optional) – Flag to set spatial specific configurations (default is False).
spot_position_file (str or None, optional) – Path to the spot position file for spatial data (default is None).
rdr_data_dir (str or None, optional) – Directory path for RDR data files (default is None).
baf_data_dir (str or None, optional) – Directory path for BAF data files (default is None).

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

display(): Display Configuration values.

class xclone.XCloneConfig(dataset_name='XClone_scDATA', set_smartseq=False, set_spatial=False, module='RDR', baf_bias_mode=1, plot_suffix='', file_format_data='h5ad', file_format_figs='pdf', outdir='./XCLONE_OUT/', _frameon=True, _vector_friendly=False)

Bases: object

Config manager for XClone.

This class manages the configuration settings for the XClone tool, including dataset details, module-specific configurations, file formats, and output directories.

Initialize the XCloneConfig class with various configuration parameters.

Parameters:

dataset_name (str, optional) – The name of the dataset (default is “XClone_scDATA”).
set_smartseq (bool, optional) – Flag to set Smart-seq specific configurations (default is False).
set_spatial (bool, optional) – Flag to set spatial specific configurations (default is False).
module (str, optional) – The module to configure, must be one of “RDR”, “BAF”, or “Combine” (default is “RDR”).
baf_bias_mode (int, optional) – BAF bias mode (default is 1).
plot_suffix (str, optional) – Suffix to append to plot filenames (default is “”).
file_format_data (str, optional) – Format for saving data files (default is “h5ad”).
file_format_figs (str, optional) – Format for saving figure files (default is “pdf”).
outdir (Union[str, Path], optional) – Directory to save output files (default is “./XCLONE_OUT/”).
_frameon (bool, optional) – Flag to add frames and axes labels to scatter plots (default is True).
_vector_friendly (bool, optional) – Flag for vector-friendly plotting (default is False).

Literal = typing.Literal

_Format: alias of Literal[‘png’, ‘jpg’, ‘tif’, ‘tiff’, ‘pdf’, ‘ps’, ‘eps’, ‘svg’, ‘svgz’, ‘pgf’, ‘raw’, ‘rgba’]

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n Config manager for XClone.\n\n This class manages the configuration settings for the XClone tool,\n including dataset details, module-specific configurations, file formats,\n and output directories.\n ', '__init__': <function XCloneConfig.__init__>, 'plot_suffix': <property object>, 'file_format_data': <property object>, 'file_format_figs': <property object>, 'outdir': <property object>, 'display': <function XCloneConfig.display>, 'Literal': typing.Literal, '_Format': typing.Literal['png', 'jpg', 'tif', 'tiff', 'pdf', 'ps', 'eps', 'svg', 'svgz', 'pgf', 'raw', 'rgba'], 'set_figure_params': <function XCloneConfig.set_figure_params>, '_is_run_from_ipython': <staticmethod object>, '__str__': <function XCloneConfig.__str__>, '__dict__': <attribute '__dict__' of 'XCloneConfig' objects>, '__weakref__': <attribute '__weakref__' of 'XCloneConfig' objects>, '__annotations__': {}})

__init__(dataset_name='XClone_scDATA', set_smartseq=False, set_spatial=False, module='RDR', baf_bias_mode=1, plot_suffix='', file_format_data='h5ad', file_format_figs='pdf', outdir='./XCLONE_OUT/', _frameon=True, _vector_friendly=False)

Initialize the XCloneConfig class with various configuration parameters.

Parameters:

dataset_name (str, optional) – The name of the dataset (default is “XClone_scDATA”).
set_smartseq (bool, optional) – Flag to set Smart-seq specific configurations (default is False).
set_spatial (bool, optional) – Flag to set spatial specific configurations (default is False).
module (str, optional) – The module to configure, must be one of “RDR”, “BAF”, or “Combine” (default is “RDR”).
baf_bias_mode (int, optional) – BAF bias mode (default is 1).
plot_suffix (str, optional) – Suffix to append to plot filenames (default is “”).
file_format_data (str, optional) – Format for saving data files (default is “h5ad”).
file_format_figs (str, optional) – Format for saving figure files (default is “pdf”).
outdir (Union[str, Path], optional) – Directory to save output files (default is “./XCLONE_OUT/”).
_frameon (bool, optional) – Flag to add frames and axes labels to scatter plots (default is True).
_vector_friendly (bool, optional) – Flag for vector-friendly plotting (default is False).

__module__ = 'xclone._config'

__str__()

Return str(self).

Return type:: str

__weakref__: list of weak references to the object (if defined)

_frameon

See set_figure_params.

Type:: bool

static _is_run_from_ipython(): Determines whether we’re currently in IPython.

_start: Time when the settings module is first imported.

_vector_friendly: Set to true if you want to include pngs in svgs and pdfs.

display(): Display Configuration values.

property file_format_data: str: File format for saving AnnData objects. Allowed are ‘txt’, ‘csv’ (comma separated value file) for exporting and ‘h5ad’ (hdf5) for lossless saving.

property file_format_figs: str: File format for saving figures. For example ‘png’, ‘pdf’ or ‘svg’. Many other formats work as well (see matplotlib.pyplot.savefig).

property outdir: Path: Directory where the function xclone.write writes to by default.

property plot_suffix: str: Global suffix that is appended to figure filenames.

set_figure_params(xclone=True, dpi=80, dpi_save=150, frameon=True, vector_friendly=True, fontsize=14, figsize=None, color_map=None, grid_alpha=None, format='pdf', facecolor=None, transparent=False, ipython_format='png2x')

Set resolution/size, styling and format of figures.

Parameters:

xclone (bool) – Init default values for matplotlib.rcParams suited for XClone.
dpi (int) – Resolution of rendered figures, this influences the size of figures in notebooks.
dpi_save (int) – Resolution of saved figures. This should typically be higher to achieve publication quality.
frameon (bool) – Add frames and axes labels to scatter plots.
vector_friendly (bool) – Plot scatter plots using png backend even when exporting as pdf or svg.
fontsize (int) – Set the fontsize for several rcParams entries. Ignored if xclone=False.
figsize (Optional[int]) – Set plt.rcParams[‘figure.figsize’].
color_map (Optional[str]) – Convenience method for setting the default color map. Ignored if xclone=False.
format (Literal['png', 'jpg', 'tif', 'tiff', 'pdf', 'ps', 'eps', 'svg', 'svgz', 'pgf', 'raw', 'rgba']) – This sets the default format for saving figures: file_format_figs.
facecolor (Optional[str]) – Sets backgrounds via rcParams[‘figure.facecolor’] = facecolor and rcParams[‘axes.facecolor’] = facecolor.
transparent (bool) – Save figures with transparent back ground. Sets rcParams[‘savefig.transparent’].
ipython_format (str) – Only concerns the notebook/IPython environment; see set_matplotlib_formats() for details.

Module specific config manager 

class xclone.XCloneGeneral_config

Bases: object

General configuration settings for XClone.

This class manages general configuration settings for the XClone tool, including cell annotation keys, reference cell types, data exclusion options, KNN smoothing parameters, and plotting preferences.

cell_anno_key

The key for cell type annotations.

Type:: str

ref_celltype

The reference cell type.

Type:: str

exclude_XY

Flag to exclude XY chromosomes from analysis.

Type:: bool

remove_guide_XY

Flag to remove guide XY chromosomes.

Type:: bool

KNN_neighbors

Number of neighbors for KNN smoothing.

Type:: int

plot_remove_immune

Flag to remove immune cells during plotting.

Type:: bool

plot_immune_celltype

The cell type to be considered as immune cells for plotting.

Type:: str or None

plot_remove_reference

Flag to remove reference cells during plotting.

Type:: bool

plot_ref_celltype

The cell type to be considered as reference cells for plotting.

Type:: str or None

develop_mode

Flag to set develop mode or not (main difference in saved outputs).

Type:: bool

Initialize the XCloneGeneral_config class with default configuration parameters.

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n General configuration settings for XClone.\n\n This class manages general configuration settings for the XClone tool,\n including cell annotation keys, reference cell types, data exclusion options,\n KNN smoothing parameters, and plotting preferences.\n\n Attributes\n ----------\n\n cell_anno_key : str\n The key for cell type annotations.\n ref_celltype : str\n The reference cell type.\n exclude_XY : bool\n Flag to exclude XY chromosomes from analysis.\n remove_guide_XY : bool\n Flag to remove guide XY chromosomes.\n KNN_neighbors : int\n Number of neighbors for KNN smoothing.\n plot_remove_immune : bool\n Flag to remove immune cells during plotting.\n plot_immune_celltype : str or None\n The cell type to be considered as immune cells for plotting.\n plot_remove_reference : bool\n Flag to remove reference cells during plotting.\n plot_ref_celltype : str or None\n The cell type to be considered as reference cells for plotting.\n develop_mode : bool\n Flag to set develop mode or not (main difference in saved outputs).\n\n ', '__init__': <function XCloneGeneral_config.__init__>, '__dict__': <attribute '__dict__' of 'XCloneGeneral_config' objects>, '__weakref__': <attribute '__weakref__' of 'XCloneGeneral_config' objects>, '__annotations__': {}})

__init__()

Initialize the XCloneGeneral_config class with default configuration parameters.

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.RDR_General_config

Bases: object

General configuration settings for new version of RDR (RDR_gaussian) Adapted from RDR_prev_General_config for Gaussian-based RDR analysis.

This class manages the configuration settings for RDR analysis, particularly for 10X scRNA-seq data, including transformation options, filtering criteria, marker gene settings, GLM fitting settings, smoothing parameters, and plotting preferences.

smart_transform

Flag to apply smart transformation (default is False).

Type:: bool

filter_ref_ave

Threshold for filtering based on reference average (default is 0.5).

Type:: float

min_gene_keep_num

Minimum number of genes to keep (default is 3000).

Type:: int

multi_refcelltype

Flag to use multiple reference cell types.

Type:: bool

marker_group_anno_key

Annotation key for marker groups.

Type:: str or None

get_marker_genes

Flag to retrieve marker genes (default is True).

Type:: bool

top_n_marker

Number of top marker genes to select (default is 15).

Type:: int

remove_marker

Flag to remove marker genes (default is True).

Type:: bool

fit_GLM_libratio

Flag to fit GLM using library ratio (default is False, to use counts ratio).

Type:: bool

select_normal_chr_num

Number of normal chromosomes to select (default is 4).

Type:: int

dispersion_celltype

Cell type for dispersion calculation.

Type:: str or None

gene_exp_group

Expression group for gene analysis (default is 1).

Type:: int

gene_exp_ref_log

Flag to use log transformation for reference expression (should active when exp_group > 1).

Type:: bool

guide_cnv_ratio

Ratio for guiding CNV.

Type:: float or None

guide_chr_anno_key

Annotation key for chromosome guidance (default is “chr_arm”).

Type:: str

guide_qt_lst

List of quantiles for guidance (default is [1e-04, 0.96, 0.99] for “chr_arm”, We recommend try [0.00001, 0.96, 0.999] for “chr”).

Type:: list of float

WMA_window_size

Window size for Weighted Moving Average (WMA) smoothing (default is 40).

Type:: int

WMA_smooth_key

Key for WMA smoothing (default is “chr_arm”).

Type:: str

xclone_plot

Flag to enable XClone plotting (default is True).

Type:: bool

plot_cell_anno_key

Annotation key for plotting cell annotations.

Type:: str or None

rdr_plot_vmin

Minimum value for RDR plot color scale.

Type:: float

rdr_plot_vmax

Maximum value for RDR plot color scale.

Type:: float

set_figtitle

Flag to set figure titles in plots (default is True).

Type:: bool

Initialize the class RDR_General_config() class with default configuration parameters.

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n General configuration settings for new version of RDR (RDR_gaussian)\n Adapted from RDR_prev_General_config for Gaussian-based RDR analysis.\n\n This class manages the configuration settings for RDR analysis, particularly\n for 10X scRNA-seq data, including transformation options, filtering criteria,\n marker gene settings, GLM fitting settings, smoothing parameters, and plotting preferences.\n\n Attributes\n ----------\n\n smart_transform : bool\n Flag to apply smart transformation (default is False).\n filter_ref_ave : float\n Threshold for filtering based on reference average (default is 0.5).\n min_gene_keep_num : int\n Minimum number of genes to keep (default is 3000).\n multi_refcelltype : bool\n Flag to use multiple reference cell types.\n marker_group_anno_key : str or None\n Annotation key for marker groups.\n get_marker_genes : bool\n Flag to retrieve marker genes (default is True).\n top_n_marker : int\n Number of top marker genes to select (default is 15).\n remove_marker : bool\n Flag to remove marker genes (default is True).\n fit_GLM_libratio : bool\n Flag to fit GLM using library ratio (default is False, to use counts ratio).\n select_normal_chr_num : int\n Number of normal chromosomes to select (default is 4).\n dispersion_celltype : str or None\n Cell type for dispersion calculation.\n gene_exp_group : int\n Expression group for gene analysis (default is 1).\n gene_exp_ref_log : bool\n Flag to use log transformation for reference expression (should active when exp_group > 1).\n guide_cnv_ratio : float or None\n Ratio for guiding CNV.\n guide_chr_anno_key : str\n Annotation key for chromosome guidance (default is "chr_arm").\n guide_qt_lst : list of float\n List of quantiles for guidance (default is [1e-04, 0.96, 0.99] for "chr_arm",\n We recommend try [0.00001, 0.96, 0.999] for "chr").\n WMA_window_size : int\n Window size for Weighted Moving Average (WMA) smoothing (default is 40).\n WMA_smooth_key : str\n Key for WMA smoothing (default is "chr_arm").\n xclone_plot : bool\n Flag to enable XClone plotting (default is True).\n plot_cell_anno_key : str or None\n Annotation key for plotting cell annotations.\n rdr_plot_vmin : float\n Minimum value for RDR plot color scale.\n rdr_plot_vmax : float\n Maximum value for RDR plot color scale.\n set_figtitle : bool\n Flag to set figure titles in plots (default is True).\n ', '__init__': <function RDR_General_config.__init__>, '__dict__': <attribute '__dict__' of 'RDR_General_config' objects>, '__weakref__': <attribute '__weakref__' of 'RDR_General_config' objects>, '__annotations__': {}})

__init__()

Initialize the class RDR_General_config() class with default configuration parameters.

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.BAF_General_config(baf_bias_mode)

Bases: object

General configuration settings for BAF (B Allele Frequency) analysis.

This class manages the configuration settings for BAF analysis, particularly for 10X scRNA-seq data, including bias mode settings, related RDR settings, KNN connectivity options, theoretical CNV states, phasing parameters, smoothing, postprocessing options, and plotting preferences.

baf_bias_mode

Mode for BAF bias setting.

Type:: int

CNV_N_components

Number of components for CNV analysis, dependent on baf_bias_mode.

Type:: int

BAF_add

Additional BAF configuration based on baf_bias_mode.

Type:: bool or None

update_info_from_rdr

Flag to update information from RDR.

Type:: bool

RDR_file

Path to the RDR file.

Type:: str or None

remove_marker_genes

Flag to remove marker genes.

Type:: bool

KNN_connect_use_key

Key for KNN connectivity usage.

Type:: str

get_BAF_KNN_connectivities

Flag to get BAF KNN connectivities.

Type:: bool

KNN_Xlayer

X layer for KNN smoothing.

Type:: str

guide_theo_CNV_states

Theoretical CNV states for guidance.

Type:: str or None

theo_neutral_BAF

Theoretical neutral BAF value.

Type:: str or None

ref_BAF_clip

Flag to clip reference BAF.

Type:: bool

concentration

Concentration value for analysis.

Type:: int

extreme_count_cap

Flag to cap extreme counts.

Type:: bool

gene_specific_concentration

Flag for gene-specific concentration.

Type:: bool

concentration_lower

Lower bound for concentration.

Type:: int

concentration_upper

Upper bound for concentration.

Type:: int

feature_mode

Mode for feature selection.

Type:: str

phasing_region_key

Key for phasing regions.

Type:: str

phasing_len

Length of phasing regions.

Type:: int

bin_nproc

Number of processes for binning.

Type:: int

WMA_window_size

Window size for Weighted Moving Average (WMA) smoothing.

Type:: int

WMA_smooth_key

Key for WMA smoothing.

Type:: str

BAF_denoise

Flag to enable BAF denoising.

Type:: bool

BAF_denoise_GMM_detection

Flag to enable GMM detection in BAF denoising.

Type:: bool

BAF_denoise_GMM_comp

Number of components for GMM in BAF denoising.

Type:: int

BAF_denoise_cellprop_cutoff

Cutoff for cell proportion in BAF denoising.

Type:: float

xclone_plot

Flag to enable XClone plotting.

Type:: bool

plot_cell_anno_key

Annotation key for plotting cell annotations.

Type:: str or None

set_figtitle

Flag to set figure titles in plots.

Type:: bool

Initialize the BAF_General_config class with configuration parameters based on the BAF bias mode.

This method sets default values for BAF analysis settings, optimized for 10X scRNA-seq data.

Parameters:: baf_bias_mode (int) – Mode for BAF bias setting, determines specific configurations. Default 1 (5 allele bias states), otherwise 0 (3 allele bias states).

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n General configuration settings for BAF (B Allele Frequency) analysis.\n\n This class manages the configuration settings for BAF analysis, particularly\n for 10X scRNA-seq data, including bias mode settings, related RDR settings,\n KNN connectivity options, theoretical CNV states, phasing parameters, smoothing,\n postprocessing options, and plotting preferences.\n\n Attributes\n ----------\n\n baf_bias_mode : int\n Mode for BAF bias setting.\n CNV_N_components : int\n Number of components for CNV analysis, dependent on baf_bias_mode.\n BAF_add : bool or None\n Additional BAF configuration based on baf_bias_mode.\n update_info_from_rdr : bool\n Flag to update information from RDR.\n RDR_file : str or None\n Path to the RDR file.\n remove_marker_genes : bool\n Flag to remove marker genes.\n KNN_connect_use_key : str\n Key for KNN connectivity usage.\n get_BAF_KNN_connectivities : bool\n Flag to get BAF KNN connectivities.\n KNN_Xlayer : str\n X layer for KNN smoothing.\n guide_theo_CNV_states : str or None\n Theoretical CNV states for guidance.\n theo_neutral_BAF : str or None\n Theoretical neutral BAF value.\n ref_BAF_clip : bool\n Flag to clip reference BAF.\n concentration : int\n Concentration value for analysis.\n extreme_count_cap : bool\n Flag to cap extreme counts.\n gene_specific_concentration : bool\n Flag for gene-specific concentration.\n concentration_lower : int\n Lower bound for concentration.\n concentration_upper : int\n Upper bound for concentration.\n feature_mode : str\n Mode for feature selection.\n phasing_region_key : str\n Key for phasing regions.\n phasing_len : int\n Length of phasing regions.\n bin_nproc : int\n Number of processes for binning.\n WMA_window_size : int\n Window size for Weighted Moving Average (WMA) smoothing.\n WMA_smooth_key : str\n Key for WMA smoothing.\n BAF_denoise : bool\n Flag to enable BAF denoising.\n BAF_denoise_GMM_detection : bool\n Flag to enable GMM detection in BAF denoising.\n BAF_denoise_GMM_comp : int\n Number of components for GMM in BAF denoising.\n BAF_denoise_cellprop_cutoff : float\n Cutoff for cell proportion in BAF denoising.\n xclone_plot : bool\n Flag to enable XClone plotting.\n plot_cell_anno_key : str or None\n Annotation key for plotting cell annotations.\n set_figtitle : bool\n Flag to set figure titles in plots.\n ', '__init__': <function BAF_General_config.__init__>, '__dict__': <attribute '__dict__' of 'BAF_General_config' objects>, '__weakref__': <attribute '__weakref__' of 'BAF_General_config' objects>, '__annotations__': {}})

__init__(baf_bias_mode)

Initialize the BAF_General_config class with configuration parameters based on the BAF bias mode.

This method sets default values for BAF analysis settings, optimized for 10X scRNA-seq data.

Parameters:: baf_bias_mode (int) – Mode for BAF bias setting, determines specific configurations. Default 1 (5 allele bias states), otherwise 0 (3 allele bias states).

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.Combine_General_config

Bases: object

General configuration settings for combining BAF and RDR analyses.

This class manages the configuration settings for combining BAF and RDR analyses, including denoising options, copy number correction settings, plotting preferences, and whole-genome duplication (WGD) detection parameters.

BAF_denoise

Flag to enable BAF denoising.

Type:: bool

RDR_denoise

Flag to enable RDR denoising.

Type:: bool

copyloss_correct

Flag to apply copy loss correction (default is True).

Type:: bool

copyloss_correct_mode

Mode for copy loss correction.

Type:: int

copygain_correct

Flag to apply copy gain correction (default is False).

Type:: bool

copygain_correct_mode

Mode for copy gain correction, None if copygain_correct is False.

Type:: int or None

RDR_prior

Flag to prioritize RDR in combination analysis.

Type:: bool

xclone_plot

Flag to enable XClone plotting.

Type:: bool

plot_cell_anno_key

Annotation key for plotting cell annotations.

Type:: str or None

merge_loss

Flag to merge loss segments in plots.

Type:: bool

merge_loh

Flag to merge loss of heterozygosity (LOH) segments in plots.

Type:: bool

set_figtitle

Flag to set figure titles in plots.

Type:: bool

customizedplotting

Flag to get customized plot, related to the setting in merge_loss and merge_loh.

Type:: bool

WGD_detection

Flag to enable whole-genome duplication (WGD) detection.

Type:: bool

WGD_detect_genome_level

Genome level for WGD detection (e.g., “chr_arm”).

Type:: str

WGD_prop_value_threshold

Proportion value threshold for WGD detection.

Type:: float

WGD_cell_prop_threshold

Cell proportion threshold for WGD detection.

Type:: int

Initialize the Combine_General_config class with default combination parameters.

This method sets default values for combining BAF and RDR analyses, optimized for default settings.

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n General configuration settings for combining BAF and RDR analyses.\n\n This class manages the configuration settings for combining BAF and RDR analyses,\n including denoising options, copy number correction settings, plotting preferences,\n and whole-genome duplication (WGD) detection parameters.\n\n Attributes\n ----------\n\n BAF_denoise : bool\n Flag to enable BAF denoising.\n RDR_denoise : bool\n Flag to enable RDR denoising.\n copyloss_correct : bool\n Flag to apply copy loss correction (default is True).\n copyloss_correct_mode : int\n Mode for copy loss correction.\n copygain_correct : bool\n Flag to apply copy gain correction (default is False).\n copygain_correct_mode : int or None\n Mode for copy gain correction, None if copygain_correct is False.\n RDR_prior : bool\n Flag to prioritize RDR in combination analysis.\n xclone_plot : bool\n Flag to enable XClone plotting.\n plot_cell_anno_key : str or None\n Annotation key for plotting cell annotations.\n merge_loss : bool\n Flag to merge loss segments in plots.\n merge_loh : bool\n Flag to merge loss of heterozygosity (LOH) segments in plots.\n set_figtitle : bool\n Flag to set figure titles in plots.\n customizedplotting : bool\n Flag to get customized plot, related to the setting in `merge_loss` and `merge_loh`.\n WGD_detection : bool\n Flag to enable whole-genome duplication (WGD) detection.\n WGD_detect_genome_level : str\n Genome level for WGD detection (e.g., "chr_arm").\n WGD_prop_value_threshold : float\n Proportion value threshold for WGD detection.\n WGD_cell_prop_threshold : int\n Cell proportion threshold for WGD detection.\n ', '__init__': <function Combine_General_config.__init__>, '__dict__': <attribute '__dict__' of 'Combine_General_config' objects>, '__weakref__': <attribute '__weakref__' of 'Combine_General_config' objects>, '__annotations__': {}})

__init__()

Initialize the Combine_General_config class with default combination parameters.

This method sets default values for combining BAF and RDR analyses, optimized for default settings.

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.HMM_Configs

Bases: object

Configuration settings for Hidden Markov Model (HMM) smoothing.

This class manages the configuration settings for HMM smoothing, including transition probabilities, HMM breaks, and module-specific settings for RDR and BAF.

trans_t

base setting for transition probability.

Type:: float

HMM_brk

Break point for HMM analysis (e.g., “chr_arm”).

Type:: str

start_prob

Starting probabilities for the HMM states.

Type:: numpy.ndarray

trans_prob

Transition probabilities for the HMM states.

Type:: numpy.ndarray

max_iter

Maximum number of iterations for HMM.

Type:: int

min_iter

Minimum number of iterations for HMM.

Type:: int

module

Module type for HMM configuration (“RDR” or “BAF”).

Type:: str

CNV_N_components

Number of CNV components, relevant for BAF module.

Type:: int

Initialize the HMM_Configs class with default HMM smoothing parameters.

This method sets default values for HMM smoothing parameters, optimized for different modules (RDR and BAF).

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n Configuration settings for Hidden Markov Model (HMM) smoothing.\n\n This class manages the configuration settings for HMM smoothing, \n including transition probabilities, HMM breaks, and module-specific settings for RDR and BAF.\n\n Attributes\n ----------\n\n trans_t : float\n base setting for transition probability.\n HMM_brk : str\n Break point for HMM analysis (e.g., "chr_arm").\n start_prob : numpy.ndarray\n Starting probabilities for the HMM states.\n trans_prob : numpy.ndarray\n Transition probabilities for the HMM states.\n max_iter : int\n Maximum number of iterations for HMM.\n min_iter : int\n Minimum number of iterations for HMM.\n module : str\n Module type for HMM configuration ("RDR" or "BAF").\n CNV_N_components : int\n Number of CNV components, relevant for BAF module.\n ', '__init__': <function HMM_Configs.__init__>, '__dict__': <attribute '__dict__' of 'HMM_Configs' objects>, '__weakref__': <attribute '__weakref__' of 'HMM_Configs' objects>, '__annotations__': {}})

__init__()

Initialize the HMM_Configs class with default HMM smoothing parameters.

This method sets default values for HMM smoothing parameters, optimized for different modules (RDR and BAF).

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.Smartseq_Config

Bases: object

Configuration settings specific to Smart-seq data analysis.

This class manages the configuration settings for Smart-seq data, including module-specific settings for RDR, BAF, and their combination, as well as general settings.

module

Module type for configuration (“RDR”, “BAF”, or “Combine”).

Type:: str

smart_transform

Flag to enable smart transformation (RDR module).

Type:: bool

filter_ref_ave

Reference average filter threshold (RDR module).

Type:: float

start_prob

Starting probabilities for the HMM states (RDR module).

Type:: numpy.ndarray

extreme_count_cap

Flag to cap extreme counts (BAF module).

Type:: bool

gene_specific_concentration

Flag to enable gene-specific concentration (BAF module).

Type:: bool

concentration

Concentration value, None if gene_specific_concentration is True (BAF module).

Type:: None

WMA_window_size

Window size for Weighted Moving Average (WMA) smoothing (BAF module).

Type:: int

exclude_XY

Flag to exclude sex chromosomes (general setting).

Type:: bool

remove_guide_XY

Flag to remove guide for sex chromosomes (general setting).

Type:: bool

Initialize the Smartseq_Config class with default Smart-seq specific parameters.

This method sets default values for Smart-seq specific parameters, optimized for different modules (RDR, BAF, Combine).

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n Configuration settings specific to Smart-seq data analysis.\n\n This class manages the configuration settings for Smart-seq data, including\n module-specific settings for RDR, BAF, and their combination, as well as general settings.\n\n Attributes\n ----------\n\n module : str\n Module type for configuration ("RDR", "BAF", or "Combine").\n smart_transform : bool\n Flag to enable smart transformation (RDR module).\n filter_ref_ave : float\n Reference average filter threshold (RDR module).\n start_prob : numpy.ndarray\n Starting probabilities for the HMM states (RDR module).\n extreme_count_cap : bool\n Flag to cap extreme counts (BAF module).\n gene_specific_concentration : bool\n Flag to enable gene-specific concentration (BAF module).\n concentration : None\n Concentration value, None if gene_specific_concentration is True (BAF module).\n WMA_window_size : int\n Window size for Weighted Moving Average (WMA) smoothing (BAF module).\n exclude_XY : bool\n Flag to exclude sex chromosomes (general setting).\n remove_guide_XY : bool\n Flag to remove guide for sex chromosomes (general setting).\n ', '__init__': <function Smartseq_Config.__init__>, '__dict__': <attribute '__dict__' of 'Smartseq_Config' objects>, '__weakref__': <attribute '__weakref__' of 'Smartseq_Config' objects>, '__annotations__': {}})

__init__()

Initialize the Smartseq_Config class with default Smart-seq specific parameters.

This method sets default values for Smart-seq specific parameters, optimized for different modules (RDR, BAF, Combine).

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

class xclone.Spatial_Config

Bases: object

Configuration settings specific to spatial transcriptomics analysis.

This class manages the configuration settings for spatial transcriptomics data, including module-specific settings for RDR, BAF, and their combination, as well as general settings.

module

Module type for configuration (“RDR”, “BAF”, or “Combine”).

Type:: str

smart_transform

Flag to enable smart transformation (RDR module).

Type:: bool

spatial_transform

Flag to enable spatial transformation (RDR module).

Type:: bool

filter_ref_ave

Reference average filter threshold (RDR module).

Type:: float

min_gene_keep_num

Minimum number of genes to keep (RDR module).

Type:: int

start_prob

Starting probabilities for the HMM states (RDR module).

Type:: numpy.ndarray

extreme_count_cap

Flag to cap extreme counts (BAF module).

Type:: bool

gene_specific_concentration

Flag to enable gene-specific concentration (BAF module).

Type:: bool

concentration

Concentration value, None if gene_specific_concentration is True (BAF module).

Type:: None

WMA_window_size

Window size for Weighted Moving Average (WMA) smoothing (BAF module).

Type:: int

exclude_XY

Flag to exclude sex chromosomes (general setting).

Type:: bool

remove_guide_XY

Flag to remove guide for sex chromosomes (general setting).

Type:: bool

Initialize the Spatial_Config class with default spatial transcriptomics specific parameters.

This method sets default values for spatial transcriptomics specific parameters, optimized for different modules (RDR, BAF, Combine).

Parameters:: None

__dict__ = mappingproxy({'__module__': 'xclone._config', '__doc__': '\n Configuration settings specific to spatial transcriptomics analysis.\n\n This class manages the configuration settings for spatial transcriptomics data, \n including module-specific settings for RDR, BAF, and their combination, as well as general settings.\n\n Attributes\n ----------\n\n module : str\n Module type for configuration ("RDR", "BAF", or "Combine").\n smart_transform : bool\n Flag to enable smart transformation (RDR module).\n spatial_transform : bool\n Flag to enable spatial transformation (RDR module).\n filter_ref_ave : float\n Reference average filter threshold (RDR module).\n min_gene_keep_num : int\n Minimum number of genes to keep (RDR module).\n start_prob : numpy.ndarray\n Starting probabilities for the HMM states (RDR module).\n extreme_count_cap : bool\n Flag to cap extreme counts (BAF module).\n gene_specific_concentration : bool\n Flag to enable gene-specific concentration (BAF module).\n concentration : None\n Concentration value, None if gene_specific_concentration is True (BAF module).\n WMA_window_size : int\n Window size for Weighted Moving Average (WMA) smoothing (BAF module).\n exclude_XY : bool\n Flag to exclude sex chromosomes (general setting).\n remove_guide_XY : bool\n Flag to remove guide for sex chromosomes (general setting).\n ', '__init__': <function Spatial_Config.__init__>, '__dict__': <attribute '__dict__' of 'Spatial_Config' objects>, '__weakref__': <attribute '__weakref__' of 'Spatial_Config' objects>, '__annotations__': {}})

__init__()

Initialize the Spatial_Config class with default spatial transcriptomics specific parameters.

This method sets default values for spatial transcriptomics specific parameters, optimized for different modules (RDR, BAF, Combine).

Parameters:: None

__module__ = 'xclone._config'

__weakref__: list of weak references to the object (if defined)

RDR module 

xclone.model.run_RDR(RDR_adata, verbose=True, config_file=None)

Run the RDR (Read Depth Ratio) analysis on the provided annotated data.

This function is an updated version of the function run_RDR in the XClone package. It uses a Gaussian mixture model to process log-transformed read depth ratios and performs CNV (Copy Number Variation) analysis based on the provided configuration.

This function performs the RDR analysis using the provided annotated data (RDR_adata). It allows for verbose output and the use of a custom configuration object. If no configuration object is specified, default settings from XClone’s RDR module will be used.

Parameters:

RDR_adata (anndata.AnnData) – The annotated data matrix on which the RDR analysis will be performed.
verbose (bool, optional) – If True, prints detailed information about the process. Default is True.
config_file (xclone.XCloneConfig or None, optional) –
The XClone configuration object. If None, the default settings in XClone-RDR will be used. Default is None. The configuration can be created as follows:
```
config_file = xclone.XCloneConfig(dataset_name="your_dataset_name", module="RDR_gaussian")
```

Returns:

RDR_adataanndata.AnnData: The finalized output with multiple layers of information in the anndata.AnnData from RDR module.

Example

import xclone

# Run RDR analysis with default settings
RDR_Xdata = xclone.model.run_RDR_gaussian(RDR_adata, verbose=True)

# Run RDR analysis with a custom configuration object
xconfig = xclone.XCloneConfig(dataset_name = dataset_name, module = "RDR_gaussian")
xconfig.outdir = out_dir
#... other specified parameters in `xconfig`
xconfig.display()
RDR_Xdata = xclone.model.run_RDR_gaussian(RDR_adata, verbose=True, config_file=xconfig)

BAF module 

xclone.model.run_BAF(BAF_adata, verbose=True, run_verbose=True, config_file=None)

Run the BAF (B Allele Frequency) analysis on the provided annotated data.

This function performs the BAF analysis using the provided annotated data (BAF_adata). It allows for verbose output and the use of a custom configuration object. If no configuration object is specified, default settings from XClone’s BAF module will be used.

Parameters:

BAF_adata (anndata.AnnData) – The annotated data matrix on which the BAF analysis will be performed.
verbose (bool, optional) – If True, prints detailed information about the process. Default is True.
run_verbose (bool, optional) – If True, provides verbose output during the run. Default is True.
config_file (xclone.XCloneConfig or None, optional) –
The XClone configuration object. If None, the default settings in XClone-BAF will be used. Default is None. The configuration can be created as follows:
```
config_file = xclone.XCloneConfig(dataset_name="your_dataset_name", module="BAF")
```

Returns:

merge_Xdataanndata.AnnData: The finalized output with multiple layers of information in the anndata.AnnData from BAF module. It is at bin level.

Example

import xclone

# Run BAF analysis with default settings
BAF_merge_Xdata = xclone.model.run_BAF(BAF_adata, verbose=True, run_verbose=True)

# Run BAF analysis with a custom configuration object
xconfig = xclone.XCloneConfig(dataset_name = dataset_name, module = "BAF")
xconfig.outdir = out_dir
#... other specified parameters in `xconfig`
xconfig.display()
BAF_merge_Xdata = xclone.model.run_BAF(BAF_adata, verbose=True, run_verbose=True, config_file=xconfig)

Combine module 

xclone.model.run_combine(RDR_Xdata, BAF_merge_Xdata, verbose=True, run_verbose=True, config_file=None)

Run the Combine (RDR & BAF) analysis on the provided annotated data.

This function performs the combine analysis using the provided annotated data (RDR_adata & BAF_merge_Xdata). It allows for verbose output and the use of a custom configuration object. If no configuration object is specified, default settings from XClone’s Combine module will be used.

Parameters:

RDR_Xdata (anndata.AnnData) – The annotated data matrix output by the RDR moudle analysis.
BAF_merge_Xdata (anndata.AnnData) – The annotated data matrix output by the BAF moudle analysis.
verbose (bool, optional) – If True, prints detailed information about the process. Default is True.
run_verbose (bool, optional) – If True, provides verbose output during the run. Default is True.
config_file (xclone.XCloneConfig or None, optional) –
The XClone configuration object. If None, the default settings in XClone-RDR will be used. Default is None. The configuration can be created as follows:
```
config_file = xclone.XCloneConfig(dataset_name="your_dataset_name", module="Combine")
```

Returns:

combine_Xdataanndata.AnnData: The finalized output with multiple layers of information in the anndata.AnnData from Combine module.

Example

import xclone

# Run Combine analysis with default settings
combine_Xdata = xclone.model.run_combine(RDR_Xdata, BAF_merge_Xdata, verbose=True, run_verbose=True)

# Run Combine analysis with a custom configuration object
xconfig = xclone.XCloneConfig(dataset_name = dataset_name, module = "Combine")
xconfig.outdir = out_dir
#... other specified parameters in `xconfig`
xconfig.display()
combine_Xdata = xclone.model.run_combine(RDR_Xdata, BAF_merge_Xdata, verbose=True, run_verbose=True, config_file=xconfig)

Plotting 

Basic Heatmap plot 

xclone.plot.CNV_visualization(Xdata, Xlayer='posterior_mtx', weights=True, states_weight=array([1, 2, 3]), states_num=3, colorbar_name='RDR states', cell_anno_key='cell_type', **kwargs)

Visualize Copy Number Alterations (CNA) for the provided data.

This function visualizes inferred CNA states based on the Read Depth Ratio (RDR). By default, it uses the .layers[“posterior_mtx”] for visualization. The RDR states typically represent copy loss, copy neutral, and copy gain.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing the CNA probability inferred from RDR.
Xlayer (str, optional) – The layer in Xdata to be used for visualization. Default is “posterior_mtx”.
weights (bool, optional) – If True, use weighted visualization. If False, use category visualization. Default is True.
states_weight (numpy.ndarray, optional) – The weights for the CNA states. Default is np.array([1, 2, 3]).
states_num (int, optional) – The number of CNA states. Default is 3 in RDR module.
colorbar_name (str, optional) – The name to be displayed on the colorbar. Default is “RDR states”.
cell_anno_key (str, optional) – The key for cell annotations used to reorder cells for visualization. Default is “cell_type”.
**kwargs (dict) – Additional keyword arguments passed to the Xheatmap function.

Returns:

None

Example

import xclone
import anndata
import numpy as np

# Visualize CNA with default settings
xclone.pl.CNV_visualization(Xdata)

# Visualize CNA with custom settings
xclone.pl.CNV_visualization(Xdata, Xlayer="custom_layer",
                            colorbar_name="Custom RDR states",
                            cell_anno_key="custom_cell_type")

xclone.plot.BAF_CNV_visualization(Xdata, Xlayer='posterior_mtx', weights=False, states_weight=array([1, 2, 3]), colorbar_name='BAF states', cell_anno_key='cell_type', **kwargs)

Visualize Allele bias state inferred from B-allele frequency (BAF) for the provided data.

By default, it uses the .layers[“posterior_mtx”] for visualization. The BAF states typically represent “allele-A bias”, “allele balance”, and “allele-B bias” (copy loss (haplotype specific) and copy neutral). With higher resolution, it can represent “allele-A bias (++)”, “allele-A bias (+)”, “allele balance”, “allele-B bias (+)” and “allele-B bias (++)”. Allele bias 5 states are only supported for category visualization. State number to be displayed are detected automatically from the provided Xlayer.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing allele bia probability inferred from BAF.
Xlayer (str, optional) – The layer in Xdata to be used for visualization. Default is “posterior_mtx”.
weights (bool, optional) – If True, use weighted visualization. If False, use category visualization. Default is False.
states_weight (numpy.ndarray, optional) – The weights for the allele bia states. Default is np.array([1, 2, 3]).
colorbar_name (str, optional) – The name to be displayed on the colorbar. Default is “BAF states”.
cell_anno_key (str, optional) – The key for the cell annotation used to reorder cells for visualization. Default is “cell_type”.
**kwargs (dict) – Additional keyword arguments passed to the Xheatmap function.

Returns:

None

Example

import xclone
# Visualize BAF CNV with default settings
xclone.pl.BAF_CNV_visualization(Xdata)

# Visualize BAF CNV with custom settings
xclone.pl.BAF_CNV_visualization(Xdata, Xlayer="custom_layer", weights=True,
                                cell_anno_key="custom_anno",
                                colorbar_name="Custom BAF states")

xclone.plot.Combine_CNV_visualization(Xdata, Xlayer, states_num=4, cell_anno_key='cell_type', color_map_name=None, colorbar_ticks=None, colorbar_label=None, **kwargs)

Visualize precise CNA states inferred from combination of RDR and BAF information.

By default, it visualizes 4 states: copy loss, loss of heterozygosity (loh), copy neutral, and copy gain.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing CNA states.
Xlayer (str) – The layer in Xdata to be used for visualization.
states_num (int, optional) – The number of CNA states to visualize. Default is 4.
cell_anno_key (str, optional) – The key for the cell annotation used to reorder cells for visualization. Default is “cell_type”.
color_map_name (str, optional) – The name of the color map to use for visualization. Default is None, which uses “combine_cmap”.
colorbar_ticks (list of int, optional) – The positions of the ticks on the colorbar. Default is None, which uses [0, 1, 2, 3].
colorbar_label (list of str, optional) – The labels for the ticks on the colorbar. Default is None, which uses [“copy loss”, “loh”, “copy neutral”, “copy gain”].
**kwargs (dict) – Additional keyword arguments passed to the Xheatmap function.

Returns:

None

Example

import xclone

# Visualize combined CNA with custom settings
colorbar_ticks = [0.25,1,2,2.75]
colorbar_label = ["copy loss","loh", "copy neutral", "copy gain"]
xclone.pl.Combine_CNV_visualization(combine_Xdata, Xlayer = "plot_prob_merge1",
                            cell_anno_key = plot_cell_anno_key,
                            color_map_name = "combine_cmap",
                            states_num = 4,
                            colorbar_ticks = colorbar_ticks,
                            colorbar_label = colorbar_label,
                            title = fig_title,
                            save_file = True,
                            out_file = combine_res_select_fig,
                            **kwargs)

Complex Annotated Heatmap plot 

xclone.plot.Complex_CNV_visualization(Xdata, Xlayer='posterior_mtx', weights=True, states_weight=array([1, 2, 3]), states_num=3, cell_anno_key=['cluster', 'cell_type'], colorbar_name='RDR states', clusters_display_name=['Clone', 'Celltype'], **kwargs)

Visualize complex Copy Number Alterations (CNA) for the provided data with multiple annotations.

This function visualizes CNA based on the Read Depth Ratio (RDR) states, using multiple cell annotations. By default, it uses the .layers[“posterior_mtx”] for visualization. The RDR states typically represent copy loss, copy neutral, and copy gain.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing the CNA probability inferred from RDR.
Xlayer (str, optional) – The layer in Xdata to be used for visualization. Default is “posterior_mtx”.
weights (bool, optional) – If True, use weighted visualization. If False, use category visualization. Default is True.
states_weight (numpy.ndarray, optional) – The weights for the CNA states. Default is np.array([1, 2, 3]).
states_num (int, optional) – The number of CNA states. Default is 3.
cell_anno_key (list of str, optional) – The keys for cell annotations used to reorder cells for visualization. Default is [“cluster”, “cell_type”].
colorbar_name (str, optional) – The name to be displayed on the colorbar. Default is “RDR states”.
clusters_display_name (list of str, optional) – The display names for the clusters annotation in the visualization. Default is [“Clone”, “Celltype”].
**kwargs (dict) – Additional keyword arguments passed to the XXheatmap function.

Returns:

None

Example

import xclone
# Visualize complex CNV with default settings
xclone.pl.Complex_CNV_visualization(Xdata)

# Visualize complex CNV with custom settings
xclone.pl.Complex_CNV_visualization(Xdata, Xlayer="custom_layer", weights=False,
                                    cell_anno_key=["custom_anno1", "custom_anno2"],
                                    colorbar_name="Custom RDR states",
                                    clusters_display_name=["Custom Clone", "Custom Celltype"])

xclone.plot.Complex_BAF_CNV_visualization(Xdata, Xlayer='posterior_mtx', weights=False, states_weight=array([1, 2, 3]), colorbar_name='BAF states', cell_anno_key=['cluster', 'cell_type'], clusters_display_name=['Clone', 'Celltype'], **kwargs)

Visualize Complex Allele bias states inferred from B-allele frequency (BAF) for the provided data with multiple annotations.

By default, it uses the .layers[“posterior_mtx”] for visualization. The BAF states typically represent “allele-A bias”, “allele balance”, and “allele-B bias” for 3 states, and can represent “allele-A bias (++)”, “allele-A bias (+)”, “allele balance”, “allele-B bias (+)”, and “allele-B bias (++)” for 5 states. State number to be displayed are detected automatically from the provided Xlayer.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing allele bias probability inferred from BAF.
Xlayer (str, optional) – The layer in Xdata to be used for visualization. Default is “posterior_mtx”.
weights (bool, optional) – If True, use weighted visualization. If False, use category visualization. Default is False.
states_weight (numpy.ndarray, optional) – The weights for the allele bias states. Default is np.array([1, 2, 3]).
colorbar_name (str, optional) – The name to be displayed on the colorbar. Default is “BAF states”.
cell_anno_key (list of str, optional) – The keys for the cell annotations used to reorder cells for visualization. Default is [“cluster”, “cell_type”].
clusters_display_name (list of str, optional) – The display names for the clusters. Default is [“Clone”, “Celltype”].
**kwargs (dict) – Additional keyword arguments passed to the XXheatmap function.

Returns:

None

Example

import xclone
# Visualize complex BAF CNV with default settings
xclone.pl.Complex_BAF_CNV_visualization(Xdata)

# Visualize complex BAF CNV with custom settings
xclone.pl.Complex_BAF_CNV_visualization(Xdata, Xlayer="custom_layer", weights=True,
                                        cell_anno_key=["custom_cluster", "custom_cell_type"],
                                        clusters_display_name=["Custom Clone", "Custom Celltype"],
                                        colorbar_name="Custom BAF states")

xclone.plot.Complex_Combine_CNV_visualization(Xdata, Xlayer, states_num=4, cell_anno_key=['cluster', 'cell_type'], clusters_display_name=['Clone', 'Celltype'], color_map_name=None, colorbar_ticks=None, colorbar_label=None, **kwargs)

Adapted from Combine_CNV_visualization to visualize multiple annotations.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing CNA states.
Xlayer (str) – The layer in Xdata to be used for visualization.
states_num (int, optional) – The number of CNA states to visualize. Default is 4.
cell_anno_key (list of str, optional) – The keys for the cell annotations used to reorder cells for visualization. Default is [“cluster”, “cell_type”].
clusters_display_name (list of str, optional) – The display names for the clusters. Default is [“Clone”, “Celltype”].
color_map_name (str, optional) – The name of the color map to use for visualization. Default is None, which uses “combine_cmap”.
colorbar_ticks (list of int, optional) – The positions of the ticks on the colorbar. Default is None, which uses [0, 1, 2, 3].
colorbar_label (list of str, optional) – The labels for the ticks on the colorbar. Default is None, which uses [“copy loss”, “loh”, “copy neutral”, “copy gain”].
**kwargs (dict) – Additional keyword arguments passed to the XXheatmap function.

Returns:

None

Example

import xclone

# Visualize combined CNA with custom settings
colorbar_ticks = [0.25,1,2,2.75]
colorbar_label = ["copy loss","loh", "copy neutral", "copy gain"]
xclone.pl.Complex_Combine_CNV_visualization(combine_Xdata, Xlayer = "plot_prob_merge1",
                            cell_anno_key = plot_cell_anno_key,
                            color_map_name = "combine_cmap",
                            states_num = 4,
                            cell_anno_key = ["cluster", "cell_type"],
                            clusters_display_name = ["Clone", "Celltype"],
                            colorbar_ticks = colorbar_ticks,
                            colorbar_label = colorbar_label,
                            title = fig_title,
                            save_file = True,
                            out_file = combine_res_select_fig,
                            **kwargs)

Allele frequency plot 

xclone.plot.visualize_cell_BAF(Xdata, Xlayer='BAF', cell_anno_key='cell_type', chr_anno_key='chr', chr_lst=None, shrink_BAF=False, default_show=False, **kwargs)

Visualize B-allele frequency (BAF) for the provided data.

This function visualizes the BAF values for cells, optionally allowing for chromosome-specific visualization, reordering by cell type, and applying a shrinkage transformation to the BAF values.

Parameters:

Xdata (anndata.AnnData) – The annotated data matrix containing BAF values.
Xlayer (str, optional) – The layer in Xdata to be used for visualization. Default is “BAF”.
cell_anno_key (str, optional) – The key for the cell annotation used to reorder cells for visualization. Default is “cell_type”.
chr_anno_key (str, optional) – The key for the chromosome annotation in Xdata.var. Default is “chr”.
chr_lst (list of str, optional) – The list of chromosomes to visualize. Default is None, which visualizes all chromosomes.
shrink_BAF (bool, optional) – If True, apply shrinkage to the BAF values around 0.5. Default is False.
default_show (bool, optional) – If True, use default settings for the heatmap. If False, use custom settings. Default is False.
**kwargs (dict) – Additional keyword arguments passed to the Xheatmap function.

Returns:

None

Example

import xclone
# Visualize BAF with default settings
xclone.pl.visualize_cell_BAF(Xdata)

# Visualize BAF for specific chromosomes with custom settings
xclone.pl.visualize_cell_BAF(Xdata, chr_lst=["chr1", "chr2"], shrink_BAF=True, default_show=True)

API Documentation

Commands 

Functions 

Read / Load 

Config module-specific parmas 

Main config manager 

Module specific config manager 

RDR module 

BAF module 

Combine module 

Plotting 

Basic Heatmap plot 

Complex Annotated Heatmap plot 

Allele frequency plot 

Read Depth Ratio plot 

VCF processing 

XClone Object 

Clustering 

Spatial analysis 

Extract Output 