cosg 1.0.4

COSG v1.0.4 Release Notes

on Python PyPI

Highlights

This release includes performance improvements, a new visualization function plotMarkerStream, and enhanced input validation for a more robust user experience.

🐛 Bug Fixes

cosg.py

• Fixed use_raw parameter bug: Previously, the use_raw parameter was non-functional because a second assignment always overwrote the first. Now use_raw=True correctly uses adata.raw.X when available.

• Fixed DataFrame fragmentation warning: Resolved the performance issue caused by repeated pd.concat() in loop. Results are now pre-allocated in dictionaries and the DataFrame is built once after the loop, eliminating the "DataFrame is highly fragmented" warning for datasets with many clusters.

• Blocked unsupported parameter combination: Using batch_key with a subset of groups now raises a clear NotImplementedError instead of producing incorrect results silently.

_plotting.py

• Fixed AttributeError in palette filtering: Added hasattr() check before accessing .cat.categories to handle non-categorical columns gracefully.

✨ New Features

New Parameter: expressed_min_num_cells_in_target_group

Added a new parameter to prevent overly permissive expression thresholds in small clusters when remove_lowly_expressed=True.

cosg.cosg(
    adata,
    groupby='cell_type',
    remove_lowly_expressed=True,
    expressed_pct=0.1,
    expressed_min_num_cells_in_target_group=3  # NEW: minimum absolute threshold
)

The actual threshold is now: max(n_cells * expressed_pct, expressed_min_num_cells_in_target_group)

For example, a cluster with 10 cells and expressed_pct=0.1 will use a threshold of max(1, 3) = 3 cells instead of just 1 cell.

New Visualization: plotMarkerStream

Added a new streamgraph visualization function for displaying marker gene specificity scores across cell types.

cosg.plotMarkerStream(
    adata,
    groupby='cell_type',
    n_top_genes=3,
    plot_type='stacked',       # Options: 'proportional', 'stacked', 'mirror', 'ridge'
    orientation='vertical',    # Options: 'vertical', 'horizontal'
    show_brackets=True,
    smooth=False
)

Features include:

• Multiple plot types (proportional, stacked, mirror, ridge)
• Vertical or horizontal orientation
• Optional smoothing with multiple methods (gaussian, spline, savgol)
• Customizable cell type brackets and gene labels
• Flexible color schemes and legend positioning

🛡️ Input Validation

Added comprehensive input validation for all parameters in cosg():

• groupby column existence check
• groups parameter validation (must be a sequence, not a single value)
• Invalid group detection with helpful error messages
• n_genes_user >= 1
• expressed_pct in range [0, 1]
• expressed_min_num_cells_in_target_group >= 1
• layer existence validation
• batch_key column existence check
• Delimiter collision detection in indexByGene()

🔧 Code Quality Improvements

• Replaced sys.exit(0) with proper ValueError exceptions
• Added type hints to plotMarkerDendrogram() and plotMarkerDotplot()
• Stored additional parameters in adata.uns[key_added]['params'] for reproducibility

📦 Installation

pip install cosg --upgrade

Or install from source:

pip install git+https://github.com/genecell/COSG.git

Thank you to all users!