Merge pull request #118 from NSAPH-Software/release_0.2.1

Release 0.2.1

Author: Naeemkh

.Rbuildignore

@@ -17,3 +17,5 @@ index.md
 ^docker_singularity/*$
 ^functional_tests/*$
 ^CRAN-SUBMISSION$
+^paper/*$
+^CODE_OF_CONDUCT\.md$

.gitignore

@@ -13,3 +13,5 @@ src-i386
 *.ipynb
 *.pdf
 *.log
+.Rdata
+.httr-oauth

CODE_OF_CONDUCT.md

@@ -0,0 +1,126 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at nkhoshnevis@g.harvard.edu. 
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][https://github.com/mozilla/inclusion].
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at <https://www.contributor-covenant.org/translations>.
+
+[homepage]: https://www.contributor-covenant.org

DESCRIPTION

@@ -2,7 +2,7 @@ Type: Package
 Package: CRE
 Title: Interpretable Subgroups Identification Through Ensemble Learning of
     Causal Rules
-Version: 0.2.0
+Version: 0.2.1
 Authors@R: c(
     person("Naeem", "Khoshnevis", , "nkhoshnevis@g.harvard.edu", role = c("aut", "cre"),
            comment = c(ORCID = "0000-0003-4315-1426", AFFILIATION = "FASRC")),
@@ -50,7 +50,6 @@ Imports:
     stabs,
     stringr,
     SuperLearner,
-    dplyr,
     magrittr,
     ggplot2,
     bcf,

NEWS.md

@@ -1,3 +1,20 @@
+# CRE 0.2.1 (2023-3-17)
+
+## Changed
+* Replace BATE with ATE in CATE Linear Decomposition.
+* Update `plot()` function (remove ATE, old BATE, and explicit AATEs).
+
+## Added
+* Code of Conduct.
+
+## Removed
+* Causal Tree benchmark in functional tests.
+
+## Bug fixes
+* Rank-Deficient Rule Matrix Issue (redundant rules).
+* Intervention Variables Filtering (ordered filtering).
+
+
 # CRE 0.2.0 (2023-1-19)
 
 ## Changed

R/CRE_package.R

@@ -2,16 +2,23 @@
 #' The 'CRE' package
 #'
 #' @description
-#' Provides an interpretable identification of subgroups with
-#' heterogeneous causal effect. The heterogeneous subgroups are
-#' discovered through ensemble learning of causal rules. Causal rules are
-#' highly interpretable if-then statement that recursively partition the
-#' features space into heterogeneous subgroups. A small number of
-#' significant causal rules are selected through Stability Selection to
-#' control for family-wise error rate in the finite sample setting. It
-#' proposes various estimation methods for the conditional causal effects
-#' for each discovered causal rule.  It is highly flexible and multiple
-#' causal estimands and imputation methods are implemented.
+#' In health and social sciences, it is critically important to 
+#' identify subgroups of the study population where a treatment 
+#' has notable heterogeneity in the causal effects with respect 
+#' to the average treatment effect. Data-driven discovery of 
+#' heterogeneous treatment effects (HTE) via decision tree methods 
+#' has been proposed for this task. Despite its high interpretability, 
+#' the single-tree discovery of HTE tends to be highly unstable and to 
+#' find an oversimplified representation of treatment heterogeneity. 
+#' To accommodate these shortcomings, we propose Causal Rule Ensemble 
+#' (CRE), a new method to discover heterogeneous subgroups through an 
+#' ensemble-of-trees approach. CRE has the following features: 
+#' 1) provides an interpretable representation of the HTE; 2) allows 
+#' extensive exploration of complex heterogeneity patterns; and 3) 
+#' guarantees high stability in the discovery. The discovered subgroups 
+#' are defined in terms of interpretable decision rules, and we develop 
+#' a general two-stage approach for subgroup-specific conditional 
+#' causal effects estimation, providing theoretical guarantees.
 #'
 #' @docType package
 #' @name CRE-package
@@ -23,6 +30,7 @@
 #' @author Falco Joannes Bargagli Stoffi
 #' @import xtable
 #' @import data.table
+#' @import SuperLearner
 #' @importFrom RRF RRF
 #' @importFrom RRF getTree
 #' @importFrom gbm pretty.gbm.tree
@@ -31,9 +39,8 @@
 #' @importFrom methods as
 #'
 #' @references
-#' Lee, K.,
-#' Bargagli-Stoffi, F. J., & Dominici, F. (2020). Causal rule ensemble:
-#' Interpretable inference of heterogeneous treatment effects.  arXiv
-#' preprint arXiv:2009.09036.
+#' Bargagli-Stoffi, F. J., Cadei, R., Lee, K. and Dominici, F. (2023). 
+#' Causal rule ensemble: Interpretable Discovery and Inference of 
+#' Heterogeneous Treatment Effects,arXiv preprint arXiv:2009.09036 
 #'
 NULL

R/check_hyper_params.R

@@ -100,7 +100,13 @@ check_hyper_params <- function(X_names, params) {
     if (!inherits(t_ext, "numeric")) {
       stop("Invalid 't_ext' input. Please input a number.")
     }
+    if (t_ext > 0.5 || t_ext < 0){
+      stop(paste("t_ext should be defind in [0, 0.5) range. ",
+                 "Current provided value: ", t_ext))
+    }
   }
+
+
   params[["t_ext"]] <- t_ext
 
   t_corr <- getElement(params, "t_corr")

R/check_input_data.R

@@ -20,7 +20,7 @@ check_input_data <- function(y, z, X, ite = NULL) {
 
   # Observed Outcome
   if (is.matrix(y)) {
-    if (ncol(y)!=1 || !(is.numeric(y[,1]) || is.integer(y[,1]))) {
+    if (ncol(y) != 1 || !(is.numeric(y[, 1]) || is.integer(y[, 1]))) {
       stop("Observed response vector (y) input values should be a numerical
            vector, not a matrix")
     }
@@ -34,14 +34,14 @@ check_input_data <- function(y, z, X, ite = NULL) {
 
   # Treatment
   if (is.matrix(z)) {
-    if (ncol(z)!=1 || !(is.numeric(z[,1]) || is.integer(z[,1]))
-        | length(unique(z)) != 2) {
+    if (ncol(z) != 1 || !(is.numeric(z[, 1]) || is.integer(z[, 1]))
+        || length(unique(z)) != 2) {
       stop("Treatment vector (z) input values should be a numerical binary
            vector, not a matrix")
     }
     N_check <- nrow(z)
-  } else if (is.vector(z) & (is.numeric(z) || is.integer(z))
-             & length(unique(z)) == 2) {
+  } else if (is.vector(z) && (is.numeric(z) || is.integer(z))
+             && length(unique(z)) == 2) {
     N_check <- length(z)
   } else {
     stop(paste0("Treatment vector (z) input values should be",

R/check_method_params.R

@@ -23,7 +23,7 @@ check_method_params <- function(y, ite, params) {
   if (length(ratio_dis) == 0) {
     ratio_dis <- 0.5
   } else {
-    if (!inherits(ratio_dis, "numeric") | (ratio_dis < 0) | (ratio_dis > 1)) {
+    if (!inherits(ratio_dis, "numeric") || (ratio_dis < 0) || (ratio_dis > 1)) {
       stop("Invalid 'ratio_dis' input. Please input a number between 0 and 1.")
     }
   }
@@ -35,10 +35,10 @@ check_method_params <- function(y, ite, params) {
   if (length(ite_method_dis) == 0) {
     ite_method_dis <- "aipw"
   } else {
-    if (!(ite_method_dis %in% c("aipw", "slearner","tlearner","xlearner",
-                                "bart","bcf","cf","tpoisson"))) {
+    if (!(ite_method_dis %in% c("aipw", "slearner", "tlearner", "xlearner",
+                                "bart", "bcf", "cf", "tpoisson"))) {
       stop(paste(
-        "Invalid ITE method for Discovery Subsample. Please choose ",
+        "Invalid ITE method for discovery subsample. Please choose ",
         "from the following:\n", "'aipw', 'bart', 'slearner','tlearner', ",
         "'xlearner', 'bcf', 'cf', or 'tpoisson'"
       ))
@@ -50,10 +50,10 @@ check_method_params <- function(y, ite, params) {
   if (length(ite_method_inf) == 0) {
     ite_method_inf <- "aipw"
   } else {
-    if (!(ite_method_dis %in% c("aipw", "slearner","tlearner","xlearner",
-                                "bart","bcf", "cf", "tpoisson"))) {
+    if (!(ite_method_inf %in% c("aipw", "slearner", "tlearner", "xlearner",
+                                "bart", "bcf", "cf", "tpoisson"))) {
       stop(paste(
-        "Invalid ITE method for Inference Subsample. Please choose ",
+        "Invalid ITE method for inference subsample. Please choose ",
         "from the following:\n", "'aipw', 'bart', 'slearner','tlearner', ",
         "'xlearner', 'bcf', 'cf', or 'tpoisson'"
       ))
@@ -65,7 +65,8 @@ check_method_params <- function(y, ite, params) {
   # Propensity Score Estimation Parameters Check--------------------------------
 
   ps_method_dis <- getElement(params, "ps_method_dis")
-  if (!(ite_method_dis %in% c("slearner", "tlearner", "xlearner", "tpoisson"))) {
+  if (!(ite_method_dis %in% c("slearner", "tlearner",
+                              "xlearner", "tpoisson"))) {
     if (length(ps_method_dis) == 0) {
       ps_method_dis <- "SL.xgboost"
     } else {
@@ -80,7 +81,8 @@ check_method_params <- function(y, ite, params) {
   params[["ps_method_dis"]] <- ps_method_dis
 
   ps_method_inf <- getElement(params, "ps_method_inf")
-  if (!(ite_method_inf %in% c("slearner", "tlearner", "xlearner", "tpoisson"))) {
+  if (!(ite_method_inf %in% c("slearner", "tlearner",
+                              "xlearner", "tpoisson"))) {
     if (length(ps_method_inf) == 0) {
       ps_method_inf <- "SL.xgboost"
     } else {