[docs] Rudimentary documentation (#5)

JuliaSurv · Jun 8, 2024 · 0a304e6 · 0a304e6 · lrnv · Jun 8, 2024
1 parent a10eaf9
commit 0a304e6
Show file tree

Hide file tree

Showing 3 changed files with 28 additions and 1 deletion.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -4,7 +4,12 @@ CurrentModule = SurvivalBase
 
 # SurvivalBase
 
-Documentation for [SurvivalBase](https://github.com/JuliaSurv/SurvivalBase.jl).
+The [`SurvivalBase.jl`](https://github.com/JuliaSurv/SurvivalBase.jl) package is intended to hold internals and shared infrastructure for several other front-facing packages in the [JuliaSurv](https://github.com/JuliaSurv) organization, while having the minimal set of dependencies. Please do not use it directly and instead used other front-facing packages and interfaces from the organization.
+
+Right now, the main infrastructure consists of special functions `Surv` and `Strata` used in [`StatsModels.jl`](https://juliastats.org/StatsModels.jl/stable/api/)'s `@formula`s to be able to express as formulas strandard survival models. 
+
+The current implementation only provides bindings for right censored survivals times (with `Surv(T,Δ)`, left-hand-side of formulas) and *stratified* estimators (with `Strata(x)`, right-hand-side of formulas), but extensions to more complex survival times (e.g. truncation and/or censoring from right and/or left) is planned (note: it would be straightforward and non-breaking). 
+
 
 ```@index
 ```

diff --git a/src/Strata.jl b/src/Strata.jl
@@ -1,3 +1,14 @@
+"""
+    Strata(x::Symbol)
+
+Create a `StrataTerm` object that holds a variable in the construction of a formula to stratify an estimator. 
+
+The behavior of the stratification depends on the fitted estimator: is is usally used on the right hand side of formulas from [`StatsModels.jl`](https://github.com/JuliaStats/StatsModels.jl) as
+
+    @formula(Surv(time,status) ~ Strata(covariate1) + covariate 2)
+
+It then has a behavior that unufortunately heavily depends on the estimator, e.g. stratification of a log-rank-type test. 
+"""
 Strata(x) = x
 struct StrataTerm{X} <: AbstractTerm
     Covariable::X

diff --git a/src/Surv.jl b/src/Surv.jl
@@ -1,3 +1,14 @@
+"""
+    Surv(T::Symbol, Δ::Symbol)
+
+Create a `SurvTerm` object that holds a tuple of variables `(T,Δ)` in the construction of a formula, usually on the left-hand-side, representing a right-censored output time `T` with its status indicatrix `Δ`: Δ being true means that the time was indeed observed, while false means censoring. 
+
+This information, usually on the left hand side a formula, has then a behavior that may depend on the estimator. It allows to use formulas from [`StatsModels.jl`](https://github.com/JuliaStats/StatsModels.jl) as follow: 
+
+    @formula(Surv(time,status) ~ covariate1 + covariate 2)
+
+This usage is common in, e.g., cox models. However, note that the *meaning* of the formula heavily depends on the model : for hazard regession and maximum likelyhood estimation, this does not mean the same thing. 
+"""
 Surv(T::Float64, Δ::Bool) = (T, Δ)
 struct SurvTerm{X, Y} <: AbstractTerm
     T::X