update paper.md

misc/paper.bib

@@ -3,21 +3,19 @@ @Manual{ceterisParibus
     author = {Biecek, Przemysław},
     year = {2018},
     note = {R package version 0.2.1},
-    url = {https://CRAN.R-project.org/package=ceterisParibus}
+    url = {http://CRAN.R-project.org/package=ceterisParibus}
   }
 
 @article{2018arXiv180608915B,
-   author = {{Biecek}, Przemysław},
+	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}
+    url = {http://arxiv.org/abs/1806.08915},
+	eprint = {1806.08915},
+	primaryClass = "stat.ML",
+	keywords = {Statistics - Machine Learning, Computer Science - Artificial Intelligence, Computer Science - Machine Learning, Statistics - Applications},
+    year = 2018,
+	adsurl = {http://adsabs.harvard.edu/abs/2018arXiv180608915B},
+	adsnote = {Provided by the SAO/NASA Astrophysics Data System}
 }
 
 
@@ -26,7 +24,7 @@ @book{collett2015modelling
   author={Collett, David},
   isbn={9781498731690},
   series={Chapman \& Hall/CRC Texts in Statistical Science},
-  url={https://books.google.pl/books?id=Okf7CAAAQBAJ},
+  url={http://books.google.pl/books?id=Okf7CAAAQBAJ},
   year={2015},
   publisher={CRC Press}
 }
@@ -43,11 +41,12 @@ @article{lu2003modeling
 @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.},
+  journal = {The Annals of Applied Statistics},
   year = {2008},
   volume = {2},
   number = {3},
   pages = {841--860},
+  doi = {doi:10.1214/08-AOAS169},
   url = {http://arXiv.org/abs/0811.1645v1},
   pdf = {http://arxiv.org/pdf/0811.1645},
 }
@@ -61,8 +60,8 @@ @article{ELEUTERI2003855
   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},
+  doi = {10.1016/S0893-6080(03)00098-4},
+  url = {http://doi.org/10.1016/S0893-6080(03)00098-4},
   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}
 }
@@ -72,7 +71,7 @@ @article{RJ-2017-016
   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},
+  url = {http://journal.r-project.org/archive/2017/RJ-2017-016/index.html},
   pages = {421--436},
   volume = {9},
   number = {1}
@@ -94,21 +93,19 @@ @Article{BSScore
 @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,
+	url = {http://arxiv.org/abs/1804.01955},
    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},
+  url = {http://doi.org/10.21105/joss.00786},
   year  = {2018},
   month = {jun},
   publisher = {The Open Journal},
@@ -128,7 +125,7 @@ @misc{pramit_choudhary_2018_1198885
   month        = mar,
   year         = 2018,
   doi          = {10.5281/zenodo.1198885},
-  url          = {https://doi.org/10.5281/zenodo.1198885}
+  url          = {http://doi.org/10.5281/zenodo.1198885}
 }
 
 
@@ -160,8 +157,8 @@ @article{doi:10.4155/fmc.11.23
   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}
+  URL = {http://doi.org/10.4155/fmc.11.23},
+  eprint = {http://doi.org/10.4155/fmc.11.23}
 }
 
 

misc/paper.md

@@ -1,5 +1,5 @@
 ---
-title: 'survxai: an R package for model agnostic explanations of survival models'
+title: 'survxai: an R package for model-agnostic explanations of survival models'
 authors:
 - affiliation: 1, 2
   name: Aleksandra Grudziaz
@@ -10,7 +10,7 @@ authors:
 - affiliation: 1, 2
   name: Przemyslaw Biecek
   orcid: 0000-0001-8423-1823
-date: "3 August 2018"
+date: "23 August 2018"
 output: pdf_document
 bibliography: paper.bib
 tags:
@@ -20,63 +20,63 @@ tags:
 - interpretable machine learning
 affiliations:
 - index: 1
-  name: Faculty of Mathematics, Informatics, and Mechanics, University of Warsaw
-- index: 2
   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.
+Predictive models are widely used in supervised machine learning. Three most common classes of such models are: *regression models*, where the target variable is continuous numeric, *classification models*, where the target variable is binary or categorical and *survival models*, where the target is some censored variable. Common examples of censored variables are times to death (but some cases lived for x years and are still alive), cessation of service by customer, or failure of machine components.
 
-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. 
+Modern predictive models are often complex in structure; for example neural networks [@ELEUTERI2003855] or random forest [@randomForestSRC]. Such sophisticated tools are also more and more often used in survival analysis. These models may be described by thousands of coefficients. Often such flexibility leads to high performance, but makes models opaque and hard to understand. This is acceptable in cases where only the model accuracy is important, but in cases that involve human decisions, it may not be informative 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. 
+The area of model interpretability or explanability has quickly gained the attention of machine learning experts. Understanding of complex models leads not only to higher trust in model predictions but also better models. Better, means that the models are more robust and obtains higher accuracy on validation data. See examples in the `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.
+Existing tools for model agnostic explanations are focused on regression models and classification problems, as in both cases model predictions that may be summarised by a single number. Survival models require different approaches as predictions are in a form of survival curves. Demand for such explainers has led to some model specific solutions, like `iSurvive` [@pmlr-v70-dempsey17a] for continuous time hidden Markov models. Yet, there is currently a lack 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.
+The `survxai` fills 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 survival random forest models and for Cox models.
+The `survxai` package consists of new implementations and visualisations of explainers, designed for survival models. Functions are well documented and the package is supplemented with unit tests, and illustrations.
+Regardless of the complexity of the model, the 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. 
+The R package `survxai` is a tool for creating explanations of survival models. It is model-agnostic, and thus works for both complex and simple survival models. It also allows for comparisons between 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). 
+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).
+The package `survxai` is available on CRAN. It can be install using the command `install.packages('survxai')`. The 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. 
+- **The Ceteris Paribus** plot presents model responses around a single point in the feature space [@ceterisParibus]. See Figure 1 for an example. Each panel is related to a single variable. Each single panel shows how a model prediction (survival curve) would change if only a single variable were changed. It is useful for *what-if* reasoning. Each curve in a panel is related to a different value of the selected variable.
+The Ceteris Paribus plot illustrates how the survival curve may change with the changing of values of 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)
+![Ceteris Paribus plot for survival random forest model with three variables. The black dashed survival curve corresponds to an observation of interest. The left panel shows the survival curves for different values of bilirubin. Colors correspond to mean survival curves of observations from quintiles. From red which is the first quintile to blue which is the last one. The middle panel shows that prediction for sex=0 is worse than for sex=1 for times less than 7.5. The right panel analogously shows survival curves for different levels of the variable stage.](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.
+- **The break down** plot presents variable contributions in final predictions  [@2018arXiv180401955S]. See Figure 2 for an example. The break down of predictions for survival models help to understand which factors drive survival probabilities 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)
+![Break down plot for survival random forest model. Variables bili and stage have the highest impact on the 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]. 
+- **The variable response** plot is designed to better understand the relation between a variable and a model output. See Figure 3 for an example. The variable response plot illustrates how the mean survival curve changes 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)
+![Variable response plots 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.
+- **The model performance** curves present prediction error for the chosen survival model, depending on time. See Figure 4 for an example. 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)
+![Model performance plots 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. 
+Explainers implemented in the `survxai` package allow for exploration of 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
 
@@ -87,3 +87,4 @@ The work was supported by NCN Opus grant 2016/21/B/ST6/02176.
 # References
 
 
+