From 6e82490244f37a47f0d3a0fe99e2ec395ac732d5 Mon Sep 17 00:00:00 2001 From: guifabre Date: Tue, 30 Apr 2024 13:15:50 -0400 Subject: [PATCH] update documentation --- NEWS.md | 71 +++++++++++++++++++++++++++------- R/00_utils.R | 4 +- R/02_algorithm.R | 69 +++++++++++++++++++++++++++++++++ README.md | 16 +++++--- man/get_banff_dictionary.Rd | 2 +- vignettes/banffIT-vignette.Rmd | 2 +- 6 files changed, 140 insertions(+), 24 deletions(-) diff --git a/NEWS.md b/NEWS.md index f54187f..c0c08f9 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,22 +1,63 @@ -# banffIT 1.0.0 +# banffIT 0.1.0 -This package is a xxx xxx xxx +The banffIT package provides provides functions to assign standardized +diagnosis using the Banff Classification (Category 1 to 6 diagnoses, +including Acute and Chronic active T-cell mediated rejection as well as +Active, Chronic active, and Chronic antibody mediated rejection). The +main function +[banff_launcher()](https://PersonalizedTransplantCare.github.io/banffIT-documentation/reference/banff_launcher.html) +considers a minimal dataset containing biopsies information in a +specific format (described by a data dictionary), verifies its content +and format (based on the data dictionary), assign diagnoses, and create +a summary report. -## Helper functions +## Main functionality + +- function `banff_launcher()` This function takes a path string + identifying the input file path. The function internally runs a series + of tests that assess the input dataset. If any of these tests fails, + the user gets information allowing them to correct the input dataset + and rerun the process. Once all tests pass, the dataset is given as an + output with a diagnosis for each observation (using the function + [add_diagnosis()](https://PersonalizedTransplantCare.github.io/banffIT-documentation/reference/add_diagnosis.html) + internally). The output dataset, along with its associated labels + (“label:en” by default) are provided to the user in an Excel format + file accessible in the output_folder specified (the working directory + by default). The output dataset comes with a report that summarizes + information about variable distributions and descriptive statistics. + +## additional functions (used in the main function, but can be used separately) + +- function `banff_dataset_evaluate()` This function takes a dataset and + evaluates its format and content based on the accepted format + specified in the data dictionary. -- xxx xxx xxx +- function `calculate_adequacy()` A tibble object with two columns: the + calculated adequacy (adequacy_calculated) and the adequacy specified + in input (adequacy_input). -## functions xxx xxx xxx +- function `dataset_cat_as_labels()` + [Function](https://maelstrom-research.github.io/madshapR-documentation/reference/dataset_cat_as_labels.html) + exported from the madshapR package. + +- function `add_diagnosis()` This function takes a dataset and returns a + diagnosis for each observation. For the function to run, the dataset + must not contain any errors that + [banff_launcher()](https://PersonalizedTransplantCare.github.io/banffIT-documentation/reference/banff_launcher.html) + would have detected. Please prefer using `banff_launcher()` to run + additional tests. + +- function `dataset_summarize()` + [Function](https://maelstrom-research.github.io/madshapR-documentation/reference/summarize.html) + exported from the madshapR package. + +## Helper functions -These functions allows to xxx xxx xxx. +- function `get_banff_dictionary()` This function gets the data + dictionary used to control the consistency of the banff dataset. -- function `add_diagnosis()` does xxx xxx xxx -- function `banff_dataset_evaluate()` does xxx xxx xxx -- function `banff_dataset_summarize()` does xxx xxx xxx -- function `banff_launcher()` does xxx xxx xxx -- function `calculate_adequacy()` does xxx xxx xxx -- function `dataset_cat_as_labels()` does xxx xxx xxx -- function `get_banff_dictionary()` does xxx xxx xxx -- function `is_banff_dataset()` does xxx xxx xxx -- function `banffIT_website()` does xxx xxx xxx +- function `banffIT_website()` This function sends the user to the + online documentation for the package, which includes a description of + the latest version of the package, vignettes, user guides, and a + reference list of functions and help pages. diff --git a/R/00_utils.R b/R/00_utils.R index 4e9e3e3..cf0723a 100644 --- a/R/00_utils.R +++ b/R/00_utils.R @@ -2,7 +2,7 @@ #' Get the banff data dictionary #' #' @description -#' This function gets the data dictionary used to control the consistancy of +#' This function gets the data dictionary used to control the consistency of #' the banff dataset. #' #' @param which Indicates which banff dictionary to get. Either "input" or @@ -136,7 +136,7 @@ The possible `language` are : ",toString(labels)) #' @export banffIT_website <- function(){ - browseURL("https://maelstrom-research.github.io/banffIT-documentation/") + browseURL("https://PersonalizedTransplantCare.github.io/banffIT-documentation/") } diff --git a/R/02_algorithm.R b/R/02_algorithm.R index d133b5b..f5986cb 100644 --- a/R/02_algorithm.R +++ b/R/02_algorithm.R @@ -984,3 +984,72 @@ madshapR::dataset_cat_as_labels #' @keywords imported #' @export madshapR::dataset_summarize + + + +# @title +# summarise a banff dataset with its diagnosis +# +# @description +# Assesses and summarizes the content and structure of a banff dataset (with +# diagnosis) and generates reports of the results. This function can be used +# to evaluate data structure, and to summarize additional information about +# variable distributions and descriptive statistics. +# +# @param banff_diagnosis A banff dataset object with diagnosis. +# @param banff_assessment A tibble object. +# @param banff_dict A list of tibble objects giving information on the +# assessment of the banff dataset. +# @param banff_file_name A character string specifying the name of the dataset. +# +# @return +# A list of tibble objects giving information on the summary of the banff +# dataset. +# +# @examples +# { +# +# library(fabR) +# banff_file <- system.file("extdata", "example.xlsx", package = "banffIT") +# banff_dataset <- read_excel_allsheets(banff_file)[1,] +# banff_dataset_evaluate(banff_dataset) +# +# } +# +# @import dplyr tidyr madshapR +# @importFrom rlang .data +# @export +# banff_dataset_summarize <- function( +# banff_diagnosis, +# banff_assessment = NULL, +# banff_dict, +# banff_file_name) { +# +# if(is.null(banff_assessment)) +# banff_assessment <- banff_dataset_evaluate(banff_diagnosis$codeset) +# +# banff_report <- +# banff_dataset_summarize( +# dataset = banff_diagnosis$codeset, +# data_dict = banff_dict, +# dataset_name = banff_file_name) +# +# banff_report$`Dataset assessment - input` <- banff_assessment$`Dataset assessment` +# banff_report$`Dataset assessment - diagnosis` <- banff_report$`Dataset assessment` +# banff_report$`Dataset assessment` <- NULL +# banff_report$`Variables summary (all)` <- banff_assessment$`Data dictionary summary` +# +# banff_report$`Dataset assessment - diagnosis` <- +# banff_report$`Dataset assessment - diagnosis` %>% +# select("column" = "name","condition" = "Quality assessment comment", "value") %>% +# dplyr::filter(!.data$`column` %in% banff_report$`Dataset assessment - input`$column) +# +# banff_report <- banff_report[unique(c( +# "Overview","Dataset assessment - input", +# "Dataset assessment - diagnosis", names(banff_report)))] +# +# return(banff_report) +# +# } + + diff --git a/README.md b/README.md index b46043e..3d06ebd 100644 --- a/README.md +++ b/README.md @@ -12,14 +12,16 @@ The banffIT package provides provides functions to assign standardized diagnosis using the Banff Classification (Category 1 to 6 diagnoses, including Acute and Chronic active T-cell mediated rejection as well as Active, Chronic active, and Chronic antibody mediated rejection). The -main function [banff_launcher()](banff_launcher()) considers a minimal -dataset containing biopsies information in a specific format (described -by a data dictionary), verifies its content and format (based on the -data dictionary), assign diagnoses, and create a summary report. +main function +[banff_launcher()](https://PersonalizedTransplantCare.github.io/banffIT-documentation/reference/banff_launcher.html) +considers a minimal dataset containing biopsies information in a +specific format (described by a data dictionary), verifies its content +and format (based on the data dictionary), assign diagnoses, and create +a summary report. # Get started -## Install the package +## Install the package and use the example file ``` r # To install madshapR: @@ -28,4 +30,8 @@ install.packages('banffIT') library(banffIT) # If you need help with the package, please use: banffIT_website() + +# use the example file provided. remplace tempdir by a directory name. +banff_file <- system.file("extdata", "example.xlsx", package = "banffIT") +banff_launcher(banff_file, output_folder = tempdir()) ``` diff --git a/man/get_banff_dictionary.Rd b/man/get_banff_dictionary.Rd index f3a78c3..f0d7291 100644 --- a/man/get_banff_dictionary.Rd +++ b/man/get_banff_dictionary.Rd @@ -22,7 +22,7 @@ A list of tibbles representing meta data used in the process. The metadata are the list of variables used, and their associated categories, if any. } \description{ -This function gets the data dictionary used to control the consistancy of +This function gets the data dictionary used to control the consistency of the banff dataset. } \examples{ diff --git a/vignettes/banffIT-vignette.Rmd b/vignettes/banffIT-vignette.Rmd index 6f9b75a..6a008af 100644 --- a/vignettes/banffIT-vignette.Rmd +++ b/vignettes/banffIT-vignette.Rmd @@ -29,7 +29,7 @@ report. ## Install the package and use the example file ```{r, eval=FALSE} -# To install madshapR: +# To install banffIT: install.packages('banffIT') library(banffIT)