omixvizpy

A Python package for omics data visualization, particularly focused on Principal Component Analysis (PCA) plotting.

Features

• PCA Visualization: Create comprehensive PCA plots with multiple grouping options
• Flexible Plotting: Support for scatter plots and pair plots of principal components
• Customizable: Easy-to-use functions with extensive customization options
• Publication Ready: High-quality plots suitable for scientific publications

Installation

From PyPI (recommended)

pip install omixvizpy

From Source

git clone https://github.com/Leslie-Lu/omixvizpy.git
cd omixvizpy
pip install -e .

Quick Start

import omixvizpy

# Plot PCA results with covariates
omixvizpy.plot_pca(
    eigenvec_file="path/to/your/eigenvec.txt",
    covar_file="path/to/your/covariates.csv",
    cov1="Country_of_birth",                    # First covariate
    cov2="Ethnic_background",                   # Second covariate (optional)
    legend_title_cov1="Country of Birth",       # Legend title for first covariate
    legend_title_cov2="Ethnicity",             # Legend title for second covariate
    cov1_levels=["England", "Wales", "Scotland", "Others"],  # Labels for first covariate
    cov2_levels=["White", "Asian", "Black", "Others"],      # Labels for second covariate
    fig_path="output/directory",                # Output directory
    fig1_name="variance_explained",             # Variance plot
    fig2_name="pc1_vs_pc2",                    # PC1 vs PC2 scatter plot
    fig3_name="pca_by_country",                # Pairplot by first covariate
    fig4_name="pca_by_ethnicity",              # Pairplot by second covariate
    fig1_size=(11, 9),                           # Size of variance explained plot
    fig2_size=(12, 12),                         # Size of PC1 vs PC2
    save_figs=True                             # Save figures instead of displaying
)

Function Reference

plot_pca

Create comprehensive PCA visualization plots.

Parameters:

• eigenvec_file (str): Path to the eigenvec file containing PCA results
• covar_file (str): Path to the CSV file containing covariate information
• cov1 (str): Name of the first covariate column (default: 'Country_of_birth')
• cov2 (Optional[str]): Name of the second covariate column
• legend_title_cov1 (str): Title for the first covariate's legend
• legend_title_cov2 (Optional[str]): Title for the second covariate's legend
• cov1_levels (List[str]): Labels for the first covariate's values
• cov2_levels (Optional[List[str]]): Labels for the second covariate's values
• fig_path (Optional[str]): Directory path where figures will be saved
• fig1_name (str): Name for the variance explained plot (default: 'variance_explained')
• fig2_name (str): Name for the PC1 vs PC2 scatter plot
• fig3_name (str): Name for the pairplot colored by first covariate
• fig4_name (str): Name for the pairplot colored by second covariate
• fig1_size (Tuple[int, int]): Size of the variance explained plot (default: (11, 9))
• fig2_size (Tuple[int, int]): Size of the PC1 vs PC2 scatter plot (default: (12, 12))
• save_figs (bool): Whether to save the figures (default: False)

Returns:

• Displays interactive plots and optionally saves them as PNG files

Input Data Format

Eigenvec File

The eigenvec file should be a tab-separated file with the following columns:

• eid: Sample identifier
• PC1, PC2, PC3, etc.: Principal component values

Covariate File

The covariate file should be a comma-separated (CSV) file with the following structure:

• eid: Sample identifier (matching eigenvec file)
• Additional columns for covariates (e.g., Country_of_birth, Ethnic_background)
  • Values in these columns should correspond to the levels specified in cov1_levels and cov2_levels
  • The order of levels in cov*_levels determines the order in the plot legend

Requirements

• Python >=3.8
• pandas >=1.3.0
• matplotlib >=3.3.0
• seaborn >=0.11.0
• numpy >=1.20.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Citation

If you use omixvizpy in your research, please cite:

@software{omixvizpy,
  title={omixvizpy: A Python package for omics data visualization},
  author={Zhen Lu},
  year={2025},
  url={https://github.com/Leslie-Lu/omixvizpy}
}