Introduction to Rcatch22

library(Rcatch22)

Rcatch22 is an R package for the calculation of 22 CAnonical Time-series CHaracteristics (catch). The package is an efficient implementation that calculates time-series features coded in C.

Core calculation function

The main function of the package is catch22_all which automates the computation of the 22 features. This can be run in a one-liner:

data <- rnorm(100)
outs <- catch22_all(data)

Taking a look at the returned dataframe, we can see a nice tidy data structure:

outs
##                                           names     values
## 1                            DN_HistogramMode_5  0.7265508
## 2                           DN_HistogramMode_10  0.9688692
## 3                 DN_OutlierInclude_p_001_mdrmd  0.1600000
## 4                 DN_OutlierInclude_n_001_mdrmd  0.0900000
## 5       CO_FirstCrossing_acf_1e_pointOfCrossing  0.7575219
## 6                                CO_FirstMin_ac  2.0000000
## 7                     SP_Summaries_fft_area_5_1  0.2573182
## 8                        SP_Summaries_fft_wq_50  1.2762720
## 9                     FC_LocalSimple_mean3_stde  1.1463080
## 10                  FC_LocalSimple_mean1_taurat  0.3677143
## 11                                 MD_pNN_pnn40  0.9797980
## 12             SB_BinaryStats_mean_longstretch1  9.0000000
## 13             SB_BinaryStats_diff_longstretch0  3.0000000
## 14                    SB_MotifThree_quantile_hh  2.1974876
## 15               CO_HistogramAMI_even_5bin_ami2  0.0848739
## 16                                CO_trev_1_num -0.2719364
## 17      IN_AutoMutualInfoStats_40_gaussian_fmmi  3.0000000
## 18 SB_TransitionMatrix_quantile_3_ac_sumdiagcov  0.0040261
## 19                    PD_PeriodicityWang_th0_01  6.0000000
## 20         CO_Embed2_Dist_tau_d_expfit_meandiff  0.1689918
## 21  SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1  0.4285714
## 22       SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1  0.4285714

catch24

An option to include the mean and standard deviation as features in addition to catch22 is available through setting the catch24 argument to TRUE:

outs2 <- catch22_all(data, catch24 = TRUE)
outs2
##                                           names      values
## 1                            DN_HistogramMode_5  0.72655081
## 2                           DN_HistogramMode_10  0.96886921
## 3                 DN_OutlierInclude_p_001_mdrmd  0.16000000
## 4                 DN_OutlierInclude_n_001_mdrmd  0.09000000
## 5       CO_FirstCrossing_acf_1e_pointOfCrossing  0.75752185
## 6                                CO_FirstMin_ac  2.00000000
## 7                     SP_Summaries_fft_area_5_1  0.25731817
## 8                        SP_Summaries_fft_wq_50  1.27627202
## 9                     FC_LocalSimple_mean3_stde  1.14630803
## 10                  FC_LocalSimple_mean1_taurat  0.36771431
## 11                                 MD_pNN_pnn40  0.97979798
## 12             SB_BinaryStats_mean_longstretch1  9.00000000
## 13             SB_BinaryStats_diff_longstretch0  3.00000000
## 14                    SB_MotifThree_quantile_hh  2.19748760
## 15               CO_HistogramAMI_even_5bin_ami2  0.08487390
## 16                                CO_trev_1_num -0.27193635
## 17      IN_AutoMutualInfoStats_40_gaussian_fmmi  3.00000000
## 18 SB_TransitionMatrix_quantile_3_ac_sumdiagcov  0.00402610
## 19                    PD_PeriodicityWang_th0_01  6.00000000
## 20         CO_Embed2_Dist_tau_d_expfit_meandiff  0.16899180
## 21  SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1  0.42857143
## 22       SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1  0.42857143
## 23                                      DN_mean -0.02378017
## 24                                DN_Spread_std  0.94305958

Feature list

A list of the time-series features included in Rcatch22 can be viewed using the included feature_list vector:

Rcatch22::feature_list
##  [1] "DN_HistogramMode_5"                          
##  [2] "DN_HistogramMode_10"                         
##  [3] "DN_OutlierInclude_p_001_mdrmd"               
##  [4] "DN_OutlierInclude_n_001_mdrmd"               
##  [5] "CO_FirstCrossing_acf_1e_pointOfCrossing"     
##  [6] "CO_FirstMin_ac"                              
##  [7] "SP_Summaries_fft_area_5_1"                   
##  [8] "SP_Summaries_fft_wq_50"                      
##  [9] "FC_LocalSimple_mean3_stde"                   
## [10] "FC_LocalSimple_mean1_taurat"                 
## [11] "MD_pNN_pnn40"                                
## [12] "SB_BinaryStats_mean_longstretch1"            
## [13] "SB_BinaryStats_diff_longstretch0"            
## [14] "SB_MotifThree_quantile_hh"                   
## [15] "CO_HistogramAMI_even_5bin_ami2"              
## [16] "CO_trev_1_num"                               
## [17] "IN_AutoMutualInfoStats_40_gaussian_fmmi"     
## [18] "SB_TransitionMatrix_quantile_3_ac_sumdiagcov"
## [19] "PD_PeriodicityWang_th0_01"                   
## [20] "CO_Embed2_Dist_tau_d_expfit_meandiff"        
## [21] "SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1" 
## [22] "SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1"

