SurvivalAnalysisRoutine

Versions

1.0.0

v1.0.0

Basic Information

Class Name: SurvivalAnalysisRoutine

Title: Survival Analysis

Version: 1.0.0

Author: Benjamin Fitzgerald, Jon Tuazon

Organization: OneStream

Creation Date: 2025-07-08

Default Routine Memory Capacity: 2.0 GB

Description

Short Description

Perform survival analysis on a dataset.

Long Description

This routine performs survival analysis on a dataset, allowing for the examination of time-to-event data. It can be used to analyze customer survival times and the impact of various features on survival. The routine will analyze the time it takes for an entity (e.g., patient, customer) to make a payment after receiving a service or product, or the time it takes for an entity to convert from one treatment pipeline to another. It will also flag risky entities based on their risk scores. Using survival analysis, this routine can help identify trends in both payment behavior and the factors that influence timely payments.

Use Cases

1. Time to Payment

Analyze the time it takes for an entity (e.g., patient, customer) to make a payment after receiving a service or product. This routine can help identify trends in both payment behavior and the factors that influence timely payments. Features that the user can choose to analyze may impact time to payment behaviors. This routine can also assist in identifying trends in payment behaviors, which can inform financial decision-making and improve cash flow management. This capability is essential for organizations to optimize their billing processes and enhance customer satisfaction.

2. Pipeline Conversion

Analyze the time it takes for an entity (e.g., lead, customer, employee) to transition from one business pipeline stage to another. For example, in sales operations, this could involve measuring how long it takes for a prospect to move from initial contact to closed deal. In customer onboarding, it could involve tracking the time it takes for a client to convert from signed contract to active usage of the product. In recruitment, it could examine the duration from candidate application to final hire. This analysis can uncover influential factors that affect transition speed, such as lead quality, team responsiveness, product complexity, and organizational workflows.

Routine Methods

1. Init (Constructor)

Method: __init__
- Type: Constructor
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: No
- Method Limits: N/A
- Outputs Dynamic Artifacts: No
- Short Description:
  - Initialize the Survival Analysis Routine.
- Detailed Description:
  - This constructor currently performs minimal setup. Core parameters are handled in the fit method.
- Inputs:
  - No input parameters
- Artifacts: No artifacts are returned by this method

2. Fit (Method)

Method: fit
- Type: Method
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: No
- Method Limits: This method was tested with a dataset of 10K rows with 6 covariates (3 numerical and 3 categorical) and completed in 2 hours and 55 minutes with 100GB of memory.
- Outputs Dynamic Artifacts: No
- Short Description:
  - Generate a report to help the user better understand the dataset.
- Detailed Description:
  - This routine performs survival analysis on a dataset, allowing for the examination of time-to-event data. It can be used to analyse use cases such as time to payment or pipelines conversion. It will analyse the time it takes for an entity (e.g., patient, customer) to make a payment after receiving a service or product, or the time it takes for a patient to convert from one treatment pipeline to another. It will also flag risky entities based on their risk scores. Using survival analysis, this routine can help identify trends in both payment behavior and the factors that influence timely payments.
