add paper.md

misc/paper.bib

@@ -0,0 +1,167 @@
+@Manual{ceterisParibus,
+    title = {ceterisParibus: Ceteris Paribus Plots (What-If Plots) for a Single Observation},
+    author = {Biecek, Przemysław},
+    year = {2018},
+    note = {R package version 0.2.1},
+    url = {https://CRAN.R-project.org/package=ceterisParibus}
+  }
+
+@article{2018arXiv180608915B,
+   author = {{Biecek}, Przemysław},
+    title = "{DALEX: explainers for complex predictive models}",
+  journal = {ArXiv e-prints},
+archivePrefix = "arXiv",
+   eprint = {1806.08915},
+ primaryClass = "stat.ML",
+ keywords = {Statistics - Machine Learning, Computer Science - Artificial Intelligence, Computer Science - Machine Learning, Statistics - Applications},
+     year = 2018,
+    month = jun,
+   adsurl = {http://adsabs.harvard.edu/abs/2018arXiv180608915B},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+@book{collett2015modelling,
+  title={Modelling Survival Data in Medical Research, Third Edition},
+  author={Collett, David},
+  isbn={9781498731690},
+  series={Chapman \& Hall/CRC Texts in Statistical Science},
+  url={https://books.google.pl/books?id=Okf7CAAAQBAJ},
+  year={2015},
+  publisher={CRC Press}
+}
+
+@article{lu2003modeling,
+  title={Modeling customer lifetime value using survival analysis—an application in the telecommunications industry},
+  author={Lu, Junxiang and Park, O},
+  journal={Data Mining Techniques},
+  pages={120--128},
+  year={2003},
+  publisher={Citeseer}
+}
+
+@Article{randomForestSRC,
+  title = {Random survival forests},
+  author = {Ishwaran, Hemant and Kogalur, Udaya B. and Blackstone, Eugene H. and Lauer, Michael S.},
+  journal = {Ann. Appl. Statist.},
+  year = {2008},
+  volume = {2},
+  number = {3},
+  pages = {841--860},
+  url = {http://arXiv.org/abs/0811.1645v1},
+  pdf = {http://arxiv.org/pdf/0811.1645},
+}
+
+@article{ELEUTERI2003855,
+  title = {A novel neural network-based survival analysis model},
+  journal = {Neural Networks},
+  volume = {16},
+  number = {5},
+  pages = {855 - 864},
+  year = {2003}, 
+  note = {Advances in Neural Networks Research: IJCNN '03},
+  issn = {0893-6080},
+  doi = {https://doi.org/10.1016/S0893-6080(03)00098-4},
+  url = {http://www.sciencedirect.com/science/article/pii/S0893608003000984},
+  author = {Eleuteri, Antonio and Tagliaferri, Roberto and Milano, Leopoldo and De Placido, Sabino and De Laurentiis, Michele},
+  keywords = {Survival analysis, Conditioning probability estimation, Neural networks, Bayesian learning, MCMC methods}
+}
+
+@article{RJ-2017-016,
+  author = {Greenwell, Brandon M.},
+  title = {{pdp: An R Package for Constructing Partial Dependence Plots}},
+  year = {2017},
+  journal = {{The R Journal}},
+  url = {https://journal.r-project.org/archive/2017/RJ-2017-016/index.html},
+  pages = {421--436},
+  volume = {9},
+  number = {1}
+}
+
+@Article{BSScore,
+    title = {Evaluating Random Forests for Survival Analysis Using
+      Prediction Error Curves},
+    author = {Mogensen, Ulla B. and Ishwaran, Hemant and Gerds, Thomas A.
+      },
+    journal = {Journal of Statistical Software},
+    year = {2012},
+    volume = {50},
+    number = {11},
+    pages = {1--23},
+    url = {http://www.jstatsoft.org/v50/i11/},
+  }
+  
+@ARTICLE{2018arXiv180401955S,
+   author = {Staniak, Mateusz and Biecek, Przemysław},
+    title = "{Explanations of model predictions with live and breakDown packages}",
+  journal = {ArXiv e-prints},
+archivePrefix = "arXiv",
+   eprint = {1804.01955},
+ primaryClass = "stat.ML",
+ keywords = {Statistics - Machine Learning, Computer Science - Learning, Statistics - Applications},
+     year = 2018,
+    month = apr,
+   adsurl = {http://adsabs.harvard.edu/abs/2018arXiv180401955S},
+  adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+@article{Molnar2018,
+  doi = {10.21105/joss.00786},
+  url = {https://doi.org/10.21105/joss.00786},
+  year  = {2018},
+  month = {jun},
+  publisher = {The Open Journal},
+  volume = {3},
+  number = {26},
+  pages = {786},
+  author = {Molnar, Christoph},
+  title = {iml: An R package for Interpretable Machine Learning},
+  journal = {Journal of Open Source Software}
+}
+
+@misc{pramit_choudhary_2018_1198885,
+  author       = {Choudhary, Pramit and
+                  Kramer, Aaron and
+                  datascience.com team, contributors},
+  title        = {{Skater: Model Interpretation Library}},
+  month        = mar,
+  year         = 2018,
+  doi          = {10.5281/zenodo.1198885},
+  url          = {https://doi.org/10.5281/zenodo.1198885}
+}
+
+
+@InProceedings{pmlr-v70-dempsey17a,
+  title = 	 {i{S}urvive: An Interpretable, Event-time Prediction Model for m{H}ealth},
+  author = 	 {Dempsey, Walter H. and Moreno, Alexander and Scott, Christy K. and Dennis, Michael L. and Gustafson, David H. and Murphy, Susan A. and Rehg, James M.},
+  booktitle = 	 {Proceedings of the 34th International Conference on Machine Learning},
+  pages = 	 {970--979},
+  year = 	 {2017},
+  editor = 	 {Doina Precup and Yee Whye Teh},
+  volume = 	 {70},
+  series = 	 {Proceedings of Machine Learning Research},
+  address = 	 {International Convention Centre, Sydney, Australia},
+  month = 	 {06--11 Aug},
+  publisher = 	 {PMLR},
+  pdf = 	 {http://proceedings.mlr.press/v70/dempsey17a/dempsey17a.pdf},
+  url = 	 {http://proceedings.mlr.press/v70/dempsey17a.html}
+}
+
+
+
+@article{doi:10.4155/fmc.11.23,
+  author = {Johansson, Ulf and Sönströd, Cecilia and Norinder, Ulf and Boström, Henrik},
+  title = {Trade-off between accuracy and interpretability for predictive in silico modeling},
+  journal = {Future Medicinal Chemistry},
+  volume = {3},
+  number = {6},
+  pages = {647-663},
+  year = {2011},
+  doi = {10.4155/fmc.11.23},
+  note ={PMID: 21554073},
+  URL = {https://doi.org/10.4155/fmc.11.23},
+  eprint = {https://doi.org/10.4155/fmc.11.23}
+}
+
+

misc/paper.md

@@ -0,0 +1,89 @@
+---
+title: 'survxai: an R package for model agnostic explanations of survival models'
+authors:
+- affiliation: 1, 2
+  name: Aleksandra Grudziaz
+  orcid: 0000-0002-5963-6260
+- affiliation: 2
+  name: Alicja Gosiewska
+  orcid: 0000-0001-6563-5742
+- affiliation: 1, 2
+  name: Przemyslaw Biecek
+  orcid: 0000-0001-8423-1823
+date: "3 August 2018"
+output: pdf_document
+bibliography: paper.bib
+tags:
+- survival analysis
+- explainable artificial intelligence
+- predictive modeling
+- interpretable machine learning
+affiliations:
+- index: 1
+  name: Faculty of Mathematics and Information Science, Warsaw University of Technology
+- index: 2
+  name: Faculty of Mathematics, Informatics, and Mechanics, University of Warsaw
+---
+
+# Introduction
+
+<!-- A summary describing the high-level functionality and purpose of the software for a diverse, non-specialist audience-->
+
+Predictive models are widely used in the supervised machine learning. Three most common classes of such models are: *regression models*, here the target variable is continuous numeric, *classification models* here the target variable is binary or categorical and *survival models* here the target is some censored variable. Common examples of censored variables are time to death (but some cases lived for x years and are still alive), cessation of service by the customer or failure of a machine component.
+
+Modern predictive models are often complex in structure. Think about neural networks [@ELEUTERI2003855] or random forest [@randomForestSRC]. Such models may be described by thousands of coefficients. Often such flexibility leads to high performance, but makes these models opaque, hard to understand. It is acceptable in cases in which only the model accuracy is important, but in cases that involve human decisions it may not be enough. To trust model predictions one needs to see which features are important and how model predictions would change if some feature was changed. 
+
+The area of model interpretability or explanability gains quickly attention of machine learning experts. Understanding of complex models leads not only to higher trust in model predictions but also to better models. Better means that they are more robust and maintain high accuracy on validation data. See examples in `DALEX`  [@2018arXiv180608915B] or `iml` [@Molnar2018] R packages. 
+
+Existing tools for model agnostic explanations are focused on regression models and classification problems as in both cases model predictions may be summarised by a single number. Survival models require different approach as predictions are in a form of survival curves. Demand for such explainers leads to some model specific solutions, like `iSurvive` introduced by [@pmlr-v70-dempsey17a] for continuous time hidden Markov model. Yet, we are lacking of model agnostic tools for survival models.
+
+The `survxai` fills out this gap. This R package is designed to deliver local and global explanations for survival models in a model agnostic fashion. In the package documentation we demonstrate examples for Cox models and for Survival Random Forest models.
+The `survxai` package consists new implementations and visualisations of explainers designed for survival models. Functions are well documented, package is supplemented with unit tests and illustrations. 
+Regardless of the complexity of the model, methods implemented in the `survxai` package maintain a certain level of interpretability, important in medical applications [@collett2015modelling], churn analysis [@lu2003modeling] and others.
+
+
+<!-- A clear statement of need that illustrates the purpose of the software-->
+# Explanations of survival models
+
+The R package `survxai` is a tool for creating explanations of survival models. It's model agnostic, thus is working with both complex and simple survival models. It also allows to compare two or more models. 
+
+Currently, four classes of model explainers are implemented. Two for local explanations (for a single prediction), and two for global explanations (for a whole model). 
+
+Package `survxai` is available on CRAN and a development version of the package can be found on [https://github.com/MI2DataLab/survxai](https://github.com/MI2DataLab/survxai).
+
+**Local methods** are the explanations of one observation.
+
+- **Ceteris Paribus** plot presents model responses around a single point in the feature space [@ceterisParibus]. See an example in Figure 1. Each panel is related to a single variable. Single panel shows how a model prediction (survival curve) would change if only a single variable will be changed. It if usefull for *what-if* reasoning. Each curve in a panle is realted a different value of the selected variable.
+Ceteris Paribus plot illustrates how may the survival curve change along with the changing values of the variable. 
+
+![Ceteris Paribus plot for Cox Proportional Hazards model with three variables. Black survival curve corresponds to a observation of interest. Middle panel shows that prediction for sex=0 are worse than for sex=1.](img/ceteris_paribus.png)
+
+- **break down** plot presents variable contributions in final predictions  [@2018arXiv180401955S]. See an example in Figure 2. The Break Down of prediction  for survival model helps to understand which factors drive survival probability for a single observation.
+
+![Break Down plot for Cox Proportional Hazards model. Variables bili and stage have highest impact on final prediction.](img/breakdown.png)
+
+**Global methods** are model performance and explanations of the conditional model structure.
+
+- **variable response** plot is designed to better understand the relation between a variable and a model output. See an example in Figure 3. Variable response plot illustrates how the mean survival curve change along with the changing values of the variable. It is inspired by partial dependence plots [@RJ-2017-016]. 
+
+![Variable response plot for three models and variable sex. In survival random forest the sex variable affects model predictions in a different way than in  other models.](img/variable_response.png)
+
+- **model performance** curves present prediction error for the chosen survival model depending on time. See an example in Figure 4. For computing prediction error we use the expected Brier Score [@BSScore]. At a given time point t, the Brier score for a single observation is the squared difference between observed survival status and a model-based prediction of surviving time t.
+
+![Model performance plot for three models. In random forest model predictions are less accurate after year 4.](img/model_performance.png)
+
+<!-- Mentions (if applicable) of any ongoing research projects using the software or recent scholarly publications enabled by it -->
+
+# Conclusions and future work
+
+Explainers implemented in the `survxai` package allow exploring one or more models in a feature-by-feature fashion. This approach will miss interactions between variables that may be handled by the models. The main problem with integrations is that number of interactions grows rapidly with the number of features what makes it hard to present in a readable form. 
+
+# Acknowledgments
+
+The work was supported by NCN Opus grant 2016/21/B/ST6/02176.
+
+<!-- A list of key references including a link to the software archive -->
+
+# References
+
+