cnellington/Contextualized

An SKLearn-style toolbox for estimating and analyzing models, distributions, and functions with context-specific parameters.

An SKLearn-style toolbox for estimating and analyzing models, distributions, and functions with context-specific parameters.

Context-specific parameters:

• Find hidden heterogeneity in data -- are all samples the same?
• Identify context-specific predictors -- are there different reasons for outcomes?
• Enable domain adaptation -- can learned models extrapolate to new contexts?

Most models can be contextualized. For example, linear regression is

$$Y = X\beta + \epsilon$$

Contextualized linear regression is

$$Y = X\beta(C) + \epsilon$$

where the coefficients $\beta$ are now a function of context $C$, allowing the model to adapt to context-specific changes. Contextualized implements this for many types of statistical models, including linear regression, logistic regression, Bayesian networks, correlation networks, and Markov networks.

For more details, see the Contextualized Machine Learning whitepaper.

Quick Start

Installation

pip install contextualized-ml

Take a look at the easy demo for a quickstart with sklearn-style wrappers.

Build a Contextualized Model

from contextualized.easy import ContextualizedRegressor
model = ContextualizedRegressor()
model.fit(C, X, Y)

This builds a contextualized linear regression model by fitting a deep-learning model to generate context-specific coefficients $\beta(C)$.

Predict Context-Specific Parameters

model.predict_params(C)

See the docs for more examples.

Important links

• Documentation
• Pypi package index

Citing

If you use this software, please cite the software publication:

@article{Ellington2024,
  doi = {10.21105/joss.06469},
  url = {https://doi.org/10.21105/joss.06469},
  year = {2024},
  publisher = {The Open Journal},
  volume = {9},
  number = {97},
  pages = {6469},
  author = {Caleb N. Ellington and Benjamin J. Lengerich and Wesley Lo and Aaron Alvarez and Andrea Rubbi and Manolis Kellis and Eric P. Xing},
  title = {Contextualized: Heterogeneous Modeling Toolbox},
  journal = {Journal of Open Source Software}
}

Contributing

Add your own contributions by sending a PR or request an improvement by creating an issue. See CONTRIBUTING.md for more info.

Thanks to all our contributors

Contextualized ML was originally implemented by Caleb Ellington (CMU) and Ben Lengerich (MIT).

Beyond code contributions, many people have helped. Check out ACKNOWLEDGEMENTS.md!

Related Publications and Pre-prints

• Contextualized Machine Learning
• Contextualized: Heterogeneous Modeling Toolbox
• Networks
  • Contextualized Networks Reveal Heterogeneous Transcriptomic Regulation in Tumors at Sample-Specific Resolution
  • NOTMAD: Estimating Bayesian Networks with Sample-Specific Structures and Parameters
• Applications
  • Contextualized Policy Recovery: Modeling and Interpreting Medical Decisions with Adaptive Imitation Learning
  • Automated Interpretable Discovery of Heterogeneous Treatment Effectiveness: A COVID-19 Case Study
  • Discriminative Subtyping of Lung Cancers from Histopathology Images via Contextual Deep Learning
  • Personalized Survival Prediction with Contextual Explanation Networks
  • Contextual Explanation Networks
• Background reading:
  • Varying-Coefficient Models

Videos

• Cold Spring Harbor Laboratory: Contextualized Graphical Models Reveal Sample-Specific Transcriptional Networks for 7000 Tumors
• Sample-Specific Models for Interpretable Analysis with Applications to Disease Subtyping

Contact Us

Please get in touch with any questions, feature requests, or applications by using the GitHub discussions page.