Survival analysis in MATLAB.zip

# MatSurv [](https://www.mathworks.com/matlabcentral/fileexchange/64582-matsurv) [](https://doi.org/10.21105/joss.01830) MatSurv is a simple survival analysis function for MATLAB (version 2016b and later) that creates a KM plot with risk table. Survival statistics, such as log-rank p-value and hazard ratio (HR) are also calculated. The log-rank test has been evaluated to give the same results as SAS and R. The style of the KM plot is easily changed with input parameters. No additional toolboxes are needed or depended upon. MatSurv was inspired by the [survminer R-package](https://github.com/kassambara/survminer). The general usage is: ```matlab [p, fh, stats] = MatSurv(TimeVar, EventVar, GroupVar, 'param', value, …) ``` ## Table of contents ## - [Why MatSurv](#Why-MatSurv) - [Citing MatSurv](#Citing-MatSurv) - [MATLAB Release Compatibility](#MATLAB-Release-Compatibility) - [Recent Improvements](#Recent-Improvements) - [Simple Example](#Simple-Example) - [Using MatSurv](#Using-Matsurv) - [More Examples](#More-Examples) - [Unit Test](#Unit-Test) - [List of all input options](#List-of-all-input-options) ## Why Matsurv ## MatSurv allows MATLAB users to create KM-plots with a risk table and also to perform a log-rank test between two or more groups. An event is, for example, death, relapse of disease, or a new metastatic tumor. If none of these events occur during the study period, the time-to-event is unknown, this point is called censored. A risk table describe the number of patients that are still “at-risk” at a specific timepoint. MatSurv also provides a fine grained customization of the KM-plots, making it suitable for publications. MatSurv hopefully will make the life easier for fellow Bioinformaticians (and other professionals) who prefer MATLAB over R. ## Citing MatSurv ## Creed et al., (2020). MatSurv: Survival analysis and visualization in MATLAB. Journal of Open Source Software, 5(46), 1830, https://doi.org/10.21105/joss.01830 ## MATLAB Release Compatibility ## Compatible with R2016b to R2019b ## Recent Improvements ## 2022-02-17 : Added options to use all four quartile groups, use `'CutPoint','QuartileAll ` 2020-04-08 : Added logrank test for trend, use `'LogRankTrend',true ` ## Simple Example ## The following code loads the data from "Freireich, EJ et al. 1963, Blood, 21, 699-716)" and creates a KM plot with risk table. The time unit is weeks and the x-axis step length is changed to 4. The risk table shows how many are at risk (alive) for each time point. Censored points are marked with a vertical line. ```matlab [p,fh,stats]=MatSurv([], [], [],'Xstep',4); ``` <img src="/figures/Example_01.png" alt="MatSurv example" width="600"> ## Using MatSurv ## ### Installation ### Simply put MatSurv.m in any directory of your choice and make sure it is added to your path. ### Usage ### MatSurv(TimeVar, EventVar, GroupVar,'param', value, ...) creates a Kaplan-Meier plot with a risk table and calculates a log-rank p-value. [p] = MatSurv( ... ) returns the log-rank p-value [p, fh] = MatSurv( ... ) returns both p-value and figure handle [p, fh, stats] = MatSurv( ... ) returns additions stats from the log-rank test [p, fh, stats] = MatSurv([], [], [], ... ) loads a test dataset from "Freireich, EJ et al. 1963, Blood, 21, 699-716" INPUTS: * `TimeVar` is a vector with numeric time to event, either observed or censored. Values equal or less than zero will be removed by default * `EventVar` is a vector or cell array defining events or censored observations. Events are defined with a 1 and censored point with a 0. By default 'Dead', 'Deceased', 'Relapsed', 'Yes' are considered as events. 'Alive', 'Living', 'Not Relapsed', 'DiseaseFree', 'No' are considered as censored. 'EventDefinition' can be used to define other types of events. * `GroupVar` is a vector or cell array defining the different groups. if `GroupVar` is a numeric vector, median-cut will be used as a default. OUTPUTS: * p : Log-rank p-value * fh : Figure handle for KM plot figure * stats : Structure with additional statistics in the following fields: ```matlab struct with fields: GroupNames: Cell with group names p_MC: log rank p-value (Mantel-Cox) Chi2_MC: Chi square (Mantel-Cox) HR_logrank: Hazard Ratio (log rank) HR_95_CI_logrank: 95 percentile Confidence Intervals [lower upper] HR_logrank_Inv: Inverted Hazard Ratio (log rank) HR_95_CI_logrank_Inv: Inverted 95 percentile Confidence Intervals [lower upper] HR_MH: Hazard Ratio (Mantel-Haenszel) HR_95_CI_MH: 95 percentile Confidence Intervals [lower upper] HR_MH_Inv: Inverted Hazard Ratio (Mantel-Haenszel) HR_95_CI_MH_Inv: Inverted 95 percentile Confidence Intervals [lower upper] MedianSurvivalTime: Median survival time for each group ``` ## More Examples ## ### Additional options ### Below are some examples for how to create different styles of KM plots and also how one can make changes using the figure handle. In the example below, we show how we can change some of the properties of the KM plot via various name-value pair arguments. ```matlab [p,fh,stats]=MatSurv([],[],[],'Xstep',4,... 'TitleOptions',{'Color','r','Interpreter','none'},'InvHR',1,... 'Xlim',32,'XMinorTick',3,'LineColor',[0 0 1;1 0 1],'LineStyle',{'-',':'},... 'LineWidth',3,'CensorLineColor','k','RT_KMplot',1); ``` <img src="/figures/Example_02.png" alt="MatSurv example" width="600"> ### Example with multiple groups ### This example is taken from the TCGA laml data set. Obtaining the data from cBioPortal can be found in the MatSurv/Article/MATLAB/get_laml_RC_data.m script. The samples are diveded into three groups based on their Cyto score. It is clear from the KM-Plot below that these groups have different outcomes. For this example we will load the data directly. ```matlab load laml_RC_data.mat [p,fh,stats]=MatSurv(laml_RC_TimeVar, laml_RC_EventVar, laml_RC_GroupVar,... 'GroupsToUse', {'Good','Intermediate','Poor'},'Xstep',24); ``` <img src="/figures/laml_Risk_Cyto.png" alt="Multiple groups MatSurv example" width="600"> ### Example with merging groups ### Groups can be merged using a multilevel cell as GroupToUse input This example will merge the poor and N.D group. The first element in the cell array will define the name of the merged group and can either be the name of an existing group or a new group name. ```matlab load laml_RC_data.mat [p,fh,stats]=MatSurv(laml_RC_TimeVar, laml_RC_EventVar, laml_RC_GroupVar,... 'GroupsToUse', {'Good','Intermediate',{'Poor + N.D.','Poor','N.D.'}},'Xstep',24); ``` <img src="/figures/laml_Risk_Cyto_Merged.png" alt="Multiple merged groups MatSurv example" width="600"> ### Example with gene expression data ### This example is also taken from the TCGA LAML dataset but we in this example we will be using RNAseq gene expression data for the hepatocyte growth factor (HGF) gene. HGF gene expression has been related to outcome in a variety of cancers, including of the lungs, pancreas, thyroid, colon, and breast. Obtaining the data from cBioPortal can be found in the MatSurv/Article/MATLAB/get_laml_HGF_gene_data.m script. The expression level of a gene is continues and if no prior knowledge is available, the median is frequqently used to divide the samples into two groups, see the first graph below. Using the top 25% and bottom 25%, quartiles, is also frequently used, see the second graph below. Finally, if one or several cut-points level are known, these can also be used, third graph below. For this example we will load the data directly. ```matlab load laml_HGF_gene_data.mat % Using median cut [p,fh,stats]=MatSurv(laml_HGF_gene_TimeVar,laml_HGF_gene_EventVar