Merge pull request #82 from ttscience/refine-README

Issue #58 Added descriptions of the remaining endpoints implemented in API

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: unbiased
-Title: Diverse Randomization Algorithms for Clinical Trials
+Title: Unbiased: Production-Grade Randomization API
 Version: 1.0.0
 Authors@R: c(
     person("Kamil", "Sijko", , "[email protected]",
@@ -10,20 +10,14 @@ Authors@R: c(
            role = c("aut")),
     person("Łukasz", "Wałejko", , "[email protected]",
            role = c("aut")),
-    person("Jagoda", "Głowacka-Walas", "[email protected]",
+    person("Jagoda", "Głowacka-Walas", ,"[email protected]",
            role = c("aut"), comment = c(ORCID = "0000-0002-7628-8691")),
+    person("Laura", "Bąkała", , role = c("aut")),
     person("Michał", "Seweryn", , "[email protected]",
-           role = c("ctr"), comment = c(ORCID = "0000-0002-9090-3435")),
+           role = c("ctb"), comment = c(ORCID = "0000-0002-9090-3435")),
     person("Transition Technologies Science Sp. z o.o.", role = c("fnd", "cph"))
     )
-Description: The Unbiased package offers a comprehensive suite of randomization
- algorithms for clinical trials, encompassing dynamic strategies like the 
- minimization method, simple randomization approaches, and block randomization
- techniques. Its primary purpose is to provide a harmonized set of functions that
- will seamlessly integrate with a production-ready plumber API, also contained
- within the package. This integration is designed to facilitate a smooth and
- efficient interface with electronic Case Report Form (eCRF) systems, enhancing
- the capability of clinical trials to manage patient allocation.
+Description: The Unbiased package delivers a minimization-based randomization algorithm for patient allocation in clinical trials, fully integrated with a production-ready API. It's designed to work seamlessly with a persistent PostgreSQL database, ensuring reliable data management and integrity. Packaged into precompiled Docker images, Unbiased simplifies deployment to just running docker-compose up, making it exceptionally straightforward to incorporate into your environment.
 License: MIT + file LICENSE
 Imports: 
     checkmate,

NAMESPACE

@@ -1,6 +1,5 @@
 # Generated by roxygen2: do not edit by hand
 
-export(create_db_connection_pool)
 export(randomize_minimisation_pocock)
 export(randomize_simple)
 export(run_unbiased)

R/audit-trail.R

@@ -124,6 +124,7 @@ AuditLog <- R6::R6Class( # nolint: object_name_linter.
 #'
 #' @param pr A plumber router for which the audit trail is to be set up.
 #' @param endpoints A list of regex patterns for which the audit trail should be enabled.
+#' @noRd
 #' @return Returns the updated plumber router with the audit trail hooks.
 #' @examples
 #' pr <- plumber::plumb("your-api-definition.R") |>

R/db.R

@@ -8,8 +8,7 @@
 #' between each attempt.
 #'
 #' @return A pool object representing the connection pool to the database.
-#' @export
-#'
+#' @noRd
 #' @examples
 #' \dontrun{
 #' pool <- create_db_connection_pool()

R/error-handling.R

@@ -9,6 +9,7 @@ globalCallingHandlers <- NULL # nolint
 #' It uses the sentryR package to set up Sentry based on environment variables.
 #'
 #' @param None
+#' @noRd
 #'
 #' @return None. If the SENTRY_DSN environment variable is not set, the function will
 #' return a message and stop execution.

R/randomize-minimisation-pocock.R

@@ -6,6 +6,7 @@
 #'
 #' @param all_patients data.frame with all patients
 #' @param new_patients data.frame with new patient
+#' @noRd
 #'
 #' @return data.frame with columns as in all_patients and new_patients,
 #'  filled with TRUE if there is match in covariate and FALSE if not

README.md

@@ -27,6 +27,10 @@ By choosing **unbiased**, you're adopting a sophisticated approach to trial rand
      - [API Endpoints](#api-endpoints)
         - [Study Creation](#study-creation)
         - [Patient Randomization](#patient-randomization)
+        - [Study List](#study-list)
+        - [Study Details](#study-details)
+        - [Randomization List](#randomization-list)
+        - [Audit Log](#audit-log)
 4. [Technical Implementation](#technical-implementation)
    - [Quality Assurance Measures](#quality-assurance-measures)
    - [Running Tests](#running-tests)
@@ -104,7 +108,6 @@ unbiased::run_unbiased()
 
 This initiates the API server, by default, on your local machine (http://localhost:3838), making it accessible for interaction through various HTTP clients, including curl, Postman, or R's `httr` package.
 
-
 # Getting started with **unbiased**
 
 The **unbiased** package offers functions for randomizing participants in clinical trials, ensuring a fair and transparent process.
@@ -117,65 +120,64 @@ The **unbiased** API is designed to facilitate clinical trial management through
 
 - **Study Management**: Create and configure new studies, including specifying randomization parameters and treatment arms.
 - **Participant Randomization**: Dynamically randomize participants to treatment groups based on the study's configuration and existing participant data.
+- **Study List**: List all previously defined studies.
+- **Study Details**: Show details about the selected study.
+- **Randomization List**: Generate a list of randomized patients for the selected study.
+- **Audit Log**: Show a audit log for the selected study.
 
 
 ### Study Creation
 
 To initialize a study using Pocock's minimization method, use the POST /minimisation_pocock endpoint. The required JSON payload should detail the study, including treatment groups, allocation ratios, and covariates.
 
-```R
-# Initialize a study with Pocock's minimisation method
-response <- request(api_url) |>
-    req_url_path("study", "minimisation_pocock") |>
-    req_method("POST") |>
-    req_body_json(
-      data = list(
-        identifier = "My_study_1",
-        name = "Study 1",
-        method = "var",
-        p = 0.85,
-        arms = list(
-          "placebo" = 1,
-          "treatment" = 1
-        ),
-        covariates = list(
-          sex = list(
-            weight = 1,
-            levels = c("female", "male")
-          ),
-          age = list(
-            weight = 1,
-            levels = c("up to 50", "51 or more")
-          )
-        )
-      )
-    )
-```
-
-This call sets up the study and returns an ID for accessing further study-related endpoints.
+This endpoint sets up the study and returns an ID for accessing further study-related endpoints.
 
 ### Patient Randomization
 
 The POST /{study_id}/patient endpoint assigns a new patient to a treatment group, requiring patient details and covariate information in the JSON payload.
 
-```R
-# Randomize a new patient
-req_url_path("study", my_study_id, "patient") |>
-          req_method("POST") |>
-          req_body_json(
-            data = list(
-              current_state =
-                tibble::tibble(
-                  "sex" = c("female"),
-                  "age" = c("up to 50"),
-                  "arm" = c("") 
-                )
-            )
-          )
-```
-
 This endpoint determines the patient's treatment group.
 
+### Study List
+
+The GET /study/ endpoint allow to list all previously defined studies. It returns information such as:
+
+- Study ID
+- Identifier
+- Name of study
+- Randomization method
+- Last edit date
+
+### Study Details
+The GET /study/{study_id} endpoint allows to retrieve details about a selected study. The response body return:
+
+- Name of study
+- Randomization method
+- Last edit date
+- Input parameters
+- Strata
+
+### Randomization List
+The GET /study/{study_id}/randomization_list endpoint allows to generate a list of randomized patients along with their assigned study arms.
+
+### Audit Log
+
+The GET /study/{study_id}/audit endpoint allows to print all records in the audit log for a selected study.
+The response body includes the following information:
+
+- Log ID
+- Creation date
+- Type of event
+- Request ID
+- Study ID
+- Endpoint URL
+- Request method
+- Request body with study definition
+- Response code
+- Response body with study details
+
+The endpoint facilitates tracking the history of requests sent to the database, along with their corresponding responses. This enables us to trace all actions involving the API.
+
 # Technical details
 
 ## Running Tests