Since version 1.0.0 (catch22 v1.0), every feature exactly reproduces a feature of hctsa v3.0.0, so values differ from earlier versions for most features. Several features were renamed to their hctsa names; the old names still work as deprecated aliases. catch22_feature_table lists each feature’s name, short name, name before version 1.0.0 (legacy_name), and the hctsa call that reproduces it (on x_z, the z-scored time series, or x, the raw time series):

catch22_feature_table(catch24 = TRUE)
##                                            name          short_name
## 1                            DN_HistogramMode_5              mode_5
## 2                           DN_HistogramMode_10             mode_10
## 3                 DN_OutlierInclude_p_001_mdrmd  outlier_timing_pos
## 4                 DN_OutlierInclude_n_001_mdrmd  outlier_timing_neg
## 5       CO_FirstCrossing_acf_1e_pointOfCrossing       acf_timescale
## 6                                CO_FirstMin_ac       acf_first_min
## 7                     SP_Summaries_fft_area_5_1      low_freq_power
## 8                        SP_Summaries_fft_wq_50         median_freq
## 9                     FC_LocalSimple_mean3_stde      forecast_error
## 10                  FC_LocalSimple_mean1_taurat    whiten_timescale
## 11                                 MD_pNN_pnn40    high_fluctuation
## 12             SB_BinaryStats_mean_longstretch1        stretch_high
## 13             SB_BinaryStats_diff_longstretch0  stretch_decreasing
## 14                    SB_MotifThree_quantile_hh       entropy_pairs
## 15               CO_HistogramAMI_even_5bin_ami2                ami2
## 16                                CO_trev_1_num                trev
## 17      IN_AutoMutualInfoStats_40_gaussian_fmmi       ami_timescale
## 18 SB_TransitionMatrix_quantile_3_ac_sumdiagcov transition_variance
## 19                    PD_PeriodicityWang_th0_01         periodicity
## 20         CO_Embed2_Dist_tau_d_expfit_meandiff      embedding_dist
## 21  SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1            rs_range
## 22       SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1                 dfa
## 23                                      DN_mean                mean
## 24                                DN_Spread_std                 std
##                                    legacy_name
## 1                           DN_HistogramMode_5
## 2                          DN_HistogramMode_10
## 3                DN_OutlierInclude_p_001_mdrmd
## 4                DN_OutlierInclude_n_001_mdrmd
## 5                                    CO_f1ecac
## 6                               CO_FirstMin_ac
## 7             SP_Summaries_welch_rect_area_5_1
## 8             SP_Summaries_welch_rect_centroid
## 9                  FC_LocalSimple_mean3_stderr
## 10              FC_LocalSimple_mean1_tauresrat
## 11                        MD_hrv_classic_pnn40
## 12            SB_BinaryStats_mean_longstretch1
## 13            SB_BinaryStats_diff_longstretch0
## 14                   SB_MotifThree_quantile_hh
## 15                    CO_HistogramAMI_even_2_5
## 16                               CO_trev_1_num
## 17     IN_AutoMutualInfoStats_40_gaussian_fmmi
## 18          SB_TransitionMatrix_3ac_sumdiagcov
## 19                   PD_PeriodicityWang_th0_01
## 20        CO_Embed2_Dist_tau_d_expfit_meandiff
## 21 SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1
## 22      SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1
## 23                                     DN_Mean
## 24                               DN_Spread_Std
##                                                    hctsa_call
## 1                          DN_HistogramMode(x_z,5,true,false)
## 2                         DN_HistogramMode(x_z,10,true,false)
## 3                     DN_OutlierInclude(x_z,'pos',0.01).mdrmd
## 4                     DN_OutlierInclude(x_z,'neg',0.01).mdrmd
## 5  CO_FirstCrossing(x_z,'ac',1/exp(1),'both').pointOfCrossing
## 6                                       CO_FirstMin(x_z,'ac')
## 7                SP_Summaries(x_z,'fft',[],[],false).area_5_1
## 8                   SP_Summaries(x_z,'fft',[],[],false).wq_50
## 9                           FC_LocalSimple(x_z,'mean',3).stde
## 10                        FC_LocalSimple(x_z,'mean',1).taurat
## 11                                          MD_pNN(x_z).pnn40
## 12                    SB_BinaryStats(x_z,'mean').longstretch1
## 13                    SB_BinaryStats(x_z,'diff').longstretch0
## 14                           SB_MotifThree(x_z,'quantile').hh
## 15                     CO_HistogramAMI(x_z,1:5,'even',5).ami2
## 16                                         CO_trev(x_z,1).num
## 17             IN_AutoMutualInfoStats(x_z,40,'gaussian').fmmi
## 18      SB_TransitionMatrix(x_z,'quantile',3,'ac').sumdiagcov
## 19                             PD_PeriodicityWang(x_z).th0_01
## 20                CO_Embed2_Dist(x_z,'tau').d_expfit_meandiff
## 21      SC_FluctAnal(x_z,2,'rsrangefit',50,1,[],true).prop_r1
## 22              SC_FluctAnal(x_z,2,'dfa',50,1,2,true).prop_r1
## 23                                          DN_Mean(x,'norm')
## 24                                         DN_Spread(x,'std')

