From 5793f9f70b9f59d709db9f0130cf4749e87232da Mon Sep 17 00:00:00 2001 From: FBartos Date: Wed, 23 Oct 2024 17:40:27 +0200 Subject: [PATCH] add documentation --- inst/qml/NonParametricSurvivalAnalysis.qml | 19 +++++++++- inst/qml/SemiParametricSurvivalAnalysis.qml | 41 +++++++++++++++++++++ inst/qml/qml_components/SurvivalPlot.qml | 15 ++++++++ 3 files changed, 74 insertions(+), 1 deletion(-) diff --git a/inst/qml/NonParametricSurvivalAnalysis.qml b/inst/qml/NonParametricSurvivalAnalysis.qml index e3aef12..81921b4 100644 --- a/inst/qml/NonParametricSurvivalAnalysis.qml +++ b/inst/qml/NonParametricSurvivalAnalysis.qml @@ -24,7 +24,9 @@ import JASP 1.0 import "./qml_components" as SA Form -{ +{ + info: qsTr("This analysis computes a survival curve for censored data using the Kaplan-Meier estimator for single-event survival data. It estimates the probability of survival over time, allowing you to understand and visualize the distribution of survival times within your data. The analysis accommodates censored observations (subjects for whom the event has not occurred during the study period) and enables comparison of survival curves across different groups using statistical tests such as the Log-Rank test, Peto and Peto test, and Fleming-Harrington test. Additionally, you can generate life tables to summarize survival data at specified intervals.") + VariablesForm { AvailableVariablesList @@ -38,6 +40,7 @@ Form title: qsTr("Time to Event") allowedColumns: ["scale"] singleVariable: true + info: qsTr("Select the variable that represents the time until the event or censoring occurs.") } AssignedVariablesList @@ -47,6 +50,7 @@ Form title: qsTr("Event Status") allowedColumns: ["nominal"] singleVariable: true + info: qsTr("Choose the variable that indicates the event status, specifying whether each observation is an event or censored.") } DropDown @@ -55,6 +59,7 @@ Form label: qsTr("Event Indicator") source: [{name: "eventStatus", use: "levels"}] onCountChanged: currentIndex = 1 + info: qsTr("Specify the value in the Event Status variable that indicates the occurrence of the event.") } AssignedVariablesList @@ -63,6 +68,7 @@ Form id: strata title: qsTr("Strata") allowedColumns: ["nominal"] + info: qsTr("Select variables to define strata, allowing separate survival curves for each stratum.") } } @@ -77,18 +83,21 @@ Form { name: "testsLogRank" label: qsTr("Log-rank (Mantel-Haenszel)") + info: qsTr("Include the Log-Rank (Mantel-Haenszel) test to compare survival curves across strata.") } CheckBox { name: "testsPetoAndPeto" label: qsTr("Peto and Peto") + info: qsTr("Include the Peto and Peto modification of the Gehan-Wilcoxon test to compare survival curves across strata.") } CheckBox { name: "testsFlemmingHarrington" label: qsTr("Flemming-Harrington") + info: qsTr("Include the Fleming-Harrington test to compare survival curves across strata., with a customizable rho parameter.") DoubleField { @@ -97,6 +106,7 @@ Form defaultValue: 0.5 min: 0 max: 1 + info: qsTr("Set the rho parameter for the Fleming-Harrington test, controlling the weight given to different time points (values between 0 and 1).") } } } @@ -105,12 +115,14 @@ Form { name: "lifeTable" label: qsTr("Life table") + info: qsTr("Generate a life table summarizing survival data at specified time intervals.") DropDown { name: "lifeTableStepsType" id: lifeTableStepsType label: qsTr("Steps type") + info: qsTr("Select the method to define intervals for the life table: Default, Quantiles, or Fixed size.") values: [ { label: qsTr("Default"), value: "default"}, @@ -125,6 +137,7 @@ Form label: qsTr("Number") defaultValue: 10 visible: lifeTableStepsType.value == "quantiles" + info: qsTr("Specify the number of intervals when using Quantiles as the steps type.") } CheckBox @@ -133,6 +146,7 @@ Form label: qsTr("Round steps") checked: true visible: lifeTableStepsType.value == "quantiles" + info: qsTr("Round the interval boundaries to the nearest integer when using Quantiles steps.") } DoubleField @@ -143,6 +157,7 @@ Form defaultValue: 0 max: lifeTableStepsTo.value visible: lifeTableStepsType.value == "fixedSize" + info: qsTr("Set the starting time for intervals when using Fixed size steps.") } DoubleField @@ -152,6 +167,7 @@ Form defaultValue: 1 // max: lifeTableStepsTo.value // TODO: enable once max is data dependent visible: lifeTableStepsType.value == "fixedSize" + info: qsTr("Define the size of each interval when using Fixed size steps.") } DoubleField @@ -162,6 +178,7 @@ Form defaultValue: 0 min: lifeTableStepsFrom.value visible: lifeTableStepsType.value == "fixedSize" + info: qsTr("Set the ending time for intervals when using Fixed size steps.") } } } diff --git a/inst/qml/SemiParametricSurvivalAnalysis.qml b/inst/qml/SemiParametricSurvivalAnalysis.qml index f49c7b4..03eb50f 100644 --- a/inst/qml/SemiParametricSurvivalAnalysis.qml +++ b/inst/qml/SemiParametricSurvivalAnalysis.qml @@ -25,6 +25,8 @@ import "./qml_components" as SA Form { + info: qsTr("This analysis performs a Cox proportional hazards regression, a statistical method used in survival analysis to examine the relationship between the time until an event occurs (such as death or failure) and one or more predictor variables. It helps you understand how different factors influence the risk or hazard of the event happening at any given time. The Cox model is particularly useful because it can handle censored data (when the event has not occurred for some subjects during the study period) and does not require assumptions about the baseline hazard function.") + VariablesForm { removeInvisibles: true @@ -44,6 +46,7 @@ Form visible: censoringTypeCounting.checked property bool active: censoringTypeCounting.checked onActiveChanged: if (!active && count > 0) itemDoubleClicked(0) + info: qsTr("Select the variable that represents the start time of the observation interval. Only available when Censoring Type is set to Counting.") } AssignedVariablesList @@ -55,6 +58,7 @@ Form visible: censoringTypeCounting.checked property bool active: censoringTypeCounting.checked onActiveChanged: if (!active && count > 0) itemDoubleClicked(0) + info: qsTr("Select the variable that represents the end time of the observation interval. Only available when Censoring Type is set to Counting.") } AssignedVariablesList @@ -66,6 +70,7 @@ Form visible: censoringTypeRight.checked property bool active: censoringTypeRight.checked onActiveChanged: if (!active && count > 0) itemDoubleClicked(0) + info: qsTr("Select the variable that represents the time until the event or censoring occurs. Only available when Censoring Type is set to Right.") } AssignedVariablesList @@ -75,6 +80,7 @@ Form title: qsTr("Event Status") allowedColumns: ["nominal"] singleVariable: true + info: qsTr("Choose the variable that indicates the event status, specifying whether each observation is an event or censored.") } DropDown @@ -83,6 +89,7 @@ Form label: qsTr("Event Indicator") source: [{name: "eventStatus", use: "levels"}] onCountChanged: currentIndex = 1 + info: qsTr("Specify the value in the Event Status variable that indicates the occurrence of the event.") } AssignedVariablesList @@ -90,6 +97,7 @@ Form name: "covariates" title: qsTr("Covariates") allowedColumns: ["scale"] + info: qsTr("Add continuous variables as covariates to include them in the Cox regression model.") } AssignedVariablesList @@ -97,6 +105,7 @@ Form name: "factors" title: qsTr("Factors") allowedColumns: ["nominal"] + info: qsTr("Add categorical variables as factors to include them in the Cox regression model.") } @@ -106,6 +115,7 @@ Form title: qsTr("Weights") allowedColumns: ["scale"] singleVariable: true + info: qsTr("Select a variable for case weights, weighting each observation accordingly in the model.") } } @@ -120,6 +130,7 @@ Form { label: qsTr("Breslow"), value: "breslow"}, { label: qsTr("Exact"), value: "exact"} ] + info: qsTr("Choose the method for handling tied event times: Efron, Breslow, or Exact.") } RadioButtonGroup @@ -130,6 +141,7 @@ Form title: qsTr("Censoring Type") radioButtonsOnSameRow: true columns: 2 + info: qsTr("Select the type of censoring in your data: Right censoring or Counting process.") RadioButton { @@ -166,6 +178,7 @@ Form id: strata title: qsTr("Strata") allowedColumns: ["nominal"] + info: qsTr("Select variables to define strata, allowing separate baseline hazard functions for each stratum.") } // TODO: allow only if multiple outcomes are possible @@ -187,6 +200,7 @@ Form title: qsTr("Cluster") allowedColumns: ["nominal"] singleVariable: true + info: qsTr("Select a variable to define clusters of correlated observations for robust variance estimation. Disabled when a Frailty variable is specified or Method is set to Exact.") } AssignedVariablesList @@ -197,6 +211,7 @@ Form title: qsTr("Frailty") allowedColumns: ["nominal"] singleVariable: true + info: qsTr("Select a variable for frailty to model unobserved heterogeneity using random effects. Disabled when a Cluster variable is specified.") } } @@ -210,6 +225,7 @@ Form name: "frailtyDistribution" id: frailtyDistribution label: qsTr("Distribution") + info: qsTr("Choose the distribution for the frailty term: Gamma, Gaussian, or T distribution. Only available when a Frailty variable is specified.") values: [ { label: qsTr("Gamma"), value: "gamma"}, @@ -223,6 +239,7 @@ Form name: "frailtyMethod" id: frailtyMethod label: qsTr("Method") + info: qsTr("Select the estimation method for the frailty distribution. Options vary based on the chosen Distribution.") values: (function() { if (frailtyDistribution.value == "gamma") { return [ @@ -251,6 +268,7 @@ Form visible: frailtyDistribution.value == "t" name: "frailtyMethodTDf" defaultValue: 5 + info: qsTr("Set the degrees of freedom (Df) for the T frailty distribution. Only visible when Distribution is set to T.") } Group @@ -262,6 +280,7 @@ Form name: "frailtyMethodFixed" id: frailtyMethodFixed label: qsTr("Fix") + info: qsTr("Choose the parameter to fix in the frailty model when Method is set to Fixed: Theta or Df.") values: [ { label: qsTr("Theta"), value: "theta"}, @@ -275,6 +294,7 @@ Form visible: frailtyMethodFixed.value == "theta" name: "frailtyMethodFixedTheta" defaultValue: 0 + info: qsTr("Specify the value of Theta to fix in the frailty model. Only visible when Fix is set to Theta.") } DoubleField @@ -283,6 +303,7 @@ Form visible: frailtyMethodFixed.value == "df" name: "frailtyMethodFixedDf" defaultValue: 0 + info: qsTr("Specify the degrees of freedom (Df) to fix in the frailty model. Only visible when Fix is set to Df.") } } } @@ -323,16 +344,19 @@ Form { name: "modelFit" label: qsTr("Model fit") + info: qsTr("Include overall model fit statistics in the output.") } Group { title: qsTr("Tests") + info: qsTr("Test all parameters of the H₁ model.") CheckBox { name: "testsLikelihoodRatio" label: qsTr("Likelihood ratio") + info: qsTr("Include the Likelihood Ratio Test in the model summary.") } CheckBox @@ -340,6 +364,7 @@ Form name: "testsWald" enabled: frailty.count == 0 label: qsTr("Wald") + info: qsTr("Include the Wald Test in the model summary. Disabled when a Frailty variable is specified.") } CheckBox @@ -347,6 +372,7 @@ Form name: "testsScore" enabled: frailty.count == 0 label: qsTr("Score (log-rank)") + info: qsTr("Include the Score (Log-Rank) Test in the model summary. Disabled when a Frailty variable is specified.") } } } @@ -362,11 +388,13 @@ Form name: "coefficientEstimate" label: qsTr("Estimates") checked: true + info: qsTr("Display the estimated coefficients in the model output.") CheckBox { name: "vovkSellke" label: qsTr("Vovk-Sellke maximum p-ratio") + info: qsTr("Include the Vovk-Sellke maximum p-ratio for each coefficient.") } } @@ -375,12 +403,14 @@ Form name: "coefficientHazardRatioEstimates" label: qsTr("Hazard ratio estimates") checked: true + info: qsTr("Display the hazard ratio estimates (exponentiated coefficients).") CheckBox { name: "coefficientHazardRatioEstimatesIncludeFrailty" label: qsTr("Include frailty") enabled: frailty.count > 0 + info: qsTr("Include the effect of frailty in hazard ratio estimates. Only available when a Frailty variable is specified.") } } @@ -390,10 +420,12 @@ Form label: qsTr("Confidence intervals") checked: true childrenOnSameRow: true + info: qsTr("Include confidence intervals for the coefficients.") CIField { name: "coefficientsConfidenceIntervalsLevel" + info: qsTr("Set the confidence level (e.g., 95%) for the confidence intervals.") } } } @@ -419,18 +451,21 @@ Form { name: "proportionalHazardsTable" label: qsTr("Table") + info: qsTr("Provide a table to test the proportional hazards assumption.") } CheckBox { name: "proportionalHazardsPlot" label: qsTr("Plot") + info: qsTr("Generate plots to assess the proportional hazards assumption.") } DropDown { name: "proportionalHazardsTransformation" label: qsTr("Transformation") + info: qsTr("Select the transformation for time in proportional hazards testing: KM, Rank, or Identity.") values: [ { label: qsTr("KM"), value: "km"}, @@ -443,6 +478,7 @@ Form { name: "proportionalHazardsTestTerms" label: qsTr("Test terms") + info: qsTr("Test the proportional hazards assumption for individual model terms (instead of coefficients).") } } @@ -456,6 +492,7 @@ Form name: "residualPlotResidualVsTime" label: qsTr("Residuals vs. time") enabled: residualPlotResidualType.value == "martingale" || residualPlotResidualType.value == "deviance" + info: qsTr("Plot residuals versus time to detect non-proportional hazards. Available only for Martingale or Deviance residuals.") } CheckBox @@ -463,6 +500,7 @@ Form name: "residualPlotResidualVsPredictors" label: qsTr("Residuals vs. predictors") enabled: selectedModelTerms.count > 0 + info: qsTr("Plot residuals versus predictors to assess model fit. Available when model terms are specified.") } CheckBox @@ -470,6 +508,7 @@ Form name: "residualPlotResidualVsPredicted" label: qsTr("Residuals vs. predicted survival") enabled: residualPlotResidualType.value == "martingale" || residualPlotResidualType.value == "deviance" + info: qsTr("Plot residuals versus predicted survival probabilities. Available only for Martingale or Deviance residuals.") } CheckBox @@ -477,6 +516,7 @@ Form name: "residualPlotResidualHistogram" label: qsTr("Residuals histogram") enabled: residualPlotResidualType.value == "martingale" || residualPlotResidualType.value == "deviance" + info: qsTr("Display a histogram of residuals to assess their distribution. Available only for Martingale or Deviance residuals.") } DropDown @@ -484,6 +524,7 @@ Form name: "residualPlotResidualType" id: residualPlotResidualType label: qsTr("Type") + info: qsTr("Select the type of residuals to plot: Martingale, Deviance, Score, Schoenfeld, or Scaled Schoenfeld.") values: [ { label: qsTr("Martingale"), value: "martingale"}, { label: qsTr("Deviance"), value: "deviance"}, diff --git a/inst/qml/qml_components/SurvivalPlot.qml b/inst/qml/qml_components/SurvivalPlot.qml index e1c0436..6263309 100644 --- a/inst/qml/qml_components/SurvivalPlot.qml +++ b/inst/qml/qml_components/SurvivalPlot.qml @@ -24,11 +24,13 @@ CheckBox { name: "plot" label: qsTr("Plot") + info: qsTr("This option generates a customizable survival plot to visualize the estimated survival probabilities over time from your survival analysis. You can choose different transformations of the survival probabilities to display, such as Survival, Risk, Cumulative Hazard, or Complementary Log-Log functions, depending on your analytical needs. The plot allows you to include confidence intervals to assess the precision of the estimates and add a risk table to provide detailed information about the number of subjects at risk and events over time. You can further enhance the plot by adding quantile lines to highlight specific survival times (e.g., median survival time) and adjust the legend position, color palette, and overall theme to suit your preferences.") DropDown { name: "plotType" label: qsTr("Type") + info: qsTr("Select the type of statistic to plot: Survival, Risk, Cumulative Hazard, or Complementary Log-Log.") values: [ { label: qsTr("Survival"), value: "survival"}, @@ -43,6 +45,7 @@ CheckBox name: "plotCi" label: qsTr("Confidence interval") checked: true + info: qsTr("Include confidence intervals in the survival plot to show the variability around the estimates.") } CheckBox @@ -50,12 +53,14 @@ CheckBox name: "plotRiskTable" label: qsTr("Risk table") checked: false + info: qsTr("Add a risk table below the plot to display additional information about the number of subjects at risk over time.") CheckBox { name: "plotRiskTableNumberAtRisk" label: qsTr("Number at risk") checked: true + info: qsTr("Display the number of subjects at risk at each time point in the risk table.") } CheckBox @@ -63,30 +68,35 @@ CheckBox name: "plotRiskTableCumulativeNumberOfObservedEvents" label: qsTr("Cum. number of observed events") checked: true + info: qsTr("Display the cumulative number of observed events (e.g., deaths) at each time point in the risk table.") } CheckBox { name: "plotRiskTableCumulativeNumberOfCensoredObservations" label: qsTr("Cum. number of censored obs.") + info: qsTr("Display the cumulative number of censored observations at each time point in the risk table.") } CheckBox { name: "plotRiskTableNumberOfEventsInTimeInterval" label: qsTr("Number of events in time interval") + info: qsTr("Display the number of events that occurred within each time interval in the risk table.") } CheckBox { name: "plotRiskTableNumberOfCensoredObservationsInTimeInterval" label: qsTr("Number of censored obs. in time interval") + info: qsTr("Display the number of censored observations within each time interval in the risk table.") } CheckBox { name: "plotRiskTableAsASingleLine" label: qsTr("As a single line") + info: qsTr("Combine all selected risk table statistics into a single line for a more compact display.") } } @@ -96,6 +106,7 @@ CheckBox label: qsTr("Add quantile") checked: false childrenOnSameRow: true + info: qsTr("Add a vertical line on the plot at a specified quantile (e.g., median survival time).") DoubleField { @@ -103,6 +114,7 @@ CheckBox defaultValue: 0.5 min: 0 max: 1 + info: qsTr("Specify the quantile value (between 0 and 1) at which to add the vertical line on the plot.") } } @@ -112,6 +124,7 @@ CheckBox name: "plotLegend" enabled: strata.count > 0 label: qsTr("Legend") + info: qsTr("Choose the position of the legend on the plot: Bottom, Right, Left, Top, or None. Only available when Strata variables are specified.") values: [ { label: qsTr("Bottom"), value: "bottom"}, @@ -125,12 +138,14 @@ CheckBox ColorPalette { enabled: strata.count > 0 + info: qsTr("Customize the color palette used in the plot. Only available when Strata variables are specified.") } DropDown { name: "plotTheme" label: qsTr("Theme") + info: qsTr("Select the theme for the plot's appearance: JASP for the default look or ggsurvfit for the ggsurvfit package style.") values: [ { label: qsTr("JASP"), value: "jasp"},