| Label | Explanation | Data Type |
Input Features or Table
| The input features or table containing fields of the age, explanatory variables, and event indicator for each observation. | Table View |
Age Field
| The numeric field of the age of the observation. This is often the age of the observation, but in general, it is the amount of time starting from the first moment the event could have occurred and ending when the event occurred (or ending when the observation was censored). The unit of the age (hours, days, years, and so on) is not provided, but all results should be interpreted in that time unit. For example, if the age values are in days, and the tool predicts an event time two time units in the future, this means two days in the future. | Field |
Event Indicator Field
| The field containing an indicator or whether the event has occurred for the observation. The field must only contain the values 0 or 1. A value of 0 indicates that the event has not occurred (a censored observation), and a value of 1 indicates that the event has occurred (an uncensored observation). For example, to estimate the lifespan of trees, a value of 0 means that the tree is alive (the event, tree death, has not occurred), and a value of 1 means that the tree is dead. | Field |
Output Features or Table
| The output features or table containing the predicted times to the event for observations in which the event has not occurred. | Feature Class; Table |
Explanatory Variables
(Optional) | A list of fields representing the explanatory variables that help predict the time to the event. Check the Categorical check box for variables that represent classes or categories such as material type or income bracket. Leave the check box unchecked for variables that are continuous. | Value Table |
Enable Survival Curve Pop-ups (Optional) | Specifies whether pop-up charts will be generated for each output record. The pop-up charts show the baseline survival curve for each record and an additional time-to-event curve for censored observations.
| Boolean |
Summary
Predicts the time until an event occurs based on the prior times to the event. Explanatory variables can be used to improve the predictions, and the tool can determine which variables increase or decrease the time until the event.
Illustration
Usage
Each observation in the input features or table must have fields containing the age of the observation, an indicator of whether the event has already occurred, and any explanatory variables. These fields are provided in the Age Field, Event Indicator Field, and Explanatory Variables parameters, respectively. The explanatory variables can be continuous or categorical, and the event indicator must only take the values 0 (the event has not occurred) or 1 (the event has occurred). For the age field, this will often be the actual age of the individual, but in general, it is the amount of time starting from the first possible time the event could have occurred and ending at the time the event occurred (or the current time, if the event has not occurred). For example, to estimate the lifespan of trees, the age field values should be the current age of the tree if it is alive or the age of the tree when it died. However, for estimating time to re-arrest, the field values should be the amount of time since the individual was released from custody (the first time a re-arrest could occur) until the time of re-arrest (or the current date if the individual has not been re-arrested). The unit of the age (hours, days, years, and so on) does not need to be provided, but all results should be interpreted in that time unit.
Predicting when an event will happen in the future is an inherently difficult task, so you are encouraged to keep realistic expectations. The tool can only extract information from the explanatory variables that you provide, but complex phenomena like infrastructure breakdown involve numerous factors that are often highly local and specific to each individual. In practice, you should usually treat the predicted times to the event as general indications of when the event might occur, rather than highly specific predictions of particular dates. You should also be particularly cautious and skeptical when extrapolating to times beyond the largest event time of the input data. Though often imprecise, the results of time-to-event analysis can still be very useful for providing general estimates of future costs or for prioritization and allocation of resources to observations most likely to next experience the event.
Time-to-event models are not inherently spatial, but incorporating spatial information may improve the model by accounting for geographic patterns. Consider adding spatial explanatory variables such as geographic regions as categorical explanatory variables or distances to key features as continuous explanatory variables. For example, in modeling urban tree mortality, distance to the nearest building could be important due to reduced sunlight from building shadows.
Observations in which the event has not yet occurred are called censored observations, and observations in which the event has occurred are called uncensored observations. This terminology comes from the fact that uncensored observations have complete information (the time to the event is known), but censored observations only have partial information; the exact time to the event is not known, but it is known to be longer than some amount of time (the current age of the observation).
While the estimation of the model parameters uses both censored and uncensored observations, uncensored observations provide the most information because their exact survival time is known. In general, it is recommended to have at least 10 uncensored observations per explanatory variable. However, categorical variables should be counted as multiple variables. A categorical variable with two categories counts as one variable; three categories counts as two variables; four categories counts as three variables; and so on. Additionally, every category should have several uncensored observations to best estimate the effect of all categories of the categorical variable.
The tool produces a variety of outputs, numerical and graphical, to understand how the explanatory variables affect the time to the event, to predict when the event will occur, and to assess the accuracy and reliability of the model.
The geoprocessing messages summarize the effects of the explanatory variables and the accuracy of the model. The output feature class or table includes fields and pop-up charts estimating when the event is predicted to occur for uncensored observations.
Learn more about the outputs of the tool and how to interpret them
Parameters
arcpy.stats.EstimateTimeToEvent(in_features, age_field, event_field, out_features, {explanatory_variables}, {enable_survival_curve_popups})| Name | Explanation | Data Type |
in_features | The input features or table containing fields of the age, explanatory variables, and event indicator for each observation. | Table View |
age_field | The numeric field of the age of the observation. This is often the age of the observation, but in general, it is the amount of time starting from the first moment the event could have occurred and ending when the event occurred (or ending when the observation was censored). The unit of the age (hours, days, years, and so on) is not provided, but all results should be interpreted in that time unit. For example, if the age values are in days, and the tool predicts an event time two time units in the future, this means two days in the future. | Field |
event_field | The field containing an indicator or whether the event has occurred for the observation. The field must only contain the values 0 or 1. A value of 0 indicates that the event has not occurred (a censored observation), and a value of 1 indicates that the event has occurred (an uncensored observation). For example, to estimate the lifespan of trees, a value of 0 means that the tree is alive (the event, tree death, has not occurred), and a value of 1 means that the tree is dead. | Field |
out_features | The output features or table containing the predicted times to the event for observations in which the event has not occurred. | Feature Class; Table |
explanatory_variables [[Variable, Categorical],...] (Optional) | A list of fields representing the explanatory variables that help predict the time to the event. Specify the variable as CATEGORICAL if it represents classes or categories such as material type or income bracket, and specify NUMERIC if it is continuous. | Value Table |
enable_survival_curve_popups (Optional) | Specifies whether pop-up charts will be generated for each output record. The pop-up charts show the baseline survival curve for each record and an additional time-to-event curve for censored observations.
| Boolean |
Code sample
The following Python window script demonstrates how to use the EstimateTimeToEvent function.
# Estimate the time until an event.
import arcpy
arcpy.env.workspace = r"c:\data\project_data.gdb"
arcpy.stats.EstimateTimeToEvent(
in_features = r"myFeatureClass",
age_field = "myAgeField",
event_field = "myEventField",
out_features = r"myOutputFeatureClass",
explanatory_variables = r"cont_var1 false;cont_var2 false;cat_var1 true;cat_var2 true",
enable_survival_curve_popups = "CREATE_POPUP"
)The following stand-alone script demonstrates how to use the EstimateTimeToEvent function.
# Estimate the time until an event.
import arcpy
# Set the current workspace.
arcpy.env.workspace = r"c:\data\project_data.gdb"
# Run tool
arcpy.stats.EstimateTimeToEvent(
in_features = r"myFeatureClass",
age_field = "myAgeField",
event_field = "myEventField",
out_features = r"myOutputFeatureClass",
explanatory_variables = r"cont_var1 false;cont_var2 false;cat_var1 true;cat_var2 true",
enable_survival_curve_popups = "CREATE_POPUP"
)
# Print the messages.
print(arcpy.GetMessages())Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes