Metadata-Version: 2.4
Name: psmil
Version: 0.0.15
Summary: psmil package
Home-page: https://github.com/Jamesyu420/PSMIL/tree/main
Author: Xuetong Li
Author-email: xtong_li@126.com
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

# Partially Subsampled Multiple Instance Learning

This is a NumPy–based toolkit for multiple-instance learning (MIL) with Gaussian mixutre models. This is also a Python package accompanying the following paper:

> Yu, B., Li, X., Zhou, J., and Wang, H. Detecting Breast Carcinoma Metastasis on Whole-Slide Images by Partially Subsampled Multiple Instance Learning, The Annals of Applied Statistics, To appear.

PSMIL implements:

1. Instance-supervised MLE (InsMLE) when instance labels are available,
2. Bag-only MLE (BagMLE) when only bag labels are available, and
3. Subsampling MLE (SubMLE) that leverages subsampling to improve statistical efficiency.

For a tutorial and the CAMELYON16 analysis, see the GitHub repo:  
[https://github.com/Jamesyu420/PSMIL](https://github.com/Jamesyu420/PSMIL).

## Installation

```bash
pip install PSMIL
```

## Quick Start

All functions operate on NumPy arrays with shapes:
- X: (N, M, p) float — features for N bags, M instances per bag, and p features
- Y: (N,) int in {0,1} — bag labels
- A: (N, M) int in {0,1} — instance labels

### InsMLE

Instance-based MLE when A is observed.

```python
ins = InsMLE(X, A, Y)
```

Returns a dict with keys:
- 'mu1' (p,) — mean of positives,
- 'mu0' (p,) — mean of negatives,
- 'alpha' float — bag prevalence np.mean(Y),
- 'pi' float — positive-instance rate on positive bags,
- 'Sigma' (p,p) — pooled covariance.

### BagMLE

BagMLE when only Y is used.

```python
bag = BagMLE(
    X, Y,
    mu1_init, mu0_init, Sigma_init, pi_init,
    prt=False, iter=100, tol=1e-10
)
```

Parameters
- mu1_init, mu0_init (p,): initial means
- Sigma_init (p,p): initial covariance (SPD)
- pi_init float in (0,1): initial positive-instance rate on positive bags
- prt bool: print per-iter diagnostics
- iter int: max iterations
- tol float: stopping threshold on parameter change (squared L2 distance sum)

Returns a dict with:
- 'mu1', 'mu0', 'Sigma', 'pi', 'alpha' — estimates
- 'pi_im' (N,M) - Posterior probability
- 'iter' int - iterations

### SubMLE

SubMLE to subsample those instances that are likely to be positive.

```python
alpha_n = sub_alphan(X, Y, est=bag, gamma_target=0.05)

sub = SubMLE(
    X, Y, A,
    mu1_init, mu0_init, Sigma_init, pi_init,
    est, alpha_n=alpha_n,
    prt=False, iter=100, tol=1e-10, seed=0
)
```

Here gamma_target is the target subsampling rate.

## Contact

If you have any questions, please feel free to contact [Baichen Yu](mailto:baichen.yu@stu.pku.edu.cn) and [Prof. Xuetong Li](mailto:xtong_li@xjtu.edu.cn).
