mlmarker 0.1.2
MLMarker is a Python package for tissue-specific protein marker prediction


# MLMarker

**MLMarker** is a machine learning framework designed for tissue-specific proteomics classification. It leverages state-of-the-art machine learning models to predict tissue origins based on protein expression data, with built-in explainability features for interpreting model predictions using SHAP values.

## Features

- **Model Training & Prediction**: Trains machine learning models to predict tissue types based on protein expression data.
- **SHAP-Based Explainability**: Explains model predictions with SHAP values and provides visualizations like force plots and radar charts.
- **Data Validation & Preprocessing**: Validates input data and ensures it's properly formatted for model input.
- **Scalable**: Designed to handle large datasets with multiple features (proteins) and tissues.

## Installation

To install **MLMarker**, use the following command:

```bash
pip install mlmarker
```

This will install the latest version of the package along with its dependencies.

If you want to install additional development requirements (e.g., for testing or contributing), clone the repository and install the dependencies from the `requirements.txt` file:

```bash
git clone https://github.com/your-repository/mlmarker.git
cd mlmarker
pip install -r requirements.txt
```

## Usage

### 1. **Loading the Model and Making Predictions**

To load a pre-trained model and make predictions for a given sample:

```python
from mlmarker.model import MLMarker
import pandas as pd

# Sample data (replace with your actual sample data)
sample_data = pd.DataFrame({...})  # Your sample data as a DataFrame

# Initialize the MLMarker class with the sample data
marker = MLMarker(sample_df=sample_data, binary=True)

# Make predictions for the top 5 tissues
predictions = marker.predict_top_tissues(n_preds=5)
print(predictions)
```

### 2. **Explaining Predictions with SHAP**

To explain the model's predictions using SHAP values:

```python
# Visualize the SHAP force plot for the top predicted tissue
marker.explainability.visualize_shap_force_plot(tissue_name='Heart')
```

### 3. **Visualizing Radar Chart**

To visualize the contributions of proteins across top predicted tissues:

```python
marker.explainability.visualize_radar_chart()
```

## Modules

### `model.py`

Contains the `MLMarker` class responsible for:
- Loading models and features from specified paths.
- Predicting tissue types for a given sample.
- Calculating and visualizing SHAP values for model explainability.

### `explainability.py`

Handles the computation and visualization of SHAP values:
- Calculates SHAP values for a given sample.
- Visualizes SHAP force plots for understanding how features contribute to predictions.
- Adjusts SHAP values for absent features and visualizes radar charts for model insights.

### `constants.py`

Contains constants used across the package:
- File paths for models and features.
- Configuration values related to model training and prediction.

### `utils.py`

Provides helper functions for data validation and preprocessing:
- Ensures the input sample data matches the expected format for prediction.
- Scales and cleans data to be compatible with the model.

## Contributing

We welcome contributions to the **MLMarker** project! If you have improvements, bug fixes, or additional features, feel free to submit a pull request.

### How to Contribute

1. Fork the repository.
2. Clone your fork locally.
3. Create a new branch for your changes.
4. Make your changes and commit them.
5. Push the changes to your fork and submit a pull request.

## Acknowledgments

- **SHAP**: For model explainability.
- **Scikit-learn**: For machine learning model support.
- **Plotly**: For visualizing results via radar charts.