Merge pull request #72 from opensafely-actions/make-v0.0.39

Allow covariate_other option to be specified as a text file of semi-colon separated variable names

Author: venexia

CHANGELOG.md

@@ -1,3 +1,8 @@
+# [v0.0.39](https://github.com/opensafely-actions/cox-ipw/releases/tag/v0.0.39)
+
+- Allow option `--covariate_other` to be specified as a filename of a text file of semi-colon separated variable names.
+- Updated the documentation for `--save_analysis_ready` to reflect that it saves a Stata dataset.
+
 # [v0.0.38](https://github.com/opensafely-actions/cox-ipw/releases/tag/v0.0.38)
 
 - Minor updates to GitHub Actions workflows.

README.md

@@ -57,18 +57,20 @@ as follows:
     Variable name for the age covariate; specify argument as NULL to model without
     age covariate [default cov_num_age]
 
-    --covariate_other=VARNAME_1;VARNAME_2;...
-    Semi-colon separated list of other covariates to be included in the regression
-    model; specify argument as NULL to run age, age squared, sex adjusted model
-    only [default
+    --covariate_other=VARNAME_1;VARNAME_2;... OR COVARIATE-OTHER.TXT
+    Semi-colon separated list of other covariates or filename of text file
+    containing semi-colon separated list of other covariates to be included in the
+    regression model; specify argument as NULL to run age, age squared, sex
+    adjusted model only. Note that if you are including only a single covariate
+    please include the semi-colon after it [default
     cov_cat_ethnicity;cov_num_consulation_rate;cov_bin_healthcare_worker;cov_bin_carehome_status]
 
     --cox_start=VARNAME_1;VARNAME_2;...
     Semi-colon separated list of variable names used to define start of patient
     follow-up or single variable if already defined [default pat_index_date]
 
     --cox_stop=VARNAME_1;VARNAME_2;...
-    semicolon separated list of variable names used to define end of patient
+    Semi-colon separated list of variable names used to define end of patient
     follow-up or single variable if already defined [default
     death_date;out_date_vte;vax_date_covid_1]
 
@@ -109,9 +111,9 @@ as follows:
     --seed=INTEGER
     Random number generator seed passed to IPW sampling [default 137]
 
-    --save_analysis_ready=FILENAME.CSV
-    If provided, analysis ready data csv filename (this is assumed to be within the
-    output directory but can be within a subdirectory) [default ]
+    --save_analysis_ready=FILENAME.DTA
+    If provided, analysis ready Stata dataset filename (this is assumed to be
+    within the output directory but can be within a subdirectory) [default ]
 
     --run_analysis=TRUE/FALSE
     Logical, if analysis should be run [default TRUE]

analysis/cox-ipw.R

@@ -70,8 +70,8 @@ option_list <- list(
     "--covariate_other",
     type = "character",
     default = "cov_cat_ethnicity;cov_num_consulation_rate;cov_bin_healthcare_worker;cov_bin_carehome_status",
-    help = "Semi-colon separated list of other covariates to be included in the regression model; specify argument as NULL to run age, age squared, sex adjusted model only [default %default]",
-    metavar = "varname_1;varname_2;..."
+    help = "Semi-colon separated list of other covariates or filename of text file containing semi-colon separated list of other covariates to be included in the regression model; specify argument as NULL to run age, age squared, sex adjusted model only. Note that if you are including only a single covariate please include the semi-colon after it [default %default]",
+    metavar = "varname_1;varname_2;... or covariate-other.txt"
   ),
   make_option(
     "--cox_start",
@@ -84,7 +84,7 @@ option_list <- list(
     "--cox_stop",
     type = "character",
     default = "death_date;out_date_vte;vax_date_covid_1",
-    help = "semicolon separated list of variable names used to define end of patient follow-up or single variable if already defined [default %default]",
+    help = "Semi-colon separated list of variable names used to define end of patient follow-up or single variable if already defined [default %default]",
     metavar = "varname_1;varname_2;..."
   ),
   make_option(
@@ -161,8 +161,8 @@ option_list <- list(
     "--save_analysis_ready",
     type = "character",
     default = "",
-    help = "If provided, analysis ready data csv filename (this is assumed to be within the output directory but can be within a subdirectory) [default %default]",
-    metavar = "filename.csv"
+    help = "If provided, analysis ready Stata dataset filename (this is assumed to be within the output directory but can be within a subdirectory) [default %default]",
+    metavar = "filename.dta"
   ),
   make_option(
     "--run_analysis",
@@ -206,7 +206,7 @@ print(record_args)
 
 write.csv(
   record_args,
-  file = paste0("output/", gsub(".csv","-args.csv",opt$df_output)),
+  file = paste0("output/", gsub(".csv", "-args.csv", opt$df_output)),
   row.names = FALSE
 )
 
@@ -224,6 +224,31 @@ lapply(
   source
 )
 
+# Read in covariate_other if a filename ----
+# Assuming it's a filename if the character string contains no semi-colons
+# Note to future self/developer - could change the second condition here to look for say .txt in string
+if (!is.null(opt$covariate_other) && !grepl(";", opt$covariate_other)) {
+  # Check if file exists
+  if (!file.exists(opt$covariate_other)) {
+    stop(paste("The file", opt$covariate_other, "does not exist, please check how you have specified the covariate_other option."))
+  }
+
+  # Read in text file contents
+  # Get the size of the file in bytes
+  covariate_other_file_size <- file.info(opt$covariate_other)$size
+
+  # Read the entire file content as a single character string
+  covariate_other_single_string <- readChar(opt$covariate_other, covariate_other_file_size)
+  # Strip newlines from (likely the end of) string (but could be multi-line text file)
+  covariate_other_single_string <- gsub("[\r\n]", "", covariate_other_single_string)
+
+  # Overwrite opt$covariate_other so it can be processed as the direct specification of this option
+  opt$covariate_other <- covariate_other_single_string
+}
+
+# If last character of opt$covariate_other is a ; replace with nothing
+opt$covariate_other <- trimws(opt$covariate_other, which = "right", whitespace = ";")
+
 # Separate list arguments ------------------------------------------------------
 print("Separate list arguments")
 
@@ -654,7 +679,7 @@ if (
 
     results$strata_warning <- strata_warning
 
-    results$cox_ipw <- "v0.0.37"
+    results$cox_ipw <- "v0.0.39"
 
     results <- results[
       order(results$model),

analysis/move-covariate-other-txt.R

@@ -0,0 +1 @@
+file.copy("dummy_tables/covariate-other.txt", "output/covariate-other.txt")

dummy_tables/covariate-other.txt

@@ -0,0 +1 @@
+cov_cat_ethnicity;cov_num_consulation_rate

justfile

@@ -13,3 +13,5 @@ test-4:
     opensafely run cox-ipw_using-args_input-arrow -f
 test-5:
     opensafely run cox-ipw_using-args_input-arrow-subdir -f
+test-6:
+    opensafely run cox-ipw_covariate-other-filename -f

project.yaml

@@ -77,3 +77,19 @@ actions:
       moderately_sensitive:
         arguments: output/results-5-args.csv
         estimates: output/results-5.csv
+
+  cox-ipw_move-covariate-other-filename:
+    run: r:v2 analysis/move-covariate-other-txt.R
+    outputs:
+      moderately_sensitive:
+        covariates: output/covariate-other.txt
+
+  cox-ipw_covariate-other-filename:
+    run: r:v2 analysis/cox-ipw.R --df_input input.csv --covariate_other output/covariate-other.txt --df_output results-6.csv
+    needs:
+    - cox-ipw_move-covariate-other-filename
+    - generate-dataset_csv
+    outputs:
+      moderately_sensitive:
+        arguments: output/results-6-args.csv
+        estimates: output/results-6.csv