---------------------------------------------------------------------- This is the API documentation for the omero_screen_plots library. ---------------------------------------------------------------------- ## Cell cycle Phase distributions and stacked composition plots. cellcycle_plot(df: pandas.core.frame.DataFrame, conditions: list[str], condition_col: str = 'condition', selector_col: str | None = 'cell_line', selector_val: str | None = None, title: str | None = None, fig_size: tuple[float, float] = (6, 6), size_units: str = 'cm', colors: list[str] | None = None, save: bool = True, save_stats: bool = False, path: Optional[pathlib.Path] = None, tight_layout: bool = False, file_format: str = 'pdf', dpi: int = 300, show_significance: bool = True, show_repeat_points: bool = True, rotation: int = 45, cc_phases: bool = True, show_subG1: bool = False, show_plate_legend: bool = False, paired: bool = True, show_ns: bool = True, min_effect: float | None = None) -> tuple[matplotlib.figure.Figure, list[matplotlib.axes._axes.Axes]] Plot cell cycle phases in a 2x2 subplot grid with statistical analysis. This is a backward-compatible wrapper around the new class-based architecture. Creates a 2x2 subplot grid showing each cell cycle phase (G1, S, G2/M, Polyploid) separately with repeat points and significance marks. Note: Unlike other plot functions, this returns (Figure, list of Axes) because it creates multiple subplots that cannot be collapsed into a single axis. Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing cell cycle data with required columns: 'cell_cycle', 'plate_id', and condition_col. conditions : list[str] List of condition names to plot. condition_col : str, default="condition" Column name for experimental condition. selector_col : str | None, default="cell_line" Column name for selector (e.g., cell line). selector_val : str | None, default=None Value to filter selector_col by. Display Options ^^^^^^^^^^^^^^^ cc_phases : bool, default=True If True, use cell cycle terminology {Sub-G1, G1, S, G2/M, Polyploid}. If False, use DNA content terminology {<2N, 2N, S, 4N, >4N}. show_subG1 : bool, default=False Whether to include Sub-G1/<2N phase in the plot. show_significance : bool, default=True Whether to show significance marks (requires ≥3 plates). paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id) per phase; set False for the unpaired ttest_ind. show_repeat_points : bool, default=True Whether to show individual repeat points. show_plate_legend : bool, default=False Whether to show legend with different shapes for each plate_id. Styling & Colors ^^^^^^^^^^^^^^^^ title : str | None, default=None Plot title. If None, generates default title. fig_size : tuple[float, float], default=(6, 6) Dimensions of the figure. size_units : str, default="cm" Units of the figure size ("cm" or "inch"). colors : list[str] | None, default=None List of colors for plotting. If None, uses default phase colors: G1=PINK, S=LIGHT_BLUE, G2/M=YELLOW, Polyploid=BLUE. rotation : int, default=45 Rotation angle for x-axis labels. tight_layout : bool, default=False Whether to use tight layout. Save Options ^^^^^^^^^^^^ save : bool, default=True Whether to save the figure. save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Optional[Path], default=None Path to save the figure. file_format : str, default="pdf" Format of the figure ("pdf", "png", "svg", etc.). dpi : int, default=300 Resolution of the figure. Returns: ------- tuple[Figure, list] The figure object and list of 4 axes objects [top-left, top-right, bottom-left, bottom-right]. Examples: -------- >>> fig, axes = cellcycle_plot( ... df=data, ... conditions=["control", "treatment"], ... selector_val="MCF10A", ... save=False ... ) >>> plt.show() >>> # Custom colors >>> fig, axes = cellcycle_plot( ... df=data, ... conditions=["ctrl", "drug1", "drug2"], ... colors=["red", "green", "blue", "purple"], ... title="Custom Cell Cycle Analysis" ... ) cellcycle_stacked(df: pandas.core.frame.DataFrame, conditions: list[str], condition_col: str = 'condition', selector_col: str | None = 'cell_line', selector_val: str | None = None, axes: matplotlib.axes._axes.Axes | None = None, title: str | None = None, fig_size: tuple[float, float] = (6, 6), size_units: str = 'cm', colors: list[str] | None = None, save: bool = False, save_stats: bool = False, path: pathlib.Path | None = None, tight_layout: bool = False, file_format: str = 'pdf', dpi: int = 300, show_triplicates: bool = False, show_error_bars: bool = True, show_boxes: bool = True, cc_phases: bool = True, phase_order: list[str] | None = None, group_size: int = 1, within_group_spacing: float = 0.2, between_group_gap: float = 0.5, paired: bool = True, show_ns: bool = True, min_effect: float | None = None, bar_width: float = 0.5, repeat_offset: float = 0.18, max_repeats: int = 3, x_label: bool = True, rotation: int = 45, show_legend: bool = True) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes] Create a stacked barplot for cell cycle phase proportions with flexible display modes. This is a unified wrapper around the new StackedCellCyclePlot class that can create either summary stacked bars (with error bars) or individual triplicate bars (with boxes). Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing cell cycle data with required columns: 'cell_cycle', 'plate_id', and condition_col. conditions : list[str] List of condition names to plot. condition_col : str, default="condition" Column name for experimental condition. selector_col : str | None, default="cell_line" Column name for selector (e.g., cell line). selector_val : str | None, default=None Value to filter selector_col by. Display Options ^^^^^^^^^^^^^^^ show_triplicates : bool, default=False If True, show individual bars for each replicate/plate with boxes. If False, show summary bars with optional error bars. show_error_bars : bool, default=True Whether to show error bars (only applies when show_triplicates=False). show_boxes : bool, default=True Whether to draw boxes around triplicates (only applies when show_triplicates=True). cc_phases : bool, default=True If True, use cell cycle terminology {Sub-G1, G1, S, G2/M, Polyploid}. If False, use DNA content terminology {<2N, 2N, S, 4N, >4N}. phase_order : list[str] | None, default=None Custom list of cell cycle phases to plot. If None, uses all available phases. axes : Axes | None, default=None Matplotlib axis. If None, a new figure is created. x_label : bool, default=True Whether to show the x-axis labels. rotation : int, default=45 Rotation angle for x-axis labels. show_legend : bool, default=True Whether to show the legend with cell cycle phase colors. Grouping & Layout ^^^^^^^^^^^^^^^^^ group_size : int, default=1 Number of conditions per group on the x-axis (1 = no grouping). paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id) per phase for the exported stats; set False for the unpaired ttest_ind. The stacked plot draws no on-plot stars — stats are written to {title}_stats.csv / {title}_medians.csv when save=True. within_group_spacing : float, default=0.2 Spacing between bars within a group. between_group_gap : float, default=0.5 Spacing between groups. bar_width : float, default=0.5 Width of each bar. repeat_offset : float, default=0.18 Offset between replicate bars (only applies when show_triplicates=True). max_repeats : int, default=3 Maximum number of replicates to show (only applies when show_triplicates=True). Styling & Colors ^^^^^^^^^^^^^^^^ title : str | None, default=None Plot title. fig_size : tuple[float, float], default=(6, 6) Dimensions of the figure. size_units : str, default="cm" Units of the figure size ("cm" or "inch"). colors : list[str] | None, default=None List of colors for plotting phases. tight_layout : bool, default=False Whether to use tight layout. Save Options ^^^^^^^^^^^^ save : bool, default=False Whether to save the figure. save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Path | None, default=None Path to save the figure. file_format : str, default="pdf" Format of the figure. dpi : int, default=300 Resolution of the figure. Returns: ------- tuple[Figure, Axes] The figure and axes objects. Examples: -------- >>> # Simple summary stacked plot with error bars >>> fig, ax = cellcycle_stacked( ... df=data, ... conditions=["control", "treatment"], ... selector_val="MCF10A" ... ) >>> # Triplicate stacked plot with boxes >>> fig, ax = cellcycle_stacked( ... df=data, ... conditions=["control", "treatment"], ... show_triplicates=True, ... selector_val="MCF10A" ... ) >>> # Grouped stacked plot with custom phases >>> fig, ax = cellcycle_stacked( ... df=data, ... conditions=["ctrl", "drug1", "drug2", "drug3"], ... group_size=2, # Group in pairs ... cc_phases=True, # Use cell cycle terminology ... phase_order=["G1", "S", "G2/M"] # Exclude Sub-G1 and Polyploid ... ) >>> # Plot without legend (for subplots or custom legends) >>> fig, ax = cellcycle_stacked( ... df=data, ... conditions=["control", "treatment"], ... show_legend=False ... ) combplot_cellcycle(df: pandas.core.frame.DataFrame, conditions: list[str], condition_col: str = 'condition', selector_col: Optional[str] = 'cell_line', selector_val: Optional[str] = None, title: Optional[str] = None, cell_number: Optional[int] = 3000, cc_phases: bool = True, show_error_bars: bool = True, fig_size: tuple[float, float] = (12, 7), size_units: str = 'cm', save: bool = True, path: Optional[pathlib.Path] = None, file_format: str = 'png', dpi: int = 300) -> tuple[matplotlib.figure.Figure, list[typing.Any]] Create a combined plot with histograms, scatter plots, and cell cycle barplot. Creates a 2×(n_conditions+1) grid layout: - Top row: DNA content histograms for each condition + empty space for barplot - Bottom row: DNA vs EdU scatter plots for each condition + cell cycle stacked barplot Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing single-cell measurements with cell cycle data. conditions : list[str] List of condition names to plot. condition_col : str, default="condition" Column name for experimental condition. selector_col : Optional[str], default="cell_line" Column name for selector (e.g., cell line). selector_val : Optional[str], default=None Value to filter selector_col by. Display Options ^^^^^^^^^^^^^^^ cell_number : Optional[int], default=3000 Number of cells to sample per condition for plotting. cc_phases : bool, default=True If True, use cell cycle terminology. If False, use DNA content terminology. show_error_bars : bool, default=True Whether to show error bars on the stacked cell cycle barplot. Styling & Layout ^^^^^^^^^^^^^^^^ title : Optional[str], default=None Plot title. If None, generates default title. fig_size : tuple[float, float], default=(12, 7) Figure size as (width, height). size_units : str, default="cm" Units for fig_size ("cm" or "inches"). Save Options ^^^^^^^^^^^^ save : bool, default=True Whether to save the figure. path : Optional[Path], default=None Directory path for saving the figure. file_format : str, default="png" File format for saving ("png", "pdf", "svg", etc.). dpi : int, default=300 Resolution for saved figure. Returns: ------- tuple[Figure, list] The figure object and list of axes objects. Examples: -------- >>> fig, axes = combplot_cellcycle( ... df=data, ... conditions=["control", "treatment1", "treatment2"], ... selector_col="cell_line", ... selector_val="MCF10A" ... ) ## Counts and features Cell counts, per-feature comparisons and normalisation. count_plot(df: pandas.core.frame.DataFrame, norm_control: str, conditions: list[str], condition_col: str = 'condition', selector_col: str | None = 'cell_line', selector_val: str | None = None, plot_type: omero_screen_plots.countplot_factory.PlotType = , show_triplicates: bool = False, show_boxes: bool = True, repeat_offset: float = 0.18, title: str | None = None, colors: Any = , save: bool = False, save_stats: bool = False, dpi: int = 300, tight_layout: bool = False, file_format: str = 'pdf', path: pathlib.Path | None = None, fig_size: tuple[float, float] = (7, 7), size_units: str = 'cm', axes: matplotlib.axes._axes.Axes | None = None, group_size: int = 1, within_group_spacing: float = 0.2, between_group_gap: float = 0.5, x_label: bool = True, paired: bool = True, show_ns: bool = True, min_effect: float | None = None, normalise_within_plate: bool = True) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes] Plot normalized or absolute counts with optional grouping. This is a backward-compatible wrapper around the simplified architecture. Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame The dataframe to plot containing single-cell measurements. norm_control : str The control condition to normalize by (required even for absolute plots). conditions : list[str] The conditions to plot. condition_col : str, default="condition" The column name for the conditions. selector_col : str | None, default="cell_line" The column name for the selector. selector_val : str | None, default=None The value of the selector. Display Options ^^^^^^^^^^^^^^^ plot_type : PlotType, default=PlotType.NORMALISED The type of plot to create (NORMALISED or ABSOLUTE). show_triplicates : bool, default=False If True, show individual bars per replicate plate instead of the mean bar with overlay points. show_boxes : bool, default=True Whether to draw boxes around triplicates (only applies when show_triplicates=True). repeat_offset : float, default=0.18 Offset between replicate bars (only applies when show_triplicates=True). Grouping & Layout ^^^^^^^^^^^^^^^^^ group_size : int, default=1 The number of conditions to group together. paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id) for significance; set False for the unpaired ttest_ind. normalise_within_plate : bool, default=True Test the per-plate log fold-change ln(cond/control) vs 0 rather than the absolute count difference. Removes a multiplicative plate baseline so significance tracks effect size, not control stability. Requires ``paired=True``; set False for the legacy absolute-count test. within_group_spacing : float, default=0.2 The spacing between conditions within a group. between_group_gap : float, default=0.5 The gap between groups. Styling & Colors ^^^^^^^^^^^^^^^^ title : str | None, default=None The title of the plot. colors : Any, default=COLOR The colors to use for the plot. x_label : bool, default=True Whether to show x-axis labels. axes : Axes | None, default=None The axis to plot on. Layout & Sizing ^^^^^^^^^^^^^^^ fig_size : tuple[float, float], default=(7, 7) The size of the plot. size_units : str, default="cm" The units of the plot size. Save Options ^^^^^^^^^^^^ save : bool, default=False Whether to save the plot. save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Path | None, default=None The path to save the plot. file_format : str, default="pdf" The format of the plot. tight_layout : bool, default=False Whether to use tight layout. dpi : int, default=300 The resolution of the plot. Returns: ------- tuple[Figure, Axes] The figure and axes objects. feature_plot(df: pandas.core.frame.DataFrame, feature: str, conditions: list[str], axes: Optional[matplotlib.axes._axes.Axes] = None, x_label: bool = True, ymax: float | tuple[float, float] | None = None, condition_col: str = 'condition', selector_col: Optional[str] = 'cell_line', selector_val: Optional[str] = '', title: Optional[str] = '', colors: list[str] | None = None, fig_size: tuple[float, float] = (5, 5), size_units: str = 'cm', scale: bool = False, violin: bool = False, show_scatter: bool = True, legend: bool = True, group_size: int = 1, within_group_spacing: float = 0.2, between_group_gap: float = 0.5, paired: bool = True, show_significance: bool = True, show_ns: bool = True, scatter_size: float = 7.0, min_effect: float | None = None, normalise_within_plate: bool = True, save: bool = True, save_stats: bool = False, path: Optional[pathlib.Path] = None, tight_layout: bool = False, file_format: str = 'pdf', dpi: int = 300) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes] Plot a unified feature plot with box/violin plots and optional scatter points. This is a backward-compatible wrapper around the new class-based architecture. The feature plot can show either boxplots or violin plots, with optional scatter points overlaid, plus median points and significance marks. Statistical analysis is shown for all group sizes. Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame The dataframe to plot containing single-cell measurements. feature : str The feature column to plot. conditions : list[str] The conditions to plot. condition_col : str, default="condition" The column name for the conditions. selector_col : Optional[str], default="cell_line" The column name for the selector. selector_val : Optional[str], default="" The value of the selector. Display Options ^^^^^^^^^^^^^^^ violin : bool, default=False Whether to use violin plots instead of box plots. show_scatter : bool, default=True Whether to show scatter points overlay. ymax : float | tuple[float, float] | None, default=None The y-axis maximum value. scale : bool, default=False Whether to scale the data. Grouping & Layout ^^^^^^^^^^^^^^^^^ group_size : int, default=1 The number of conditions to group. paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id) for significance; set False for the unpaired ttest_ind. show_significance : bool, default=True Annotate significance marks. Set False to plot the distributions and the per-repeat medians without a test -- appropriate when n is small enough that the reader should judge the spread directly, or when many comparisons are shown side by side without correction. normalise_within_plate : bool, default=True Test the per-plate log fold-change ln(cond/control) vs 0 rather than the absolute feature difference. Removes a multiplicative plate baseline so significance tracks effect size (suited to area/intensity readouts). Requires ``paired=True``; set False for the legacy absolute test. within_group_spacing : float, default=0.2 The spacing between conditions within a group. between_group_gap : float, default=0.5 The gap between groups. Styling & Colors ^^^^^^^^^^^^^^^^ title : Optional[str], default="" The title of the plot. colors : list[str], default=COLORS The colors to use for the plot. legend : bool, default=True Whether to show the default plate legend. x_label : bool, default=True Whether to show the x-label. axes : Optional[Axes], default=None The axis to plot on. Layout & Sizing ^^^^^^^^^^^^^^^ fig_size : tuple[float, float], default=(5, 5) The size of the figure. size_units : str, default="cm" The units of the figure size. Save Options ^^^^^^^^^^^^ save : bool, default=True Whether to save the plot. save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Optional[Path], default=None The path to save the plot. file_format : str, default="pdf" The format of the saved figure. tight_layout : bool, default=False Whether to use tight layout. dpi : int, default=300 The resolution of the saved figure. Returns: ------- tuple[Figure, Axes] The figure and axes objects. feature_norm_plot(df: pandas.core.frame.DataFrame, feature: str, conditions: list[str], axes: Optional[matplotlib.axes._axes.Axes] = None, x_label: bool = True, condition_col: str = 'condition', selector_col: Optional[str] = 'cell_line', selector_val: Optional[str] = '', title: Optional[str] = '', color_scheme: str = 'green', legend: bool = False, fig_size: tuple[float, float] = (8, 6), size_units: str = 'cm', normalize_by_plate: bool = True, threshold: float = 1.5, save_norm_qc: bool = False, show_triplicates: bool = False, show_error_bars: bool = True, show_boxes: bool = True, group_size: int = 1, within_group_spacing: float = 0.2, between_group_gap: float = 0.5, paired: bool = True, show_ns: bool = True, scatter_size: float = 7.0, min_effect: float | None = None, save: bool = True, save_stats: bool = False, path: Optional[pathlib.Path] = None, tight_layout: bool = False, file_format: str = 'pdf', dpi: int = 300) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes] Create a normalized feature plot with threshold-based stacked bars. This plot normalizes the feature data by mode (peak=1.0) and displays the proportion of cells above/below a threshold as stacked bars. Optionally shows individual triplicate data with boxes. Parameters ---------- df : pd.DataFrame The dataframe containing single-cell measurements. feature : str The feature column to normalize and plot. conditions : list[str] The conditions to plot. axes : Optional[Axes], default=None The axis to plot on. x_label : bool, default=True Whether to show the x-label. condition_col : str, default="condition" The column name for the conditions. selector_col : Optional[str], default="cell_line" The column name for the selector. selector_val : Optional[str], default="" The value of the selector. title : Optional[str], default="" The title of the plot. color_scheme : str, default="green" Color scheme for positive/negative categories. Options: - "green": Olive (positive) and Light Green (negative) - "blue": Blue (positive) and Light Blue (negative) - "purple": Purple (positive) and Lavender (negative) Invalid values default to "green". legend : bool, default=False Whether to show the default plate legend. Default False since norm plots have their own threshold legend. fig_size : tuple[float, float], default=(8, 6) The size of the figure. size_units : str, default="cm" The units of the figure size. normalize_by_plate : bool, default=True Whether to normalize within each plate. threshold : float, default=1.5 The threshold value (times mode). save_norm_qc : bool, default=False Whether to save normalization QC plots. QC plots show the intensity distributions before/after normalization to document the process. Saved to the same path as the main plot with suffix "_norm_qc". show_triplicates : bool, default=False Whether to show individual triplicate bars. show_error_bars : bool, default=True Whether to show error bars on summary bars. show_boxes : bool, default=True Whether to draw boxes around triplicates. group_size : int, default=1 The number of conditions to group. paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id) for significance; set False for the unpaired ttest_ind. within_group_spacing : float, default=0.2 The spacing between conditions within a group. between_group_gap : float, default=0.5 The gap between groups. save : bool, default=True Whether to save the plot. save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Optional[Path], default=None The path to save the plot. tight_layout : bool, default=False Whether to use tight layout. file_format : str, default="pdf" The format of the saved figure. dpi : int, default=300 The resolution of the saved figure. Returns: ------- tuple[Figure, Axes] The figure and axes objects. Examples: -------- >>> # Basic normalized feature plot with default green scheme >>> fig, ax = feature_norm_plot( ... df=df, ... feature="intensity_mean_p21_nucleus", ... conditions=["control", "treatment1", "treatment2"], ... ) >>> # Blue color scheme with individual triplicates >>> fig, ax = feature_norm_plot( ... df=df, ... feature="intensity_mean_p21_nucleus", ... conditions=["control", "treatment1", "treatment2"], ... color_scheme="blue", ... show_triplicates=True, ... threshold=2.0, # Custom threshold at 2x mode ... ) >>> # Purple color scheme for publication >>> fig, ax = feature_norm_plot( ... df=df, ... feature="intensity_mean_p21_nucleus", ... conditions=["control", "treatment1", "treatment2"], ... color_scheme="purple", ... ) combplot_feature(df: pandas.core.frame.DataFrame, conditions: list[str], feature: Union[str, list[str]], threshold: Union[float, list[Optional[float]], NoneType] = None, condition_col: str = 'condition', selector_col: Optional[str] = 'cell_line', selector_val: Optional[str] = None, title: Optional[str] = None, cell_number: Optional[int] = 3000, fig_size: Optional[tuple[float, float]] = None, size_units: str = 'cm', save: bool = True, path: Optional[pathlib.Path] = None, file_format: str = 'png', dpi: int = 300, figure: Union[matplotlib.figure.Figure, matplotlib.figure.SubFigure, NoneType] = None, show_ylabel: bool = True, show_xlabel: bool = True) -> tuple[typing.Union[matplotlib.figure.Figure, matplotlib.figure.SubFigure], list[typing.Any]] Create a combined plot with histograms and scatter plots for feature analysis. Creates a ``(2 + n_features)×n_conditions`` grid layout that grows vertically with the number of features supplied: - Top row: DNA content histograms for each condition. - Second row: DNA vs EdU scatter plots with cell cycle phases. - One additional row per feature: DNA vs feature scatter plots with optional threshold colouring. Passing a single ``feature`` string reproduces the classic three-row layout (histogram → EdU → feature); passing a list of features stacks one scatter row per feature underneath the EdU row. Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing single-cell measurements. conditions : list[str] List of condition names to plot. condition_col : str, default="condition" Column name for experimental condition. selector_col : Optional[str], default="cell_line" Column name for selector (e.g., cell line). selector_val : Optional[str], default=None Value to filter selector_col by. Plot Configuration ^^^^^^^^^^^^^^^^^^ feature : str | list[str] Feature column name(s) for the stacked scatter rows. A single string creates one feature row; a list creates one row per entry, in order. threshold : float | list[float | None] | None, default=None Threshold value(s) for feature colouring (below=blue, above=red). A scalar (or ``None``) is applied to every feature row; a list must match the length of ``feature``, with ``None`` entries disabling the threshold for that row. cell_number : Optional[int], default=3000 Number of cells to sample per condition for plotting. Styling & Layout ^^^^^^^^^^^^^^^^ title : Optional[str], default=None Plot title. If None, generates default title. fig_size : Optional[tuple[float, float]], default=None Figure size as (width, height). When ``None`` the height scales with the number of rows (matching the classic ``(10, 7)`` default for a single feature). size_units : str, default="cm" Units for fig_size ("cm" or "inches"). Save Options ^^^^^^^^^^^^ save : bool, default=True Whether to save the figure. path : Optional[Path], default=None Directory path for saving the figure. file_format : str, default="png" File format for saving ("png", "pdf", "svg", etc.). dpi : int, default=300 Resolution for saved figure. Returns: ------- tuple[Figure, list] The figure object and list of axes objects. Examples: -------- Classic single-feature layout: >>> fig, axes = combplot_feature( ... df=data, ... conditions=["control", "treatment1", "treatment2"], ... feature="intensity_mean_p21_nucleus", ... threshold=5000, ... selector_col="cell_line", ... selector_val="MCF10A", ... ) Stack several features as extra rows (one threshold per feature, ``None`` to disable): >>> fig, axes = combplot_feature( ... df=data, ... conditions=["control", "treatment1"], ... feature=[ ... "intensity_mean_p21_nucleus", ... "intensity_mean_p53_nucleus", ... "area_cell", ... ], ... threshold=[5000, 3000, None], ... selector_col="cell_line", ... selector_val="MCF10A", ... ) PlotType(*values) Enumeration for plot types: normalised and absolute. ## Distributions Histograms and scatter plots of single-cell measurements. histogram_plot(df: pandas.core.frame.DataFrame, feature: str, conditions: str | list[str], condition_col: str = 'condition', selector_col: Optional[str] = None, selector_val: Optional[str] = None, axes: Optional[matplotlib.axes._axes.Axes] = None, title: Optional[str] = None, show_title: bool = False, colors: list[str] | None = None, fig_size: tuple[float, float] | None = None, size_units: str = 'cm', bins: int | str = 100, log_scale: bool = False, log_base: float = 2, x_limits: tuple[float, float] | None = None, normalize: bool = False, kde_overlay: bool = False, kde_smoothing: float = 0.8, kde_params: dict[str, typing.Any] | None = None, show_x_labels: bool = True, rotation: int = 0, save: bool = False, path: Optional[pathlib.Path] = None, tight_layout: bool = False, file_format: str = 'pdf', dpi: int = 300) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes | list[matplotlib.axes._axes.Axes]] Create histogram plot(s) for single or multiple conditions. This function creates histograms using seaborn.histplot with support for log scaling, custom binning, normalization, and KDE overlays. - If conditions is a string: Creates single histogram for that condition - If conditions is a list: Creates subplots with one histogram per condition Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame The dataframe containing the data to plot. feature : str The column name to create histogram for. conditions : str | list[str] Single condition (string) or multiple conditions (list) to plot. condition_col : str, default="condition" The column name for condition labels. selector_col : Optional[str], default=None The column name for additional filtering. selector_val : Optional[str], default=None The value to filter by if selector_col is provided. Display Options ^^^^^^^^^^^^^^^ bins : int | str, default=100 Number of bins or binning strategy. Default is 100 bins. Can be int for exact number or str for methods like "auto", "sturges", etc. For multiple conditions with int bins, calculates unified bin edges across all conditions for consistent visualization. log_scale : bool, default=False Whether to use logarithmic scaling for x-axis. log_base : float, default=2 Base for logarithmic scaling (only used if log_scale=True). x_limits : tuple[float, float] | None, default=None X-axis limits as (min, max). If None, uses data range. normalize : bool, default=False Whether to normalize histogram to show density instead of counts. kde_overlay : bool, default=False Whether to overlay KDE curves. When True, shows only KDE lines (no histograms) in a single plot with different colors for each condition. kde_smoothing : float, default=0.8 KDE smoothing factor (bw_adjust parameter). Lower = smoother curves. Typical range: 0.5 (very smooth) to 2.0 (more detailed). kde_params : dict[str, Any] | None, default=None Additional KDE parameters. Common options: - bw_method: 'scott' (default), 'silverman', or float for manual bandwidth - gridsize: int (default 200) - higher = smoother curves - cut: float (default 2) - how far to extend beyond data range show_x_labels : bool, default=True Whether to show x-axis tick labels. rotation : int, default=0 Rotation angle for x-axis tick labels. axes : Optional[Axes], default=None The matplotlib axes to plot on. Only valid for single condition (string). For multiple conditions, creates subplots automatically. Styling & Colors ^^^^^^^^^^^^^^^^ title : Optional[str], default=None The title of the plot. If None, auto-generates from feature and condition. show_title : bool, default=False Whether to display the title. When True, positions title at y-axis start. colors : list[str] | None, default=None Colors to use for the histogram. Uses first color in list. fig_size : tuple[float, float] | None, default=None The size of the figure in the specified units. If None, uses dynamic defaults: - Single condition: (4, 4) cm - Multiple conditions: (4 * num_conditions, 4) cm size_units : str, default="cm" The units for figure size ("cm" or "inches"). tight_layout : bool, default=False Whether to use tight layout when saving. Save Options ^^^^^^^^^^^^ save : bool, default=False Whether to save the plot to file. path : Optional[Path], default=None Directory path for saving the plot (required if save=True). file_format : str, default="pdf" File format for saved plot ("pdf", "png", "svg", etc.). dpi : int, default=300 Resolution for saved plot in dots per inch. Returns: ------- tuple[Figure, Axes | list[Axes]] The matplotlib Figure and Axes object(s). Returns: - (Figure, Axes) for single condition (string input) - (Figure, list[Axes]) for multiple conditions (list input) Raises: ------ ValueError If required parameters are missing or invalid. If specified columns are not found in dataframe. If no data remains after filtering. Examples: -------- >>> # Basic histogram for one condition >>> fig, ax = histogram_plot( ... df=df, ... feature="integrated_int_DAPI_norm", ... condition="control" ... ) >>> # Log-scale histogram with KDE overlay >>> fig, ax = histogram_plot( ... df=df, ... feature="integrated_int_DAPI_norm", ... condition="control", ... log_scale=True, ... log_base=2, ... kde_overlay=True, ... x_limits=(1, 16) ... ) >>> # Histogram with custom styling >>> fig, ax = histogram_plot( ... df=df, ... feature="area_nucleus", ... condition="treatment1", ... colors=["#1f77b4"], ... title="Nucleus Area Distribution - Treatment 1", ... bins=50, ... normalize=True ... ) >>> # Multiple histograms using subplots >>> fig, axes = plt.subplots(1, 3, figsize=(15, 5)) >>> conditions = ["control", "treatment1", "treatment2"] >>> for i, condition in enumerate(conditions): ... histogram_plot( ... df=df, ... feature="integrated_int_DAPI_norm", ... condition=condition, ... axes=axes[i], ... title=f"Histogram: {condition}" ... ) Notes: ----- This function creates histograms for single conditions. For multiple histograms: - Use this function multiple times with different axes - Use combplot functionality for complex layouts - Create subplots manually and pass axes parameter The function is designed for flexibility - it can integrate with existing plots by accepting an axes parameter, or create standalone plots when axes=None. For DNA content histograms (common in cell cycle analysis), consider: - Using log_scale=True with log_base=2 - Setting x_limits based on expected DNA content range - Using normalize=True for comparing different sample sizes scatter_plot(df: pandas.core.frame.DataFrame, conditions: str | list[str], condition_col: str = 'condition', selector_col: str | None = None, selector_val: str | None = None, x_feature: str | None = None, y_feature: str = 'intensity_mean_EdU_nucleus_norm', cell_number: int | None = 3000, hue: str | None = None, hue_order: list[str] | None = None, palette: list[str] | dict[str, str] | None = None, x_scale: Optional[Literal['linear', 'log']] = None, x_scale_base: int = 2, y_scale: Optional[Literal['linear', 'log']] = None, y_scale_base: int = 2, x_limits: tuple[float, float] | None = None, y_limits: tuple[float, float] | None = None, x_ticks: list[float] | None = None, y_ticks: list[float] | None = None, size: float = 2, alpha: float = 1.0, kde_overlay: bool | None = None, kde_cmap: str = 'rocket_r', kde_alpha: float = 0.1, vline: float | None = None, hline: float | None = None, line_style: str = '--', line_color: str = 'black', grid: bool = False, show_title: bool = False, title: str | None = None, x_label: str | None = None, y_label: str | None = None, show_legend: bool = False, legend_loc: str = 'best', legend_title: str | None = None, threshold: float | None = None, fig_size: tuple[float, float] | None = None, size_units: str = 'cm', dpi: int = 300, save: bool = False, path: pathlib.Path | None = None, file_format: str = 'pdf', tight_layout: bool = False, axes: matplotlib.axes._axes.Axes | None = None) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes | list[matplotlib.axes._axes.Axes]] Create a scatter plot with flexible configuration. This function provides a high-level API for creating scatter plots with support for multiple conditions, log scales, KDE overlays, and threshold-based coloring. Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing the data. conditions : str | list[str] Single condition string or list of conditions. condition_col : str, default="condition" Column containing condition labels. selector_col : str | None, default=None Optional column for additional filtering. selector_val : str | None, default=None Optional value for selector_col filtering. Plot Features ^^^^^^^^^^^^^ x_feature : str | None, default=None Column name for x-axis. When ``None`` (the default), resolves to the normalised DNA-content column via :func:`find_dna_norm_column` (e.g. ``integrated_int_DAPI_norm`` for legacy plates, ``integrated_int_Hoechst_norm`` for new plates). y_feature : str, default="intensity_mean_EdU_nucleus_norm" Column name for y-axis (default: EdU intensity). cell_number : int | None, default=3000 Number of cells to sample per condition (None = all). Display Options ^^^^^^^^^^^^^^^ hue : str | None, default=None Column name for color mapping (auto-detects cell_cycle). hue_order : list[str] | None, default=None Order for hue categories. palette : list[str] | dict[str, str] | None, default=None Colors for hue categories. size : float, default=2 Size of scatter points. alpha : float, default=1.0 Transparency of points. kde_overlay : bool | None, default=None Whether to add KDE overlay (auto for DNA vs EdU). kde_cmap : str, default="rocket_r" Colormap for KDE. kde_alpha : float, default=0.1 Transparency of KDE. grid : bool, default=False Whether to show grid. show_legend : bool, default=False Whether to show legend. legend_loc : str, default="best" Legend location. legend_title : str | None, default=None Legend title. Axes Settings ^^^^^^^^^^^^^ x_scale : Literal["linear", "log"] | None, default=None Scale type for x-axis ("linear" or "log", auto-detected). x_scale_base : int, default=2 Base for log scale on x-axis. y_scale : Literal["linear", "log"] | None, default=None Scale type for y-axis ("linear" or "log", auto-detected). y_scale_base : int, default=2 Base for log scale on y-axis. x_limits : tuple[float, float] | None, default=None Limits for x-axis (auto-set for DNA content). y_limits : tuple[float, float] | None, default=None Limits for y-axis. x_ticks : list[float] | None, default=None Custom x-axis tick positions. y_ticks : list[float] | None, default=None Custom y-axis tick positions. x_label : str | None, default=None X-axis label. y_label : str | None, default=None Y-axis label. axes : Axes | None, default=None Existing matplotlib Axes to plot on. Reference Lines & Thresholds ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ vline : float | None, default=None Vertical reference line position (auto for DNA). hline : float | None, default=None Horizontal reference line position (auto for EdU). line_style : str, default="--" Style for reference lines. line_color : str, default="black" Color for reference lines. threshold : float | None, default=None Y-value threshold for blue/red coloring. Styling & Colors ^^^^^^^^^^^^^^^^ show_title : bool, default=False Whether to show title. title : str | None, default=None Plot title. fig_size : tuple[float, float] | None, default=None Figure size in size_units. size_units : str, default="cm" Units for figure size ("cm" or "inches"). tight_layout : bool, default=False Whether to use tight layout. Save Options ^^^^^^^^^^^^ save : bool, default=False Whether to save the figure. path : Path | None, default=None Directory to save figure. file_format : str, default="pdf" Format for saved figure. dpi : int, default=300 Resolution for saved figures. Returns: ------- tuple[Figure, Axes | list[Axes]] (Figure, Axes or list of Axes) Examples: Basic cell cycle plot with auto-detection: >>> fig, ax = scatter_plot(df, "control") Multiple conditions with threshold coloring: >>> fig, axes = scatter_plot( ... df, ... ["control", "treatment"], ... y_feature="intensity_mean_p21_nucleus", ... threshold=5000 ... ) Custom features with log scales: >>> fig, ax = scatter_plot( ... df, ... "control", ... x_feature="area_cell", ... y_feature="intensity_mean_p21_nucleus", ... x_scale="log", ... y_scale="log" ... ) ## Classification and QC Classifier output and per-well quality control. classification_plot(df: pandas.core.frame.DataFrame, classes: list[str], conditions: list[str], condition_col: str = 'condition', class_col: str = 'Class', selector_col: str | None = 'cell_line', selector_val: str | None = None, show_triplicates: bool = False, fig_size: tuple[float, float] = (7, 7), size_units: str = 'cm', y_lim: tuple[int, int] = (0, 100), title: str | None = None, colors: list[str] = ['#526C94', '#D8C367', '#75B1CE', '#DC6B83', '#D4D3CF', '#00bfb2', '#CCDBA2', '#889466', '#C6B2D1', '#654875'], axes: Optional[matplotlib.axes._axes.Axes] = None, bar_width: float = 0.75, show_legend: bool = True, legend_bbox: tuple[float, float] = (0.98, 1.0), group_size: int = 1, repeat_offset: float = 0.18, within_group_spacing: float = 0.2, between_group_gap: float = 0.4, show_boxes: bool = True, show_significance: bool = True, stats_class: str | list[str] | None = None, paired: bool = True, show_ns: bool = True, min_effect: float | None = None, save: bool = False, save_stats: bool = False, path: Optional[pathlib.Path] = None, file_format: str = 'pdf', tight_layout: bool = True, dpi: int = 300) -> tuple[matplotlib.figure.Figure, matplotlib.axes._axes.Axes] Create a classification plot with flexible display options. The plot behavior changes based on parameters: - show_triplicates="stacked": Shows stacked bars with error bars - show_triplicates="triplicates": Shows individual repeat bars - group_size > 1: Groups conditions together (works with triplicates mode) Parameters ---------- Data Filtering ^^^^^^^^^^^^^^ df : pd.DataFrame DataFrame containing classification data classes : list[str] List of class names to plot conditions : list[str] List of condition names to plot condition_col : str, default="condition" Column name for experimental condition class_col : str, default="Class" Column name for class/category (dynamic based on model) selector_col : str | None, default="cell_line" Column name for selector (e.g., cell line) selector_val : str | None, default=None Value to filter selector_col by Display Options ^^^^^^^^^^^^^^^ show_triplicates : bool, default=False If False, shows stacked bars with error bars (mean ± SD). If True, shows individual replicate bars side-by-side. y_lim : tuple[int, int], default=(0, 100) Y-axis limits Styling & Colors ^^^^^^^^^^^^^^^^ fig_size : tuple[float, float], default=(7, 7) Figure size as (width, height) size_units : str, default="cm" Units for fig_size ("cm" or "inches") title : str | None, default=None Plot title colors : list[str], default=COLORS List of colors for plotting axes : Axes | None, default=None Existing axes to plot on Stacked Mode Settings ^^^^^^^^^^^^^^^^^^^^^ bar_width : float, default=0.75 Width of bars in stacked mode show_legend : bool, default=True Whether to show legend legend_bbox : tuple[float, float], default=(0.98, 1.0) Legend position as (x, y) Triplicates Mode Settings ^^^^^^^^^^^^^^^^^^^^^^^^^ group_size : int, default=1 Number of conditions to group (1 = no grouping) repeat_offset : float, default=0.18 Offset for repeat bars within_group_spacing : float, default=0.2 Spacing within groups between_group_gap : float, default=0.4 Gap between groups show_boxes : bool, default=True Whether to draw a box around each condition's triplicate bars (only applies when show_triplicates=True). Set False for a cleaner look when the bars do not sum to 100% (e.g. a single class selected). show_significance : bool, default=True Whether to compute significance (condition vs the first in the group, paired by plate). Exports a p-value and a medians CSV when save=True. stats_class : str | None, default=None Which class's comparison to annotate on the plot (default = the first class in ``classes``). Both CSV tables always cover every class. paired : bool, default=True Use a paired t-test (ttest_rel, matched by plate_id); set False for the unpaired ttest_ind. Save Options ^^^^^^^^^^^^ save : bool, default=False Whether to save the plot save_stats : bool, default=False Write {title}_stats.csv and {title}_medians.csv to ``path`` (independent of ``save``; works when plotting onto a provided/composed ``axes``). path : Path | None, default=None Path to save the plot file_format : str, default="pdf" File format for saving tight_layout : bool, default=True Whether to use tight layout dpi : int, default=300 Resolution for saving Returns: Tuple of (figure, axes) Examples: # Stacked plot with error bars (default) fig, ax = classification_plot( df, ["G1", "S", "G2M"], ["Control", "Treatment"] ) # Individual triplicates without grouping fig, ax = classification_plot( df, ["G1", "S", "G2M"], ["Control", "Treatment"], show_triplicates=True ) # Individual triplicates with grouping fig, ax = classification_plot( df, ["G1", "S", "G2M"], ["Control", "Treat1", "Treat2", "Treat3"], show_triplicates=True, group_size=2 # Groups conditions in pairs ) well_qc_plot(df: 'pd.DataFrame', *, title: 'str | None' = None, dna_norm_col: 'str | None' = None, fig_size: 'tuple[float, float]' = (12, 7), size_units: 'str' = 'cm', save: 'bool' = False, path: 'Path | None' = None, file_format: 'str' = 'png', dpi: 'int' = 300) -> 'Figure' Build a compact per-well QC figure (histogram + scatter + cell-cycle bar). Layout — 2×2 ``GridSpec`` matching the legacy per-well QC plot: - Top-left: DNA-content histogram (log₂ x-axis). - Bottom-left: DNA vs EdU scatter coloured by cell-cycle phase, with KDE overlay and threshold lines. - Right (spans both rows): stacked cell-cycle phase barplot. The caller is expected to pass a DataFrame that contains a single well's cells already filtered down (or trust the resolver / the underlying primitives to filter via the ``well`` column). The figure does not sample cells — the histogram and scatter use all rows passed in. Args: df: Single-cell DataFrame with cell-cycle columns (``cell_cycle``, ``intensity_mean_EdU_nucleus_norm``, and the normalised DNA-content column). title: Figure-level suptitle. If ``None``, no title is drawn. dna_norm_col: Normalised DNA-content column to plot on the x-axis. Auto-resolved via :func:`find_dna_norm_column` when ``None``. fig_size: Figure size in ``size_units`` (default: cm). size_units: ``"cm"`` (default) or ``"inches"``. save: Save the figure to ``path``. path: Directory to save the figure into when ``save=True``. file_format: Save format. dpi: Save resolution. Returns: The composed matplotlib Figure. ## Utilities save_fig(fig: matplotlib.figure.Figure, path: pathlib.Path, fig_id: str, tight_layout: bool = False, fig_extension: str = 'pdf', resolution: int = 300) -> None Save a matplotlib figure to a file. Parameters ---------- fig : Figure The figure to save. path : Path The path for saving the figure. fig_id : str The name of the saved figure. tight_layout : bool, optional Whether to use tight layout (default is True). fig_extension : str, optional The file extension for the saved figure (default is 'pdf'). resolution : int, optional The resolution of the saved figure in dpi (default is 300). Returns: ------- None Saves the figure in the specified format. ---------------------------------------------------------------------- This is the User Guide documentation for the package. ---------------------------------------------------------------------- ## Guide ### Overview **OmeroScreen Plots** is a comprehensive visualization and analysis package for high-content screening data from OMERO. It provides standardized, publication-ready plots for immunofluorescence microscopy data with built-in statistical analysis. **Recent Architecture Update**: The package has been refactored from a complex multi-class factory pattern to a simplified single-class architecture, providing better performance, maintainability, and error handling while maintaining full backward compatibility. ## Key Features * **Standardized Plots**: Consistent, publication-ready figures for screening data * **Multiple Plot Types**: Feature plots, cell cycle analysis, combined plots, and more * **Statistical Analysis**: Built-in statistical tests and data normalization * **Flexible Customization**: Extensive options for colors, grouping, and styling * **Integration**: Works seamlessly with OMERO and cellview databases ## Quick Start ```python import pandas as pd from omero_screen_plots.countplot_api import count_plot from omero_screen_plots.countplot_factory import PlotType # Load your data df = pd.read_csv("path/to/data.csv") # Create a count plot (simplified architecture) fig, ax = count_plot( df=df, norm_control="DMSO", conditions=["DMSO", "Treatment1", "Treatment2"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Cell Count Analysis", save=True, path="output/" ) ``` Full signatures and parameter documentation for every public function are in the [API reference](../reference/index.html). ## Requirements - Python 3.12, 3.13 or 3.14 - OMERO Screen installation (for full pipeline integration) - Access to screening data in CSV format or cellview database ## Install from Source Since OmeroScreen Plots is part of the omero-screen monorepo, the recommended installation method is through the main project: ```bash # Clone the repository git clone https://github.com/Helfrid/omero-screen.git cd omero-screen # Install using uv (recommended) uv sync --dev source .venv/bin/activate ``` ## Standalone Installation If you only need the plotting functionality: ```bash cd packages/omero-screen-plots uv pip install -e . ``` ## Dependencies OmeroScreen Plots requires the following main dependencies: - **pandas**: Data manipulation and analysis - **matplotlib**: Core plotting functionality - **seaborn**: Statistical visualizations - **numpy**: Numerical operations - **scipy**: Statistical tests - **scikit-posthocs**: Post-hoc statistical tests All dependencies are automatically installed with the package. ## Verify Installation ```python import omero_screen_plots print(omero_screen_plots.__version__) ``` ## Troubleshooting ### Import Errors If you encounter import errors, ensure that: 1. You're in the correct virtual environment 2. The package is installed in editable mode (`-e`) 3. Your Python path includes the package directory ### Missing Dependencies Run `uv sync` to ensure all dependencies are installed correctly. ## Next Steps - Check out the [Quick Start Guide](quickstart.qmd) for basic usage - Explore [Plot Types](plot_types.qmd) for available visualizations ### Quick Start ```{=html} ``` This guide will help you create your first plots with OmeroScreen Plots using example data. ## Download Example Data First, let's download the example dataset from Zenodo to test the different plot types: ```bash # Navigate to the examples data directory cd packages/omero-screen-plots/src/omero_screen_plots/examples/data # Download the example dataset from Zenodo wget https://zenodo.org/records/15728770/files/sample_plate_data.csv # Or using curl curl -L -o sample_plate_data.csv https://zenodo.org/records/15728770/files/sample_plate_data.csv ``` This dataset contains single-cell measurements from a high-content screening experiment with multiple conditions and features. ## Basic Workflow 1. **Load example data**: Use the downloaded CSV file 2. **Choose a plot type**: Based on your analysis needs 3. **Create and customize**: Generate publication-ready figures 4. **Save and export**: Multiple format options ## Data Format The example data includes these key columns: - **object_id**: Unique identifier for each cell - **condition**: Experimental condition (e.g., "DMSO", "Nutlin", "Etop", "Noc") - **plate_id**: Plate identifier - **well_name**: Well position (e.g., "C04", "D04") - **Feature columns**: Various measurements including: - `intensity_mean_dapi_nucleus`: DAPI intensity - `intensity_integrated_edu_nucleus`: EdU incorporation - `intensity_mean_p21_nucleus`: p21 expression - `area_nucleus`: Nuclear area - And many more... ## Plot Types We have built a variety of functions for standardized single-cell analysis. This includes plotting measurements of specific parameters such as mean intensity or cell area, as well as cell cycle and cell count plotting. These plot types include statistical analysis when at least three different datasets are present in the dataframe. Combined plots display cell cycle profiles in greater detail using scatterplots. ### 1. Count Plots Count plots are the simplest type of analysis of the OmeroScreen IF data. They simply display the differences in cell count and provide a statistical analysis, if more than 3 repeats are available. ```python import pandas as pd from omero_screen_plots.countplot_api import count_plot from omero_screen_plots.countplot_factory import PlotType # Load your data df = pd.read_csv("sample_plate_data.csv") # Generate absolute count plot fig, ax = count_plot( df=df, norm_control="control", # Still required for data processing conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col='cell_line', selector_val='MCF10A', plot_type=PlotType.ABSOLUTE, title="Absolute Cell Counts per Condition", save=True, path="_static" ) ``` ::: {.fig-card} ![Count Plot Example](../assets/qs_count_plot.svg) ::: ### 2. Feature Plots Feature plots display single cell measurements for a chosen parameter provided by the feature argument. Below is a standard example using an overlay of boxen and stripplots and also displaying the median of individual repeats in the data set with t-tests performed relative to the control (the first column by default) ```python from omero_screen_plots import feature_plot # Generate feature plot fig, ax = feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col='cell_line', selector_val='MCF10A', title="p21 Expression by Condition", fig_size=(5, 3), save=True, path="_static" # Save to docs _static directory ) ``` ::: {.fig-card} ![Feature Plot Example](../assets/qs_feature_plot.svg) ::: ### 3. Cell Cycle Plots Cellcycle plots require EdU staining in the dataset, and are calculated using an automated normalisation and thresholding procedure. There are several variations in the display options, below is a stacked barplot example. *Note: The cell cycle plot requires EdU staining data. If your dataset doesn't contain the required EdU columns, this plot may not display correctly.* ```python from omero_screen_plots import cellcycle_stacked # Generate cell cycle plot (requires EdU data) fig, ax = cellcycle_stacked( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col='cell_line', selector_val='MCF10A', y_err=True, title="Stacked Cell Cycle Plot", fig_size=(6, 3), size_units="cm", between_group_gap=0.4, save=True, path="_static" # Save to docs _static directory ) ``` ::: {.fig-card} ![Cell Cycle Plot Example](../assets/qs_cellcycle_plot.svg) ::: ## Running the Example Notebooks The package includes Jupyter notebooks demonstrating various analyses: ```bash # Navigate to the examples directory cd packages/omero-screen-plots/src/omero_screen_plots/examples/notebooks # Start Jupyter jupyter notebook # Open and run the example notebooks: # - featureplot.ipynb # - cellcycle.ipynb # - combplot.ipynb # - normalise.ipynb ``` ## Common Parameters Most plot classes share these parameters: - **data_path**: Path to your CSV file - **conditions**: List of conditions to plot - **condition_col**: Column name containing conditions - **plate_ids**: Optional list to filter specific plates - **output_path**: Directory for saving figures - **fig_format**: Output format ("pdf", "png", "svg") - **dpi**: Resolution for raster formats ## Statistical Analysis The example data demonstrates automatic statistical testing: ```python # Feature plot with statistics plot = FeaturePlot( data_path="sample_plate_data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["DMSO", "Nutlin", "Etop", "Noc"], condition_col="condition", test_group_pairs=[("DMSO", "Nutlin"), ("DMSO", "Etop"), ("DMSO", "Noc")] ) ``` ## Customization Examples ### Custom Colors ```python # Use custom colors for conditions plot = FeaturePlot( data_path="sample_plate_data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["DMSO", "Nutlin", "Etop", "Noc"], condition_col="condition", order_and_colors={ "DMSO": "#1f77b4", "Nutlin": "#ff7f0e", "Etop": "#2ca02c", "Noc": "#d62728" } ) ``` ### Grouped Conditions ```python # Group conditions visually plot = FeaturePlot( data_path="sample_plate_data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["DMSO", "Nutlin", "Etop", "Noc"], condition_col="condition", grouped=True, group_names=["Control", "DNA Damage"] ) ``` ## Tips for Using Example Data 1. **Explore the data**: Check what features are available in the CSV 2. **Try different features**: The example data has many measured parameters 3. **Experiment with conditions**: Try different subsets of the four conditions 4. **Test plot types**: Each plot type reveals different aspects of the data 5. **Check the notebooks**: Example notebooks show real-world usage patterns ## Next Steps - Explore [Plot Types](plot_types.qmd) for all available visualizations - Learn about [Customization](customization.qmd) options - Try your own data following the same format as the example dataset ### Plot Types OmeroScreen Plots provides several specialized plot types for high-content screening data analysis. Each plot type is designed for specific analytical needs. ## FeaturePlot **Purpose**: Compare any measured feature across conditions using box plots, violin plots, or boxen plots. **Use cases**: - Protein expression levels - Cell morphology parameters - Intensity measurements - Any quantitative feature ### Basic Usage ```python from omero_screen_plots.featureplot import FeaturePlot plot = FeaturePlot( data_path="sample_plate_data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["DMSO", "Nutlin"], condition_col="condition", plot_type="box" # Options: "box", "violin", "boxen" ) ``` ### Key Parameters - **y_feature**: The feature to plot on y-axis - **plot_type**: Visual representation style - **test_group_pairs**: Pairs for statistical comparisons - **grouped**: Enable visual grouping of conditions - **show_points**: Overlay individual data points ### Output - Box/violin plots with statistical annotations - Optional scatter overlay - Automatic or custom statistics ## ClassificationPlot **Purpose**: Visualize categorical classification results as stacked bars or individual triplicates. **Use cases**: - Cell morphology classification - Phenotype distribution analysis - Quality control assessment - Drug toxicity evaluation ### Basic Usage ```python from omero_screen_plots import classification_plot fig, ax = classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], class_col="classifier", # Dynamic classification column display_mode="stacked" # or "triplicates" ) ``` ### Key Features - **Dynamic class column**: Adapt to any categorical classification - **Two display modes**: Stacked bars with error bars or individual triplicates - **Flexible grouping**: Group conditions for easier comparison - **Custom colors**: Apply meaningful color schemes to categories ## CellCyclePlot **Purpose**: Analyze cell cycle distribution based on DNA content (DAPI) and S-phase marker (EdU). **Use cases**: - Cell cycle profiling - Drug effect on proliferation - p21-based cell cycle arrest analysis ### Basic Usage ```python from omero_screen_plots.cellcycleplot import CellCyclePlot cc_plot = CellCyclePlot( data_path="sample_plate_data.csv", conditions=["DMSO", "Nutlin"], condition_col="condition", dapi_col="intensity_integrated_dapi_nucleus", edu_col="intensity_mean_edu_nucleus", p21_col="intensity_mean_p21_nucleus" # Optional ) ``` ### Key Parameters - **dapi_col**: Column with integrated DAPI intensity - **edu_col**: Column with EdU incorporation data - **p21_col**: Optional p21 expression for arrest analysis - **plot_type**: "standard", "grouped", or "stacked" - **normalise**: Normalize to percentage or absolute counts ### Output - Cell cycle phase distribution (G1, S, G2) - Optional p21+ arrested cells - Statistical comparisons between conditions ## CombPlot **Purpose**: Combined visualizations showing relationships between features with marginal distributions. **Use cases**: - Feature correlation analysis - Scatter plots with histograms - Distribution comparisons - Multi-dimensional data exploration ### Plot Types Available 1. **Scatter Plot** ```python plot = CombPlot( data_path="sample_plate_data.csv", plot_type="scatter", x_feature="intensity_integrated_dapi_nucleus", y_feature="intensity_mean_edu_nucleus" ) ``` 2. **Histogram** ```python plot = CombPlot( data_path="sample_plate_data.csv", plot_type="histogram", x_feature="area_nucleus" ) ``` 3. **Hexbin Plot** ```python plot = CombPlot( data_path="sample_plate_data.csv", plot_type="hexbin", x_feature="area_nucleus", y_feature="intensity_mean_dapi_nucleus" ) ``` ### Key Parameters - **x_feature**, **y_feature**: Features for x and y axes - **plot_type**: "scatter", "histogram", "hexbin", "kde" - **show_regression**: Add regression line to scatter - **marginal_type**: Type of marginal plots ## CountPlot **Purpose**: Analyze and visualize cell counts per well or condition. **Use cases**: - Toxicity assessment - Proliferation analysis - Quality control - Well-to-well variation ### Basic Usage ```python from omero_screen_plots.countplot import CountPlot count_plot = CountPlot( data_path="sample_plate_data.csv", conditions=["DMSO", "Nutlin", "Etop", "Noc"], condition_col="condition" ) ``` ### Key Parameters - **normalise_to**: Normalize counts to specific condition - **show_plate_layout**: Display as plate heatmap - **aggregate_by**: Group by well, condition, or plate ### Output - Bar plots of cell counts - Statistical comparisons - Optional plate layout visualization ## Specialized Analysis Functions ### Normalise **Purpose**: Data normalization utilities for immunofluorescence data. ```python from omero_screen_plots.normalise import NormalisePlot norm_plot = NormalisePlot( data_path="sample_plate_data.csv", feature="intensity_mean_p21_nucleus", control_condition="DMSO" ) ``` Features: - Z-score normalization - Percent of control - Robust scaling - Plate-wise normalization ### Stats Module **Purpose**: Statistical analysis utilities used across all plot types. ```python from omero_screen_plots.stats import perform_statistical_tests # Automatic statistical testing results = perform_statistical_tests( data, groups=["DMSO", "Nutlin"], test_type="auto" # Automatically selects appropriate test ) ``` ## Choosing the Right Plot Type | Analysis Goal | Recommended Plot Type | |--------------|---------------------| | Compare single feature across conditions | FeaturePlot | | Analyze cell cycle distribution | CellCyclePlot | | Explore feature relationships | CombPlot (scatter) | | Assess cell viability/counts | CountPlot | | Examine distributions | CombPlot (histogram) | | Normalize data | NormalisePlot | ## Common Workflow 1. **Start with CountPlot** to check data quality and cell numbers 2. **Use FeaturePlot** to explore individual features 3. **Apply CellCyclePlot** for proliferation analysis 4. **Explore with CombPlot** for feature relationships 5. **Normalize data** when comparing across plates ## Tips - Always check cell counts first to identify problematic wells - Use violin plots for large datasets to see distribution shapes - Enable `show_points` in FeaturePlot for small sample sizes - Use grouped layouts when comparing related conditions - Save plots in vector format (PDF/SVG) for publications ### Customization & Styling OmeroScreen Plots uses a custom matplotlib style (`hhlab_style01.mplstyle`) that provides consistent, publication-ready formatting for all plots. This page documents the default styling and shows how to customize it. ## Default Color Palette The package uses a carefully curated 11-color palette designed for scientific visualization: | Color Name | Hex Code | RGB | Preview | |------------|----------|-----|---------| | Blue | `#526C94` | (82, 108, 148) | ████ | | Yellow | `#D8C367` | (216, 195, 103) | ████ | | Light Blue | `#75B1CE` | (117, 177, 206) | ████ | | Pink | `#DC6B83` | (220, 107, 131) | ████ | | Grey | `#D4D3CF` | (212, 211, 207) | ████ | | Turquoise | `#00BFB2` | (0, 191, 178) | ████ | | Light Green | `#CCDBA2` | (204, 219, 162) | ████ | | Olive | `#889466` | (136, 148, 102) | ████ | | Lavender | `#C6B2D1` | (198, 178, 209) | ████ | | Purple | `#654875` | (101, 72, 117) | ████ | | Dark Grey | `#4A4A4A` | (74, 74, 74) | ████ | ### Using Colors in Code Colors are available through the `COLOR` enum: ```python from omero_screen_plots.colors import COLOR # Access individual colors blue_color = COLOR.BLUE.value # "#526C94" yellow_color = COLOR.YELLOW.value # "#D8C367" # Use in custom plotting import matplotlib.pyplot as plt plt.plot(x, y, color=COLOR.BLUE.value) ``` ## Typography & Layout ### Font Settings - **Font Family**: Arial (sans-serif) - **Default Size**: 6pt - **Label Size**: 6pt (axes labels) - **Tick Label Size**: 6pt - **Legend Size**: 6pt - **Title Size**: 3pt (positioned left, regular weight) ### Figure Dimensions - **Default Size**: 2.4" × 1.3" (publication-ready) - **DPI**: 150 (display), 300 (saved files) - **Format**: Tight layout with 0.2" padding ### Axes Styling - **Spines**: Left and bottom only (top and right hidden) - **Line Width**: 0.5pt - **Color**: Black text and axes - **Ticks**: No tick marks (cleaner appearance) - **Grid**: Disabled by default ### Legends - **Background**: White with full opacity - **Frame**: Visible border - **Spacing**: Compact (0.25 units) - **Scatter Points**: 3 points in legend ## Customizing Colors ### Method 1: Using order_and_colors Parameter Most plot functions accept an `order_and_colors` dictionary: ```python from omero_screen_plots.featureplot import feature_plot_simple # Custom color scheme custom_colors = { "Control": "#1f77b4", # Blue "Treatment_A": "#ff7f0e", # Orange "Treatment_B": "#2ca02c", # Green "Treatment_C": "#d62728" # Red } feature_plot_simple( data_path="data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["Control", "Treatment_A", "Treatment_B", "Treatment_C"], condition_col="condition", order_and_colors=custom_colors, output_path="output/" ) ``` ### Method 2: Using Default Colors with Custom Order ```python from omero_screen_plots.colors import COLOR # Use default palette but specify order ordered_colors = { "DMSO": COLOR.BLUE.value, "Nutlin": COLOR.YELLOW.value, "Etoptoside": COLOR.LIGHT_BLUE.value, "Nocodazole": COLOR.PINK.value } ``` ### Method 3: Grouped Color Schemes For grouped analyses, colors are automatically assigned within groups: ```python feature_plot_simple( data_path="data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["WT_Control", "WT_Drug", "KO_Control", "KO_Drug"], condition_col="condition", grouped=True, group_names=["Wild Type", "Knockout"], output_path="output/" ) # Automatically uses alternating colors within each group ``` ## Style Customization ### Temporary Style Override ```python import matplotlib.pyplot as plt # Temporarily override specific parameters with plt.rc_context({'font.size': 8, 'axes.labelsize': 8}): feature_plot_simple( data_path="data.csv", y_feature="intensity_mean_p21_nucleus", conditions=["Control", "Treatment"], condition_col="condition", output_path="output/" ) ``` ### Creating Custom Style File Create your own `.mplstyle` file based on `hhlab_style01.mplstyle`: ```python import matplotlib.pyplot as plt # Load custom style plt.style.use("path/to/your/custom_style.mplstyle") # Then use plotting functions normally feature_plot_simple(...) ``` ### Modifying Existing Plots For fine-tuning individual plots: ```python from omero_screen_plots.featureplot import feature_plot import pandas as pd # Create base plot df = pd.read_csv("data.csv") fig, ax = feature_plot( df=df, y_feature="intensity_mean_p21_nucleus", conditions=["Control", "Treatment"], condition_col="condition" ) # Customize further ax.set_title("Custom Title", fontsize=10) ax.grid(True, alpha=0.3) plt.tight_layout() plt.savefig("custom_plot.pdf") ``` ## Best Practices ### Color Selection - **Accessibility**: Default palette is colorblind-friendly - **Contrast**: High contrast against white backgrounds - **Consistency**: Use same colors for same conditions across figures - **Limit**: Maximum 10 conditions per plot for clarity ### Typography - **Size**: Keep text readable at publication scale - **Hierarchy**: Distinguish between labels, titles, and annotations - **Consistency**: Use same font sizes across related figures ### Layout - **Spacing**: Ensure adequate white space around elements - **Alignment**: Left-align titles for consistent appearance - **Proportions**: Maintain aspect ratios appropriate for data type ### File Output - **Format**: PDF for publications, PNG for presentations - **Resolution**: 300 DPI minimum for print quality - **Size**: Standard figure dimensions for journal requirements ## Common Customizations ### Journal-Specific Requirements ```python # Nature/Science style (larger fonts) with plt.rc_context({ 'font.size': 8, 'axes.labelsize': 8, 'xtick.labelsize': 7, 'ytick.labelsize': 7, 'legend.fontsize': 7 }): your_plot_function() # Cell/Molecular Biology style (smaller, compact) with plt.rc_context({ 'font.size': 6, 'figure.figsize': (2.0, 1.5) }): your_plot_function() ``` ### High-Contrast Mode ```python # Black and white for grayscale printing bw_colors = { "Control": "#000000", # Black "Treatment_1": "#666666", # Dark grey "Treatment_2": "#CCCCCC" # Light grey } ``` ### Presentation Mode ```python # Larger sizes for presentations with plt.rc_context({ 'font.size': 12, 'axes.labelsize': 14, 'figure.figsize': (6, 4), 'figure.dpi': 100 }): your_plot_function() ``` The default styling is optimized for scientific publications but can be easily adapted for different contexts while maintaining the professional appearance and readability that makes OmeroScreen Plots effective for data communication. ## Plot gallery ### Classification plots ```{=html} ``` The classification plot visualizes categorical classification results across experimental conditions with flexible display modes for stacked percentages or individual biological replicates. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Stacked Classification Create a standard stacked bar plot showing mean percentages with error bars: ```python from omero_screen_plots import classification_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="stacked", title="Cell Morphology Classification", save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Stacked Classification](../assets/Cell_Morphology_Classification_-_Stacked.svg) ::: ### Individual Triplicates Display Show individual biological replicates to assess experimental consistency: ```python fig, ax = classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="triplicates", title="Individual Replicates" ) ``` ::: {.fig-card} ![Individual Triplicates Display](../assets/Cell_Morphology_Classification_-_Triplicates.svg) ::: ### Grouped Conditions Group related conditions for easier comparison: ```python fig, ax = classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2", "treatment3"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="triplicates", group_size=2, title="Grouped Conditions" ) ``` ::: {.fig-card} ![Grouped Conditions](../assets/classification_grouped.svg) ::: ### Custom Colors Apply custom color schemes to match your classification categories: ```python from omero_screen_plots.colors import COLOR custom_colors = [COLOR.GREY.value, COLOR.LIGHT_GREEN.value, COLOR.OLIVE.value] fig, ax = classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="stacked", colors=custom_colors, title="Custom Color Scheme" ) ``` ::: {.fig-card} ![Custom Colors](../assets/classification_colors.svg) ::: ### Multi-Panel Comparison Create publication-ready figures comparing different display modes: ```python import matplotlib.pyplot as plt fig, axes = plt.subplots(1, 3, figsize=(15, 5)) # Stacked mode classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="stacked", show_legend=False, axes=axes[0] ) axes[0].set_title("Stacked Mode", fontweight='bold') # Individual triplicates classification_plot( df=df, classes=["normal", "micronuclei", "collapsed"], conditions=["control", "treatment1", "treatment2"], condition_col="condition", class_col="classifier", selector_col="cell_line", selector_val="MCF10A", display_mode="triplicates", group_size=1, axes=axes[1] ) axes[1].set_title("Individual Triplicates", fontweight='bold') plt.tight_layout() ``` ::: {.fig-card} ![Multi-Panel Comparison](../assets/classification_comparison.svg) ::: ### Feature plots ```{=html} ``` The featureplot module provides flexible visualization options for comparing quantitative features across experimental conditions. Feature plots support both box plots and violin plots, with optional scatter point overlays, statistical significance testing, and flexible grouping layouts. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Box Plot Create a standard box plot with scatter points and statistical significance marks: ```python from omero_screen_plots import feature_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="feature plot basic", fig_size=(5, 5), save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Box Plot](../assets/feature_plot_basic.svg) ::: ### Grouped Layout Group conditions for better visual organization and within-group statistical comparisons: ```python fig, ax = feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="feature plot grouped", group_size=2, within_group_spacing=0.2, between_group_gap=0.5, fig_size=(6, 4) ) ``` ::: {.fig-card} ![Grouped Layout](../assets/feature_plot_grouped.svg) ::: ### Violin Plots Use violin plots to show the full distribution of your data: ```python fig, ax = feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="feature plot violin", violin=True, ymax=20000, fig_size=(5, 5) ) ``` ::: {.fig-card} ![Violin Plots](../assets/feature_plot_violin.svg) ::: ### Clean Violin Plots Remove scatter points for cleaner visualization with custom y-axis limits: ```python fig, ax = feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="feature plot no scatter", violin=True, show_scatter=False, ymax=(2000, 12000), group_size=2, fig_size=(5, 5) ) ``` ::: {.fig-card} ![Clean Violin Plots](../assets/feature_plot_no_scatter.svg) ::: ### Combined Subplot Analysis Create multi-panel figures comparing different features: ```python import matplotlib.pyplot as plt from omero_screen_plots.utils import save_fig fig, axes = plt.subplots(2, 1, figsize=(2, 4)) fig.suptitle("feature plot comparison", fontsize=8, weight="bold") # First subplot - p21 intensity feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", axes=axes[0], group_size=2, x_label=False, ) axes[0].set_title("mean nuc. p21 intensity", fontsize=7) # Second subplot - cell area feature_plot( df=df, feature="area_cell", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", violin=True, show_scatter=False, ymax=10000, axes=axes[1], group_size=2, ) axes[1].set_title("area cell", fontsize=7) save_fig(fig, "output/", "feature_comparison", fig_extension="svg") ``` ::: {.fig-card} ![Combined Subplot Analysis](../assets/feature_plot_comparison.svg) ::: ### Normalised feature plots ```{=html} ``` The feature_norm_plot module provides visualization for normalized feature data with threshold-based analysis. These plots normalize data by mode (peak = 1.0) and display the proportion of cells above/below a customizable threshold as stacked bars. They support triplicate display, multiple color schemes, and normalization QC plots. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Normalized Plot Create a basic normalized feature plot with the default green color scheme: ```python from omero_screen_plots import feature_norm_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = feature_norm_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", color_scheme="green", title="feature norm plot basic", show_error_bars=True, fig_size=(5, 4), save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Normalized Plot](../assets/feature_norm_plot_basic.svg) ::: ### Triplicates with Blue Color Scheme Show individual triplicate data with boxes using the blue color scheme: ```python fig, ax = feature_norm_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", color_scheme="blue", title="feature norm plot triplicates", show_triplicates=True, show_boxes=True, threshold=1.5, fig_size=(5, 4) ) ``` ::: {.fig-card} ![Triplicates with Blue Color Scheme](../assets/feature_norm_plot_triplicates.svg) ::: ### Grouped Layout with Purple Scheme Use grouped layout for better visual organization with the purple color scheme: ```python fig, ax = feature_norm_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", color_scheme="purple", title="feature norm plot grouped", show_triplicates=True, show_boxes=True, threshold=1.5, group_size=2, within_group_spacing=0.2, between_group_gap=0.4, fig_size=(5, 4) ) ``` ::: {.fig-card} ![Grouped Layout with Purple Scheme](../assets/feature_norm_plot_grouped.svg) ::: ### Custom Threshold Analysis Adjust the threshold for different sensitivity in detecting positive cells: ```python fig, ax = feature_norm_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", color_scheme="green", title="feature norm plot threshold", threshold=2.0, # Higher threshold (2x mode instead of 1.5x) show_triplicates=True, show_boxes=True, fig_size=(5, 4) ) ``` ::: {.fig-card} ![Custom Threshold Analysis](../assets/feature_norm_plot_threshold.svg) ::: ### Combined Analysis Comparison Create multi-panel figures comparing different analysis approaches: ```python import matplotlib.pyplot as plt from omero_screen_plots import feature_plot from omero_screen_plots.utils import save_fig fig, axes = plt.subplots(3, 1, figsize=(2, 6)) fig.suptitle("feature norm plot comparison", fontsize=8, weight="bold") # Standard feature plot feature_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", x_label=False, group_size=2, axes=axes[0], ) axes[0].set_title("p21 feature plot", fontsize=7) # Normalized feature plot feature_norm_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", x_label=False, axes=axes[1], group_size=2, show_triplicates=True, show_boxes=True, threshold=1.5, ) axes[1].set_title("p21 feature norm plot", fontsize=7) # Violin plot for comparison feature_plot( df=df, feature="area_cell", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", x_label=True, violin=True, show_scatter=False, ymax=10000, axes=axes[2], group_size=2, ) axes[2].set_title("area cell violin", fontsize=7) save_fig(fig, "output/", "feature_norm_comparison", fig_extension="svg") ``` ::: {.fig-card} ![Combined Analysis Comparison](../assets/feature_norm_plot_comparison.svg) ::: ### Configuration Options The feature_norm_plot function supports extensive customization: **Normalization & Thresholding**: - **Mode normalization**: Data is normalized so the peak (mode) equals 1.0 - **Threshold analysis**: Customizable threshold (default 1.5x mode) for positive/negative classification - **Plate normalization**: Option to normalize within each plate separately - **QC plots**: Optional normalization quality control plots showing before/after distributions **Color Schemes**: - **Green** (default): Olive for positive cells, light green for negative cells - **Blue**: Blue for positive cells, light blue for negative cells - **Purple**: Purple for positive cells, lavender for negative cells **Display Options**: - **Summary bars**: Show aggregated proportions across replicates with error bars - **Triplicate display**: Show individual replicate bars with optional box outlines - **Grouping**: Organize conditions into groups with custom spacing - **Threshold legend**: Automatic legend showing threshold value and color mapping **Layout & Styling**: - **Figure size**: Control figure dimensions in cm or inches - **Spacing**: Customize within-group and between-group spacing - **Labels**: Control axis labels, titles, and legend display - **Export**: Save in multiple formats (SVG, PDF, PNG) with custom DPI ### Cell cycle plots ```{=html} ``` The cell cycle plot provides comprehensive visualization of cell cycle phase distributions across experimental conditions in a multi-panel grid layout with statistical analysis and flexible phase terminology. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Default Cell Cycle Analysis Create a standard 2x3 grid showing all cell cycle phases with statistical analysis: ```python from omero_screen_plots import cellcycle_plot import pandas as pd df = pd.read_csv("data.csv") fig, axes = cellcycle_plot( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Cell Cycle Analysis", save=True, file_format="svg" ) ``` ::: {.fig-card} ![Default Cell Cycle Analysis](../assets/cellcycle_plot_default.svg) ::: ### DNA Content Visualization Focus on DNA content measurements with 2x2 grid layout: ```python fig, axes = cellcycle_plot( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", cc_phases=False, # Use DNA content terminology (<2N, 2N, S, 4N, >4N) title="DNA Content Analysis" ) ``` ::: {.fig-card} ![DNA Content Visualization](../assets/cellcycle_plot_DNA_content.svg) ::: ### Custom Phase Selection Analyze specific cell cycle phases with custom terminology: ```python fig, axes = cellcycle_plot( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", cc_phases=True, show_subG1=False, # Exclude SubG1 title="Major Cell Cycle Phases" ) ``` ::: {.fig-card} ![Custom Phase Selection](../assets/cellcycle_plot_no_SubG1.svg) ::: ### Clean Layout with Custom Colors Create publication-ready figures with custom styling: ```python from omero_screen_plots.colors import COLOR custom_colors = [COLOR.LIGHT_BLUE.value, COLOR.BLUE.value, COLOR.GREY.value, COLOR.DARK_GREY.value] fig, axes = cellcycle_plot( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", show_subG1=True, colors=custom_colors, show_repeat_points=False, title="Custom Styled Cell Cycle" ) ``` ::: {.fig-card} ![Clean Layout with Custom Colors](../assets/cellcycle_plot_custom_colors.svg) ::: ### Cell cycle stacked plots ```{=html} ``` The cell cycle stacked plot provides unified visualization of cell cycle phase distributions using stacked bar charts with options for summary statistics or individual biological replicates. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Stacked Distribution Create a standard stacked bar plot showing cell cycle phase proportions with error bars: ```python from omero_screen_plots import cellcycle_stacked import pandas as pd df = pd.read_csv("data.csv") fig, ax = cellcycle_stacked( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Cell Cycle Phase Distribution", save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Stacked Distribution](../assets/cellcycle_stacked_default.svg) ::: ### Individual Triplicates Display Show individual biological replicates to assess experimental consistency: ```python fig, ax = cellcycle_stacked( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", selector_val="MCF10A", show_triplicates=True, group_size=1, title="Cell Cycle - Individual Replicates" ) ``` ::: {.fig-card} ![Individual Triplicates Display](../assets/cellcycle_stacked_triplicates.svg) ::: ### DNA Content Focus Emphasize DNA content measurements with custom phase selection: ```python fig, ax = cellcycle_stacked( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", selector_val="MCF10A", phase_order=['SubG1', 'G1', 'S', 'G2/M'], title="DNA Content Distribution" ) ``` ::: {.fig-card} ![DNA Content Focus](../assets/cellcycle_stacked_DNA_content.svg) ::: ### Custom Phase Colors Apply custom color schemes for publication figures: ```python from omero_screen_plots.colors import COLOR phase_colors = [COLOR.LIGHT_BLUE.value, COLOR.BLUE.value, COLOR.GREY.value, COLOR.DARK_GREY.value] fig, ax = cellcycle_stacked( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", colors=phase_colors, show_legend=True, title="Custom Cell Cycle Colors" ) ``` ::: {.fig-card} ![Custom Phase Colors](../assets/cellcycle_stacked_custom_colors.svg) ::: ### Grouped Condition Analysis Group related conditions for treatment comparison: ```python fig, ax = cellcycle_stacked( df=df, conditions=['control', 'low_dose', 'med_dose', 'high_dose'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", show_triplicates=True, group_size=2, within_group_spacing=0.2, between_group_gap=0.5, title="Dose Response Analysis" ) ``` ::: {.fig-card} ![Grouped Condition Analysis](../assets/cellcycle_stacked_advanced_grouping.svg) ::: ### Histogram plots ```{=html} ``` The histogramplot module provides comprehensive distribution visualization with support for both traditional histograms and kernel density estimation (KDE) overlays. It offers flexible options for single or multiple conditions, logarithmic scaling, and extensive customization. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Single Condition Histogram Create a standard histogram for a single condition: ```python from omero_screen_plots import histogram_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = histogram_plot( df=df, feature="intensity_mean_p21_nucleus", conditions="control", # Single condition as string condition_col="condition", selector_col="cell_line", selector_val="MCF10A", bins=100, # Default value title="Basic Histogram", show_title=True, fig_size=(6, 4), save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Single Condition Histogram](../assets/histogram_plot_basic.svg) ::: ### Multiple Conditions with Subplots Compare distributions across multiple conditions using automatic subplot layout: ```python fig, axes = histogram_plot( df=df, feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", bins=50, title="Multiple Conditions", show_title=True, fig_size=(16, 4) # Automatically sized: 4cm per condition ) ``` ::: {.fig-card} ![Multiple Conditions with Subplots](../assets/histogram_intensity_mean_p21_nucleus_multi.svg) ::: ### DNA Content with Log Scale Essential for cell cycle analysis using logarithmic scaling: ```python fig, axes = histogram_plot( df=df, feature="integrated_int_DAPI_norm", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", bins=100, log_scale=True, log_base=2, # Base 2 for DNA content (2N, 4N) x_limits=(1, 16), # Typical DNA content range title="DNA Content Distribution", show_title=True ) ``` ::: {.fig-card} ![DNA Content with Log Scale](../assets/histogram_integrated_int_DAPI_norm_multi.svg) ::: ### KDE Overlay Mode Compare multiple conditions on a single plot using smooth density curves: ```python fig, ax = histogram_plot( df=df, feature="integrated_int_DAPI_norm", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", kde_overlay=True, # Enables KDE-only mode kde_smoothing=0.8, # Smoothing factor log_scale=True, log_base=2, x_limits=(1, 16), title="KDE Overlay Comparison", show_title=True, fig_size=(8, 5) ) ``` ::: {.fig-card} ![KDE Overlay Mode](../assets/histogram_plot_KDE_overlay.svg) ::: ### Normalized Histograms Show probability density instead of counts for sample-size-independent comparison: ```python fig, axes = histogram_plot( df=df, feature="area_cell", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", bins=50, normalize=True, # Show density instead of counts title="Cell Area Distribution (Normalized)", show_title=True ) ``` ::: {.fig-card} ![Normalized Histograms](../assets/histogram_area_cell_multi.svg) ::: ## Parameters The histogram_plot function supports extensive customization: **Plot Modes**: - **Standard histograms**: Multiple conditions create separate subplots - **KDE overlay**: All conditions overlaid on single plot (when `kde_overlay=True`) **Scaling Options**: - **Linear or logarithmic**: Use `log_scale=True` with customizable `log_base` - **Normalization**: Show density (`normalize=True`) or counts (default) **Binning Control**: - **Fixed bins**: Integer value (default: 100) - **Automatic strategies**: 'auto', 'sturges', 'fd', etc. - **Unified binning**: Automatic calculation for consistent multi-condition comparison **KDE Parameters**: - **Smoothing**: Control with `kde_smoothing` (0.5-2.0, default: 0.8) - **Advanced options**: Pass additional parameters via `kde_params` dict - **Resolution**: Higher `gridsize` for smoother curves **Visual Customization**: - **Colors**: Default blue for histograms, varied palette for KDE overlay - **Figure size**: Dynamic defaults based on condition count - **Titles**: Optional with customizable positioning - **Axis limits**: Custom x-axis range with `x_limits` ### Key Parameters Essential parameters for different use cases: **For Cell Cycle Analysis**: ```python histogram_plot(df, "integrated_int_DAPI_norm", conditions, log_scale=True, log_base=2, x_limits=(1, 16)) ``` **For Biomarker Comparison**: ```python histogram_plot(df, "intensity_mean_p21_nucleus", conditions, kde_overlay=True, kde_smoothing=0.7) ``` **For Morphological Features**: ```python histogram_plot(df, "area_cell", conditions, normalize=True, bins=50) ``` ### Notes on Normalization When `normalize=True`, the histogram displays **probability density**: - Y-axis shows density (probability per unit of x-axis) - Total area under histogram equals 1.0 - Formula: `density = count / (total_count * bin_width)` - Compatible with KDE overlay (which always shows density) This allows direct comparison of distributions with different sample sizes, essential for conditions with varying cell counts due to toxicity or proliferation effects. ### Advanced KDE Customization Fine-tune KDE generation with the `kde_params` dictionary: ```python histogram_plot( df, feature, conditions, kde_overlay=True, kde_smoothing=0.6, kde_params={ 'gridsize': 500, # Higher resolution 'bw_method': 'scott', # Bandwidth selection 'cut': 3, # Extend beyond data range 'alpha': 0.9, # Transparency 'linewidth': 3 # Line thickness } ) ``` **Bandwidth Methods**: - `'scott'`: Good general purpose (default) - `'silverman'`: Alternative automatic method - Float value: Manual bandwidth specification **Smoothing Guidelines**: - Lower values (0.5-0.7): Smoother, less detailed curves - Default (0.8): Balanced smoothness and detail - Higher values (1.5-2.0): More detailed, potentially noisier ### Scatter plots ```{=html} ``` The scatter plot provides intelligent visualization for exploring relationships between two quantitative features with automatic context detection for cell cycle analysis and extensive customization options. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Feature Correlation Create a standard scatter plot to explore relationships between two features: ```python from omero_screen_plots import scatter_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = scatter_plot( df=df, x_feature="area_cell", y_feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Cell Area vs p21 Intensity", save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Feature Correlation](../assets/scatter_plot_basic.svg) ::: ### Multiple Condition Comparison Compare feature relationships across different experimental conditions: ```python fig, ax = scatter_plot( df=df, x_feature="area_cell", y_feature="intensity_mean_p21_nucleus", conditions=['control', 'cond01', 'cond02', 'cond03'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Multi-Condition Feature Analysis" ) ``` ::: {.fig-card} ![Multiple Condition Comparison](../assets/scatter_plot_multiple.svg) ::: ### Cell Cycle Context Detection Automatic cell cycle visualization with DNA content and EdU incorporation: ```python fig, ax = scatter_plot( df=df, x_feature="integrated_int_DAPI_norm", # Auto-detected as DNA content y_feature="intensity_mean_EdU_nucleus_norm", # Auto-detected as EdU conditions=['control', 'cond01', 'cond02'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="Cell Cycle Analysis" ) ``` ::: {.fig-card} ![Cell Cycle Context Detection](../assets/scatter_plot_phases.svg) ::: ### Threshold Analysis Apply threshold-based classification with custom coloring: ```python fig, ax = scatter_plot( df=df, x_feature="area_cell", y_feature="intensity_mean_p21_nucleus", conditions=['control', 'treatment'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", threshold=5000, # Threshold value for y-axis title="Threshold-Based Classification" ) ``` ::: {.fig-card} ![Threshold Analysis](../assets/scatter_plot_threshold.svg) ::: ### KDE Density Overlay Add kernel density estimation for distribution visualization: ```python fig, ax = scatter_plot( df=df, x_feature="integrated_int_DAPI_norm", y_feature="intensity_mean_EdU_nucleus_norm", conditions=['control'], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", kde_overlay=True, title="Density Distribution Analysis" ) ``` ::: {.fig-card} ![KDE Density Overlay](../assets/scatter_plot_kde.svg) ::: ### Combined plots ```{=html} ``` The combined plot module provides two specialized multi-panel visualizations that integrate histograms, scatter plots, and statistical summaries for comprehensive data analysis. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Overview The combplot module offers two distinct visualization approaches: **combplot_feature**: Creates a vertically stacked grid layout for feature analysis. The number of rows grows with the number of features supplied (`2 + n_features` rows): - Top row: DNA content histograms - Second row: DNA vs EdU scatter plots with cell cycle phases - One additional row per feature: DNA vs feature scatter plots with optional threshold coloring Passing a single `feature` string reproduces the classic three-row layout (histogram → EdU → feature). Passing a list of features stacks one scatter row per feature underneath the EdU row, sharing the DNA-content x-axis. **combplot_cellcycle**: Creates a 2-row grid with integrated barplot - Top row: DNA content histograms - Bottom row: DNA vs EdU scatter plots - Right column: Stacked cell cycle phase barplot ## Examples ### Feature Analysis with Threshold Analyze p21 intensity across conditions with threshold-based coloring: ```python from omero_screen_plots import combplot_feature import pandas as pd df = pd.read_csv("data.csv") fig, axes = combplot_feature( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], feature="intensity_mean_p21_nucleus", threshold=5000, selector_col="cell_line", selector_val="MCF10A", title="p21 Intensity Analysis", cell_number=3000, save=True, file_format="svg" ) ``` ::: {.fig-card} ![Feature Analysis with Threshold](../assets/combplot_feature_p21.svg) ::: ### Cell Area Analysis Examine cell size distributions with DNA content context: ```python fig, axes = combplot_feature( df=df, conditions=['control', 'cond01', 'cond02'], feature="area_cell", threshold=2000, selector_col="cell_line", selector_val="MCF10A", title="Cell Area Analysis", cell_number=2000, fig_size=(8, 7) ) ``` ::: {.fig-card} ![Cell Area Analysis](../assets/combplot_feature_area.svg) ::: ### Compact Feature Comparison Compare control vs treatment with nuclear intensity: ```python fig, axes = combplot_feature( df=df, conditions=['control', 'cond01'], feature="intensity_mean_nucleus", threshold=7500, selector_val="MCF10A", title="Nuclear Intensity Comparison", cell_number=3000, fig_size=(6, 7) ) ``` ::: {.fig-card} ![Compact Feature Comparison](../assets/combplot_feature_nucleus.svg) ::: ### Stacked Multi-Feature Analysis Pass a **list** of features to stack one scatter row per feature beneath the EdU row. The grid height grows automatically, and each feature can take its own threshold (use `None` to disable colouring for a given row): ```python fig, axes = combplot_feature( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], feature=[ "intensity_mean_p21_nucleus", "area_cell", ], threshold=[5000, None], # one threshold per feature; None disables it selector_col="cell_line", selector_val="MCF10A", title="Stacked feature analysis", cell_number=2000, save=True, file_format="svg", ) ``` A scalar `threshold` (or `threshold=None`) is broadcast to every feature row, so `threshold=None` plots all feature rows in a single colour. When `fig_size` is left as `None` the figure height scales with the number of rows (matching the classic `(10, 7)` default for a single feature). ::: {.fig-card} ![Stacked Multi-Feature Analysis](../assets/combplot_feature_stacked.svg) ::: ### Cell Cycle Distribution Analysis Comprehensive cell cycle analysis with integrated barplot: ```python from omero_screen_plots import combplot_cellcycle fig, axes = combplot_cellcycle( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], selector_val="MCF10A", title="Cell Cycle Distribution", cell_number=3000, cc_phases=True, show_error_bars=True, save=True ) ``` ::: {.fig-card} ![Cell Cycle Distribution Analysis](../assets/combplot_cellcycle_default.svg) ::: ### DNA Content Terminology Use DNA content labels without error bars: ```python fig, axes = combplot_cellcycle( df=df, conditions=['control', 'cond01', 'cond02', 'cond03'], selector_val="MCF10A", title="DNA Content Analysis", cc_phases=False, # Use <2N, 2N, S, 4N, >4N show_error_bars=False, fig_size=(12, 7) ) ``` ::: {.fig-card} ![DNA Content Terminology](../assets/combplot_cellcycle_dna.svg) ::: ### Compact Cell Cycle View Reduced conditions for space-efficient visualization: ```python fig, axes = combplot_cellcycle( df=df, conditions=['control', 'cond01', 'cond02'], selector_val="MCF10A", title="Compact Cell Cycle", cell_number=2000, fig_size=(10, 7) ) ``` ::: {.fig-card} ![Compact Cell Cycle View](../assets/combplot_cellcycle_compact.svg) ::: ## Advanced Usage ### Data Sampling Control The `cell_number` parameter controls sampling for scatter plots only: ```python # Histograms use full data, scatter plots sample 5000 cells fig, axes = combplot_feature( df=df, conditions=conditions, feature="intensity_mean_p21_nucleus", threshold=5000, cell_number=5000, # Only affects scatter plots selector_val="MCF10A" ) ``` ### Multiple Feature Comparison Stack several features in a single figure by passing aligned lists of features and thresholds. Each feature becomes its own scatter row underneath the shared EdU row: ```python fig, axes = combplot_feature( df=df, conditions=['control', 'treatment'], feature=["intensity_mean_p21_nucleus", "area_nucleus"], threshold=[5000, 500], # aligned with `feature`; lengths must match selector_val="MCF10A", title="Multi-feature comparison", ) ``` If you would rather produce one figure per feature (for example to save them as separate files), loop over the features and call `combplot_feature` with a single feature each time: ```python features = [ ("intensity_mean_p21_nucleus", 5000), ("area_nucleus", 500), ] for feature, threshold in features: fig, axes = combplot_feature( df=df, conditions=['control', 'treatment'], feature=feature, threshold=threshold, selector_val="MCF10A", title=f"{feature} Analysis", fig_size=(6, 7), ) ``` ### Custom Error Bar Control Toggle error bars on cell cycle barplot: ```python # Without error bars for cleaner visualization fig, axes = combplot_cellcycle( df=df, conditions=conditions, selector_val="MCF10A", show_error_bars=False, cc_phases=True ) ``` ## See Also - [`histogram_plot`](histogramplot.qmd) : Individual histogram plots - [`scatter_plot`](scatterplot.qmd) : Individual scatter plots - [`cellcycle_stacked`](cellcyclestacked.qmd) : Standalone cell cycle barplots - [`feature_plot`](featureplot.qmd) : Feature comparison plots ### Count plots ```{=html} ``` The count plot module provides visualization for cell count analysis across experimental conditions. Count plots support both normalized and absolute count display, statistical significance testing, and flexible grouping layouts for comparative analysis. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples ### Basic Normalized Count Plot Create a standard normalized count plot showing relative counts compared to control: ```python from omero_screen_plots import count_plot import pandas as pd df = pd.read_csv("data.csv") fig, ax = count_plot( df=df, norm_control="control", conditions=["control", "cond01", "cond02", "cond03"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", title="count plot basic", fig_size=(6, 4), save=True, file_format="svg" ) ``` ::: {.fig-card} ![Basic Normalized Count Plot](../assets/count_plot_basic.svg) ::: ### Absolute Count Plot Display raw cell counts without normalization to see actual numbers: ```python from omero_screen_plots import count_plot, PlotType fig, ax = count_plot( df=df, norm_control="control", conditions=["control", "cond01", "cond02", "cond03"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", plot_type=PlotType.ABSOLUTE, title="count plot absolute", fig_size=(6, 4), save=True, file_format="svg" ) ``` ::: {.fig-card} ![Absolute Count Plot](../assets/count_plot_absolute.svg) ::: ### Grouped Layout Group conditions for better visual organization and within-group statistical comparisons: ```python fig, ax = count_plot( df=df, norm_control="control", conditions=["control", "cond01", "cond02", "cond03"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", group_size=3, within_group_spacing=0.2, between_group_gap=0.8, title="count plot grouped", fig_size=(6, 4) ) ``` ::: {.fig-card} ![Grouped Layout](../assets/count_plot_grouped.svg) ::: ### Combined Subplot Analysis Create multi-panel figures comparing normalized and absolute counts: ```python import matplotlib.pyplot as plt from omero_screen_plots.utils import save_fig fig, axes = plt.subplots(2, 1, figsize=(2, 4)) fig.suptitle("count plot with axes", fontsize=8, weight="bold") # Normalized counts count_plot( df=df, norm_control="control", conditions=["control", "cond01", "cond02", "cond03"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", axes=axes[0], plot_type=PlotType.NORMALISED, x_label=False ) axes[0].set_title("MCF10A Norm Counts", fontsize=8, weight="bold") # Absolute counts count_plot( df=df, norm_control="control", conditions=["control", "cond01", "cond02", "cond03"], condition_col="condition", selector_col="cell_line", selector_val="MCF10A", plot_type=PlotType.ABSOLUTE, axes=axes[1] ) axes[1].set_title("MCF10A Abs. Counts", fontsize=8, weight="bold") save_fig(fig, "output/", "count_plot_with_axes", fig_extension="svg") ``` ::: {.fig-card} ![Combined Subplot Analysis](../assets/count_plot_with_axes.svg) ::: ### Normalisation The normalise module provides data normalization utilities for immunofluorescence data. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples Normalize by mode: ```python from omero_screen_plots.normalise import normalize_by_mode import pandas as pd df = pd.read_csv("sample_plate_data.csv") normalized_df = normalize_by_mode( df=df, feature="intensity_mean_p21_nucleus", condition_col="condition", control_condition="DMSO" ) ``` Normalize and plot results: ```python from omero_screen_plots.normalise import normalize_and_plot normalize_and_plot( data_path="sample_plate_data.csv", feature="intensity_mean_p21_nucleus", condition_col="condition", control_condition="DMSO", output_path="output/" ) ``` Set threshold categories: ```python from omero_screen_plots.normalise import set_threshold_categories df_with_categories = set_threshold_categories( df=df, feature="intensity_mean_p21_nucleus", low_threshold=500, high_threshold=2000 ) ``` ### Utility functions This module provides utility functions used across the plotting package. See the [API reference](../reference/index.html) for full signatures and parameter documentation. ## Examples Scaling immunofluorescence data: ```python from omero_screen_plots.utils import scale_data import pandas as pd # Scale intensity data to 16-bit range df = pd.read_csv("data.csv") df_scaled = scale_data( df, scale_col="intensity_mean_p21_nucleus", scale_min=1.0, # 1st percentile scale_max=99.0 # 99th percentile ) ``` Saving figures with consistent formatting: ```python from omero_screen_plots.utils import save_fig import matplotlib.pyplot as plt fig, ax = plt.subplots() # ... create your plot ... save_fig( fig=fig, path=Path("output"), fig_id="my_analysis", fig_extension="pdf", resolution=300 ) ``` Filtering data by condition: ```python from omero_screen_plots.utils import selector_val_filter # Filter for specific experimental condition filtered_df = selector_val_filter( df=data, selector_col="cell_line", selector_val="HeLa", condition_col="treatment", conditions=["DMSO", "Nutlin"] ) ```