Short names and single features

Short names can be added to the output of catch22_all:

catch22_all(data, short_names = TRUE)
##                                           names     values         short_names
## 1                            DN_HistogramMode_5  0.7265508              mode_5
## 2                           DN_HistogramMode_10  0.9688692             mode_10
## 3                 DN_OutlierInclude_p_001_mdrmd  0.1600000  outlier_timing_pos
## 4                 DN_OutlierInclude_n_001_mdrmd  0.0900000  outlier_timing_neg
## 5       CO_FirstCrossing_acf_1e_pointOfCrossing  0.7575219       acf_timescale
## 6                                CO_FirstMin_ac  2.0000000       acf_first_min
## 7                     SP_Summaries_fft_area_5_1  0.2573182      low_freq_power
## 8                        SP_Summaries_fft_wq_50  1.2762720         median_freq
## 9                     FC_LocalSimple_mean3_stde  1.1463080      forecast_error
## 10                  FC_LocalSimple_mean1_taurat  0.3677143    whiten_timescale
## 11                                 MD_pNN_pnn40  0.9797980    high_fluctuation
## 12             SB_BinaryStats_mean_longstretch1  9.0000000        stretch_high
## 13             SB_BinaryStats_diff_longstretch0  3.0000000  stretch_decreasing
## 14                    SB_MotifThree_quantile_hh  2.1974876       entropy_pairs
## 15               CO_HistogramAMI_even_5bin_ami2  0.0848739                ami2
## 16                                CO_trev_1_num -0.2719364                trev
## 17      IN_AutoMutualInfoStats_40_gaussian_fmmi  3.0000000       ami_timescale
## 18 SB_TransitionMatrix_quantile_3_ac_sumdiagcov  0.0040261 transition_variance
## 19                    PD_PeriodicityWang_th0_01  6.0000000         periodicity
## 20         CO_Embed2_Dist_tau_d_expfit_meandiff  0.1689918      embedding_dist
## 21  SC_FluctAnal_2_rsrangefit_50_1_logi_prop_r1  0.4285714            rs_range
## 22       SC_FluctAnal_2_dfa_50_1_2_logi_prop_r1  0.4285714                 dfa

A single feature can be computed by its name or short name, giving the same value as catch22_all:

catch22_feature(data, "trev")
## [1] -0.2719364
CO_trev_1_num(data)
## [1] -0.2719364

Features that cannot be estimated

Some features cannot be estimated for some time series (e.g., a constant or very short time series). By default (mask_nans = TRUE), each such feature is set to a fixed value at the appropriate end of its range, so that catch22_all always returns real numbers. The masked column (with return_masked = TRUE) shows which values were masked, and mask_nans = FALSE gives NaN for them instead:

constant <- rep(1, 100)
head(catch22_all(constant, return_masked = TRUE))
##                                     names values masked
## 1                      DN_HistogramMode_5      0   TRUE
## 2                     DN_HistogramMode_10      0   TRUE
## 3           DN_OutlierInclude_p_001_mdrmd      0   TRUE
## 4           DN_OutlierInclude_n_001_mdrmd      0   TRUE
## 5 CO_FirstCrossing_acf_1e_pointOfCrossing     99   TRUE
## 6                          CO_FirstMin_ac    100   TRUE
head(catch22_all(constant, mask_nans = FALSE))
##                                     names values
## 1                      DN_HistogramMode_5    NaN
## 2                     DN_HistogramMode_10    NaN
## 3           DN_OutlierInclude_p_001_mdrmd    NaN
## 4           DN_OutlierInclude_n_001_mdrmd    NaN
## 5 CO_FirstCrossing_acf_1e_pointOfCrossing    NaN
## 6                          CO_FirstMin_ac    NaN

A time series containing NaN, NA or Inf gives NaN for every feature (with a warning).