- Inputs:
  - Required Input
    - Source Data Definition: Select the data source connection for training the survival analysis routine.
      - Name: data_connection
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: TabularConnection
    - Event Column: Select the column that indicates the event occurrence (e.g., payment, conversion).The event column should contain binary values indicating whether the event occurred (1) or not (0).
      - Name: event_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Time-to-Event Column: Select the column that indicates the time-to-event (e.g., time until payment, time until conversion).The time column should contain numerical values representing the time until the event occurred.
      - Name: time_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Numerical Features: Select numerical features for the survival model. WARNING: Training and prediction must use the same features. Prediction may include extras, but not fewer.
      - Name: numerical_features
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: list[str]
    - Categorical Features: Select categorical features for the survival model. WARNING: Training and prediction must use the same features. Prediction may include extras, but not fewer.
      - Name: categorical_features
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: list[str]
    - Unit Settings: Set time unit (days, weeks, months, years) according to the dataset for the routine.
      - Name: unit_settings
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Hyperparameter Tuning: Full: for best quality (slowest). Quick: for great quality, faster tuning (normal). Off: less accurate, fastest (quick).
      - Name: hyperparameter_tuning
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Models to Exclude: Exclude models from training and selection. Leave empty to train all candidates.
      - Name: models_to_exclude
      - Tooltip:
        
        Detail:
        
        RandomSurvivalForest and GradientBoostingSurvivalAnalysis support SHAP explanations. CoxPHSurvivalAnalysis does not (Permutation Importance only). Exclude non-SHAP models to guarantee SHAP explainability for the winning model.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: list[str]
    - Show Model Performance Plot: Include the Time-Dependent AUC model-performance plot and its 'versus random' benchmark. Turn off for deployments where benchmarking against randomness is not meaningful.
      - Name: show_model_performance
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: bool
    - Show Best Model Performance Panel: Show the 'Best Model Performance' panel (best model, Arena Score, performance scale) on the Model Summary page. Turn off to hide it for deployments where it is not needed.
      - Name: show_best_model_performance
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: bool
    - SHAP Explanation Target: Produce SHAP explanations for Risk Score, Survival Probability, Both, or Off.
      - Name: shap_explanation_target
      - Tooltip:
        
        Detail:
        
        SHAP is only available when a tree-based model wins; Cox falls back to Permutation Importance. Use Models to Exclude to prevent a non-SHAP model from winning.
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Decimal Places: How many decimal places the web app shows for Summary Table cells and every chart's axis/hover values. Choose Full Precision or 1-8. The stored data and downloaded CSV always keep full precision.
      - Name: decimal_places
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Probability Display: Whether the web app shows Survival Probability S(t) or Event Probability 1 - S(t) across the Summary Table, the time-to-threshold view, and the Survival Function plot.
      - Name: survival_display_mode
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
- Artifacts:
  - Survival Analysis Web Dashboard: A Web Dashboard with the results of the Survival Analysis routine.
    - Qualified Key Annotation: web_app
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@web_app/data_/data.appref
        
        json file of data relating to web app
  - Parameters: Parameters used to generate the Survival Analysis Web Dashboard.
    - Qualified Key Annotation: web_app_params
    - Aggregate Artifact: False
    - In-Memory Json Accessible: True
    - File Annotations:
      - artifacts_/@web_app_params/data_/data.json
        
        Stored json data. The schema is not known until runtime.

3. Predict (Method)

Method: predict
- Type: Method
- Memory Capacity: 2.0 GB
- Allow In-Memory Execution: No
- Read Only: No
- Method Limits: This method was tested with a dataset of 1M rows with 6 covariates (3 numerical and 3 categorical) and completed in roughly 4 minutes with 100GB of memory. At the moment, using larger datasets may lead to memory issues.
- Outputs Dynamic Artifacts: No
- Short Description:
  - Generate a web app artifact for survival analysis predictions.
- Detailed Description:
  - This method uses the best model from the survival analysis routine to make predictions on the test set. The user will input the predict data, and the method will generate a summary dataframe flagging high risk scores, survival and cumulative hazard quantile curves, and a permutation feature importance plot.
- Inputs:
  - Required Input
    - Source Data Definition: Select the data source connection for the survival analysis prediction.
      - Name: data_connection
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: TabularConnection
    - Unique Identifier Column: Select the column to be used as the unique identifier for each observation.If no unique identifier is available, select Auto ID (use row index as the unique identifier).
      - Name: unique_id_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Prediction Horizon: Set the prediction horizon for the survival analysis model. This defines how far into the future the model will predict survival probabilities.
      - Name: prediction_horizon
      - Tooltip:
        
        Validation Constraints:
        
        The input must be greater than or equal to 1.
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
    - Prediction Interval: Set the prediction interval for the survival analysis model. This defines the time interval for which the model will provide survival probabilities.
      - Name: prediction_interval
      - Tooltip:
        
        Validation Constraints:
        
        The input must be greater than or equal to 1.
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
    - Flag High Risk Observations: Flag high-risk observations and add the High Risk Flag column. Turn on to configure how high risk is determined on the next page. Observations with no risk score are never flagged.
      - Name: enable_high_risk_flag
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: bool
    - Analyze Model Performance Drift: Measure how the model's discrimination (C-index and fixed-horizon AUC) changes across calendar periods. Turn on to pick the calendar date and ground-truth event/time columns on a later page.
      - Name: enable_drift_analysis
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: bool
    - High Risk Threshold Type: Choose how high risk is determined: by standard deviations above the mean risk score, or by survival probability at a chosen horizon falling to/below a threshold.
      - Name: high_risk_threshold_type
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Standard Deviations Above Mean: Flag observations whose risk score is at least this many standard deviations above the mean. Enter a number greater than 0 (decimals allowed).
      - Name: high_risk_std_threshold
      - Tooltip:
        
        Validation Constraints:
        
        The input must be greater than 0.
        
        This input may be subject to other validation constraints at runtime.
      - Type: float
    - Survival Probability Threshold: Flag observations whose survival probability at the chosen horizon falls to/below this value. Enter a value between 0 and 1 (exclusive).
      - Name: high_risk_probability_threshold
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: float
    - Survival Probability Horizon: The horizon at which the survival probability is checked against the threshold. Options are derived from the prediction horizon and interval entered on the setup page.
      - Name: high_risk_probability_horizon
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: int
    - Calendar Date Column: Select the calendar date/datetime column used to bucket observations into periods. Rows whose date cannot be parsed are skipped.
      - Name: period_date_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Calendar Granularity: Calendar granularity used to bucket observations (Month, Quarter, or Year).
      - Name: drift_granularity
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Ground-Truth Event Column: Select the ground-truth event indicator column (1 = event occurred, 0 = censored) used to measure the model's performance per period.
      - Name: drift_event_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Ground-Truth Time-to-Event Column: Select the ground-truth time-to-event column used to measure the model's performance per period.
      - Name: drift_time_column
      - Tooltip:
        
        Validation Constraints:
        
        This input may be subject to other validation constraints at runtime.
      - Type: str
    - Fixed AUC Horizon: The fixed horizon at which the per-period AUC is evaluated. Leave blank to default to the prediction horizon entered on the setup page.
      - Name: drift_auc_horizon
      - Tooltip:
        
        Validation Constraints:
        
        The input must be greater than or equal to 1.
        
        This input may be subject to other validation constraints at runtime.
      - Type: Optional[int]
- Artifacts:
  - Survival Analysis Web Dashboard: A Web Dashboard with the results of the Survival Analysis routine.
    - Qualified Key Annotation: web_app
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@web_app/data_/data.appref
        
        json file of data relating to web app
  - Parameters: Parameters used to generate the Survival Analysis Web Dashboard.
    - Qualified Key Annotation: web_app_params
    - Aggregate Artifact: False
    - In-Memory Json Accessible: True
    - File Annotations:
      - artifacts_/@web_app_params/data_/data.json
        
        Stored json data. The schema is not known until runtime.
  - Summary Table: Table of risk scores, survival probabilities at selected time horizons, and high-risk flags per entity.
    - Qualified Key Annotation: summary_df
    - Aggregate Artifact: False
    - In-Memory Json Accessible: False
    - File Annotations:
      - artifacts_/@summary_df/data_/data_<int>.parquet
        
        A partitioned set of parquet files where each file will have no more than 1000000 rows.

Interface Definitions

No interface definitions found for this routine

Developer Docs

Routine Typename: SurvivalAnalysisRoutine

Method Name	Artifact Keys
`__init__`	N/A
`fit`	web_app, web_app_params
`predict`	web_app, web_app_params, summary_df

Versions​

v1.0.0​

Basic Information​

Tags​

Description​

Short Description​

Long Description​

Use Cases​

1. Time to Payment​

2. Pipeline Conversion​

Routine Methods​

1. Init (Constructor)​

2. Fit (Method)​

3. Predict (Method)​

Interface Definitions​

Developer Docs​