Analysis#

Loading the data#

pip install \
    --extra-index-url https://v01dXYZ.github.io/vision-toolkit/pyindex \
    vision-toolkit==0.0.0a1.dev389+g6ddc1f3ca

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns

import vision_toolkit2 as vt2

df = pd.read_csv(f"{vt2.example_dataset_dir()}/data_1.csv")
df

gazeX	gazeY
1051.811	185.862
1052.974	188.4511
1049.647	189.7382
1056.02	194.5852
1050.597	190.8808
...	...
664.5712	357.8108
667.3209	350.5245
665.432	342.5446
668.3115	357.9101
663.9468	345.6406

3999 rows x 2 columns

serie = vt2.Serie.read_csv(
    f"{vt2.example_dataset_dir()}/data_1.csv",
    size_plan_x=512,
    size_plan_y=512,
    sampling_frequency=1000,
    distance_type="euclidean",
)

sns.lineplot({"x": serie.x, "y": serie.y});

png

plt.plot(serie.x, serie.y);

png

sns.histplot(x=serie.x, y=serie.y, bins=50);

png

sns.lineplot(serie.absolute_speed);

png

from vision_toolkit2.segmentation.analysis import (
    saccade as sac_analysis,
    fixation as fix_analysis,
    pursuit as pur_analysis,
    pursuit_task as pt_analysis,
)

sac_analysis.count(serie)

{'count': 15}

Fixation Analysis Functions#

The Vision Toolkit provides comprehensive fixation analysis functions:

Basic Metrics#

count() - Count the number of fixations
frequency() - Calculate fixation frequency
frequency_wrt_labels() - Frequency with respect to labels
durations() - Fixation durations

Example:

fix_analysis.count(serie)

{'count': 15}

fix_analysis.frequency(serie)

{'frequency': 3.750937734433608}

fix_analysis.frequency_wrt_labels(serie)

{'frequency': 3.817765334690761}

fix_analysis.durations(serie)

{'duration_mean': 0.15033333333333332,
 'duration_sd': 0.08588752334691381,
 'raw': array([0.107, 0.276, 0.077, 0.177, 0.095, 0.097, 0.082, 0.317, 0.272,
        0.105, 0.079, 0.101, 0.262, 0.107, 0.101])}

Spatial Analysis#

centroids() - Fixation centroids (center points)
drift_displacements() - Displacement during fixations
drift_distances() - Total distance traveled during fixations
drift_velocities() - Velocities during fixations

Example:

fix_analysis.centroids(serie)

{'centroids': array([[1059.79150718,  186.76042876],
        [ 673.2726369 ,  373.51161213],
        [1016.13262324,  416.70778485],
        [ 883.71841851,  674.73369492],
        [ 736.79375365,  726.41066407],
        [ 252.00809809,  699.41673389],
        [ 331.00173369,   74.24673508],
        [ 373.00319399,  359.84872134],
        [ 668.69204291,  354.63359706],
        [ 761.59439183,  278.23225397],
        [ 939.11668917,  258.7944735 ],
        [ 781.14097488,  449.41477266],
        [ 678.40768722,  359.25886693],
        [ 743.37814489,  264.58397447],
        [ 665.53335004,  367.14904209]])}

fix_analysis.drift_displacements(serie)

{'drift_displacement_mean': 14.055241261644381,
 'drift_displacement_sd': 12.123970432442798,
 'raw': array([16.90838806, 16.81196844,  0.32607768, 37.50761505,  2.62295743,
         4.50798028, 32.05264536, 17.13155327, 15.05813834,  8.64871887,
         5.47965738,  2.39924441,  7.0017103 ,  9.4032098 , 34.96875427])}

fix_analysis.drift_distances(serie)

{'drift_cumul_distance_mean': 80.58726718291312,
 'drift_cumul_distance_sd': 66.76842471162495,
 'raw': array([ 36.5417955 , 191.68126899,  24.88534736,  83.97655827,
         22.76253223,  25.3973385 ,  57.99453109, 131.25182414,
        229.3513495 ,  39.93694014,  29.10836466,  52.67431712,
        157.75472207,  33.20421307,  92.28790512])}

fix_analysis.drift_velocities(serie)

{'drift_velocity_mean': 110.73537997684822,
 'drift_velocity_sd': 119.39640396739392,
 'raw': array([159.51309487,  61.13443069,   4.29049574, 213.11144916,
         27.90380246,  46.95812791, 395.71167112,  54.21377616,
         55.56508612,  83.16075832,  70.25201768,  23.99244405,
         26.82647626,  88.70952645, 349.68754266])}

Advanced Metrics#

BCEA() - Bivariate Contour Ellipse Area (spatial dispersion)
average_velocity_means() - Average velocity means
average_velocity_deviations() - Deviations in average velocities

Example:

fix_analysis.BCEA(serie)

{'average_BCEA': 79.79662807124008,
 'raw': array([ 49.92864074, 192.15812199,  10.75192963, 103.25531394,
          6.60857609,   8.29428948, 150.5608987 ,  90.71091206,
        330.87316788,  11.77368667,  14.88026096,  23.12691575,
         51.79216072,  23.04257385, 129.19197261])}

fix_analysis.average_velocity_means(serie)

{'average_velocity_means': 497.0121908210056,
 'raw': array([344.73391978, 697.02279632, 327.43878102, 477.13953561,
        242.15459817, 264.55560933, 715.98186528, 415.35387386,
        846.31494281, 384.00903982, 373.18416232, 526.7431712 ,
        604.42422248, 313.24729309, 922.87905121])}

fix_analysis.average_velocity_deviations(serie)

{'average_velocity_sd': 418.50920424828973,
 'raw': array([261.09389071, 465.19251154, 217.05041374, 597.35594151,
        180.32999528, 208.05850446, 659.30342139, 270.09371894,
        524.54366161, 410.29680971, 261.18709689, 339.55236856,
        405.647778  , 302.1752015 , 567.38119255])}

Saccade Analysis Functions#

The Vision Toolkit provides 30 easy-access saccade analysis functions:

Basic Metrics#

count() - Count the number of saccades
frequency() - Calculate saccade frequency
frequency_wrt_labels() - Frequency with respect to labels
durations() - Saccade durations

Example:

sac_analysis.count(serie)

{'count': 15}

sac_analysis.frequency(serie)

{'frequency': 3.750937734433608}

sac_analysis.frequency_wrt_labels(serie)

{'frequency': 3.817765334690761}

sac_analysis.durations(serie)

{'duration_mean': 0.11160000000000002,
 'duration_sd': 0.10142470817592442,
 'raw': array([0.098, 0.253, 0.348, 0.019, 0.032, 0.174, 0.103, 0.126, 0.036,
        0.028, 0.022, 0.134, 0.038, 0.235, 0.028])}

Spatial Analysis#

amplitudes() - Saccade amplitudes (start to end distance)
travel_distances() - Total distance traveled during saccades
efficiencies() - Saccade efficiency (amplitude/travel distance)

Example:

sac_analysis.amplitudes(serie)

{'amplitude_mean': 263.59143726705116,
 'amplitude_sd': 156.9313660360474,
 'raw': array([431.069, 350.647, 317.88 ,  65.693, 148.412, 491.634, 614.051,
        295.985, 279.154, 130.954, 185.546, 253.139, 127.006, 120.422,
        142.28 ])}

sac_analysis.travel_distances(serie)

{'distance_mean': 484.95562953672714,
 'distance_sd': 371.95667930081976,
 'raw': array([ 633.53781441,  745.88303269, 1260.20088406,   65.74618809,
         178.92414304,  605.94358212,  704.75175062,  434.15993366,
         324.33523717,  155.22669753,  185.64949582,  462.51924717,
         169.8808253 , 1181.54976927,  166.02584211])}

sac_analysis.efficiencies(serie)

{'efficiency_mean': 0.7035608229643436,
 'efficiency_sd': 0.2599348422781371,
 'raw': array([0.68041558, 0.4701099 , 0.2522455 , 0.99919101, 0.82946883,
        0.81135276, 0.87130113, 0.68174186, 0.86069587, 0.84363065,
        0.99944252, 0.54730479, 0.74761822, 0.10191869, 0.85697502])}

Directional Analysis#

directions() - Saccade directions
horizontal_deviations() - Horizontal deviations from straight path
successive_deviations() - Deviations between consecutive saccades
initial_directions() - Initial direction of saccades
initial_deviations() - Initial deviation from final direction

Example:

sac_analysis.directions(serie)

{'direction_mean': 184.97585845975223,
 'direction_sd': 113.6534620269226,
 'raw': array([1.53709393e+02, 1.03937931e+01, 1.24104281e+02, 3.38466526e+02,
        1.62012981e+02, 1.83261916e+02, 2.77576264e+02, 7.94224579e+01,
        2.73062781e-01, 3.19833123e+02, 3.53888544e+02, 1.29199178e+02,
        2.15611257e+02, 3.01101980e+02, 1.25783120e+02])}

sac_analysis.horizontal_deviations(serie)

{'horizontal_deviation_mean': 35.10541888715441,
 'horizontal_deviation_sd': 22.84622026882561,
 'raw': array([69.56665357, 18.22034647,  3.2324008 , 39.51022668, 34.91098499,
        45.19190081])}

sac_analysis.successive_deviations(serie)

{'successive_deviation_mean': 106.62170836383449,
 'successive_deviation_sd': 51.94899597098306,
 'raw': array([143.31559962, 113.71048831, 145.63775517, 176.45354522,
         21.24893512,  94.31434744, 161.84619431,  79.14939508,
         40.43994005,  34.05542154, 135.31063421,  86.41207808,
         85.49072335, 175.3188596 ])}

sac_analysis.initial_directions(serie)

{'initial_direction_mean': 219.19264232249864,
 'initial_direction_sd': 77.41774874422606,
 'raw': array([174.0732116 , 162.84974379, 181.84854444, 273.81392803,
        353.03383249, 169.53659358])}

sac_analysis.initial_deviations(serie)

{'initial_deviation_mean': 47.603499828375625,
 'initial_deviation_sd': 50.831402248537685,
 'raw': array([ 63.63986518,   1.07009025,   1.38385635,  46.67584529,
        138.12284749,  34.7284944 ])}

Velocity Analysis#

mean_velocities() - Mean velocities during saccades
average_velocity_means() - Average of mean velocities
average_velocity_deviations() - Deviations in average velocities
peak_velocities() - Peak velocities during saccades

Example:

sac_analysis.mean_velocities(serie)

{'velocity_means': array([6531.31767432, 2959.85330433, 3631.7028359 , 3652.56600483,
        5771.74654963, 3502.56405852, 6909.33088842, 3473.27946926,
        9266.72106201, 5749.13694537, 8840.45218182, 3477.58832458,
        4591.37365677, 5049.35798835, 6149.10526333]),
 'velocity_sd': array([7809.39240384, 3681.58783385, 4341.6296244 ,  824.203462  ,
        3398.34292001, 5167.60681114, 9320.70536659, 3670.71051078,
        6896.32553026, 2943.21723887, 2823.65850373, 4417.55336831,
        2879.03031232, 6966.05956474, 1670.38879191])}

sac_analysis.average_velocity_means(serie)

{'average_velocity_means': 2966.4394479887574,
 'raw': array([2482.81318212, 5391.3041701 , 3319.56566684, 2106.73721024,
        2556.1955222 , 1942.02093643])}

sac_analysis.average_velocity_deviations(serie)

{'average_velocity_sd': 5368.084202508176,
 'raw': array([7809.39240384, 3681.58783385, 4341.6296244 ,  824.203462  ,
        3398.34292001, 5167.60681114, 9320.70536659, 3670.71051078,
        6896.32553026, 2943.21723887, 2823.65850373, 4417.55336831,
        2879.03031232, 6966.05956474, 1670.38879191])}

sac_analysis.peak_velocities(serie)

{'velocity_peak_mean': 16041.565290300752,
 'velocity_peak_sd': 8140.594554774943,
 'raw': array([26650.54675156, 11499.13964563, 19403.31166761,  4653.86626757,
        10013.66399242, 20937.55248962, 31768.01225285, 12724.2554848 ,
        18929.90510991,  9441.76701085, 11908.10264895, 15259.22774882,
         9205.95430364, 29108.31132714,  9119.86265314])}

Acceleration Analysis#

mean_acceleration_profiles() - Mean acceleration profiles
mean_accelerations() - Mean accelerations
mean_decelerations() - Mean decelerations
average_acceleration_profiles() - Average acceleration profiles
average_acceleration_means() - Average acceleration means
average_deceleration_means() - Average deceleration means
peak_accelerations() - Peak accelerations
peak_decelerations() - Peak decelerations

Example:

sac_analysis.mean_acceleration_profiles(serie)

{'acceleration_profile_means': array([ 874008.67854417,  466926.16994806,  627911.47499608,
         335174.79626075,  824650.41218432,  555918.21626835,
         951089.91712113,  518265.68135677, 1170104.6829876 ,
         691696.08123762,  869260.51061405,  632317.5849134 ,
         793696.85863302,  770103.8451626 ,  554280.42255197]),
 'acceleration_profile_sd': array([701462.64472679, 446766.25927397, 583007.54657288, 200906.84153639,
        526539.34232105, 672846.95952373, 999770.5717708 , 537261.69668498,
        934921.19500209, 492776.57257371, 625339.57975458, 597433.45790866,
        527394.26529169, 841002.02537918, 379527.76649318])}

sac_analysis.mean_accelerations(serie)

{'acceleration_means': array([1520512.08247845,  445526.10829659,  853427.57830499,
         328345.53289676,  784567.06262209, 1545560.05069237,
        1715166.34799621,  464800.81672111, 1266974.06225195,
         702990.14460236,  957113.22256442,  570044.32916096,
         815741.75825093,  692778.12666915,  437903.06848542]),
 'acceleration_sd': array([ 573833.62125638,  431105.36236059,  687935.96698542,
         147818.78723956,  595753.43157626,  929186.22400531,
        1164665.17019426,  496353.21668619,  906475.41314918,
         525137.97420084,  663128.0108422 ,  547133.03507697,
         641727.86296368,  738855.50654814,  322259.68793386])}

sac_analysis.mean_decelerations(serie)

{'deceleration_means': array([ 714481.86458636,  858711.91402875,  571735.98355811,
         342857.71754524,  870459.95454115,  461366.44864822,
         774047.81728422,  906777.03104257, 1083998.56808596,
         666284.43866695,  797381.01901829, 1083798.68911862,
         781236.69797941, 1752595.32719698,  670657.77661852]),
 'deceleration_sd': array([ 637807.51330115,  558919.64754015,  540732.34886413,
         259152.96777654,  452441.9576743 ,  561783.8436423 ,
         874010.67238157,  671921.05981058,  977256.10672433,
         443229.79860326,  615283.3472987 ,  758086.28130025,
         466290.99860069, 1346719.05067745,  408521.88424123])}

sac_analysis.average_acceleration_profiles(serie)

{'average_means': 562237.9145644187,
 'raw': array([494219.56510628, 818376.52627536, 548932.86171236, 455658.01389053,
        539207.03050419, 517033.48989781])}

sac_analysis.average_acceleration_means(serie)

{'average_means': 1031478.1743529715,
 'raw': array([1274467.89930545,  788040.35019116, 1459368.5399476 ,
        1629079.53269371,  515980.58972147,  521932.13425845])}

sac_analysis.average_deceleration_means(serie)

{'average_means': 683583.8921889699,
 'raw': array([ 477827.79337941,  854779.9375764 ,  450802.07004628,
         428710.96439818, 1373423.36194992,  515959.22578363])}

sac_analysis.peak_accelerations(serie)

{'peak_acceleration_mean': 2368437.122632236,
 'raw': array([2511911.01514697, 1743177.60890077, 2715507.00586859,
         626592.64547203, 2228990.43841675, 3145643.01911695,
        3272446.04413716, 2946826.10477496, 2931107.49783274,
        1623478.0392322 , 2247672.89934087, 2802894.96029465,
        1990640.97928238, 3658806.55368692, 1080862.0279796 ])}

sac_analysis.peak_decelerations(serie)

{'peak_deceleration_mean': 2375344.451726647,
 'raw': array([3026345.84276135, 2268448.63547742, 2840737.69996218,
         691843.49694667, 1586251.86598377, 3150151.34000444,
        3792391.60021473, 2189989.87999209, 3350011.18597608,
        1378607.30839093, 2088463.15707768, 2151300.80276127,
        1759364.42185024, 3982689.01893544, 1373570.51956542])}

Curvature Analysis#

max_curvatures() - Maximum curvatures during saccades
area_curvatures() - Area under curvature curves

Example:

sac_analysis.max_curvatures(serie)

{'max_curvature_mean': 93.35793348869778,
 'max_curvature_sd': 142.2644719876219,
 'raw': array([110.18243607, 170.87111479, 380.81212727,   0.71585189,
          2.26083867,  24.7412767 ,  15.40398849,  65.8200162 ,
          8.84604322,   5.99937132,   1.55342605, 120.13961   ,
          5.28364247, 454.84224317,  32.89701602])}

sac_analysis.area_curvatures(serie)

{'curvature_area_mean': 16570.088935698346,
 'curvature_area_sd': 24430.353059600908,
 'raw': array([3.17267710e+04, 3.84703699e+04, 7.57511402e+04, 2.56027217e+01,
        2.55848221e+02, 2.96131023e+03, 5.94766646e+03, 1.06264774e+04,
        2.31977793e+03, 1.65005492e+02, 2.09902051e+02, 1.39257974e+04,
        3.38912885e+02, 6.22928501e+04, 3.53390207e+03])}

Advanced Metrics#

skewness_exponents() - Skewness exponents
gamma_skewness_exponents() - Gamma distribution skewness
amplitude_duration_ratios() - Amplitude/duration ratios
peak_velocity_amplitude_ratios() - Peak velocity/amplitude ratios
peak_velocity_duration_ratios() - Peak velocity/duration ratios
peak_velocity_velocity_ratios() - Peak velocity/velocity ratios
acceleration_deceleration_ratios() - Acceleration/deceleration ratios
main_sequence() - Main sequence analysis

Example:

sac_analysis.skewness_exponents(serie)

{'skewness_exponent_mean': 0.5120498599429821,
 'skewness_exponent_sd': 0.28798385121666226,
 'raw': array([0.19587629, 0.94444444, 0.19884726, 0.5       , 0.51612903,
        0.0867052 , 0.18627451, 0.872     , 0.45714286, 0.66666667,
        0.42857143, 0.87218045, 0.35135135, 0.92307692, 0.48148148])}

sac_analysis.gamma_skewness_exponents(serie)

{'skewness_exponent_mean': 223.26049970374746,
 'skewness_exponent_sd': 467.07881903400164,
 'raw': array([7.46465306e-01, 8.21589712e-01, 8.58361408e-01, 2.36584287e+02,
        5.18278812e+02, 5.95218307e-01, 4.77401079e-01, 9.42284832e-01,
        1.65689815e+01, 2.44821249e+02, 2.84749637e+02, 6.69665298e-01,
        2.30353770e+02, 5.32193380e-01, 1.81190758e+03])}

sac_analysis.amplitude_duration_ratios(serie)

{'ratio_mean': 3841.335857333124,
 'ratio_sd': 2348.6947134260063,
 'raw': array([4398.66326531, 1385.95652174,  913.44827586, 3457.52631579,
        4637.875     , 2825.48275862, 5961.66019417, 2349.08730159,
        7754.27777778, 4676.92857143, 8433.90909091, 1889.09701493,
        3342.26315789,  512.43404255, 5081.42857143])}

sac_analysis.peak_velocity_amplitude_ratios(serie)

{'ratio_mean': 71.59714025305044,
 'ratio_sd': 48.536371970692386,
 'raw': array([ 61.82431757,  32.79406253,  61.03973722,  70.84265093,
         67.4720642 ,  42.58768208,  51.73513642,  42.98952813,
         67.81169215,  72.09987485,  64.17870851,  60.28003488,
         72.4844047 , 241.71921515,  64.09799447])}

sac_analysis.peak_velocity_duration_ratios(serie)

{'ratio_mean': 244719.2713983509,
 'ratio_sd': 154645.72312977165,
 'raw': array([271944.3546078 ,  45451.1448444 ,  55756.64272301, 244940.32987218,
        312926.99976299, 120330.76143458, 308427.30342569, 100986.15464129,
        525830.69749753, 337205.96467316, 541277.3931343 , 113874.83394639,
        242261.955359  , 123865.15458356, 325709.38046939])}

sac_analysis.peak_velocity_velocity_ratios(serie)

{'ratio_mean': 8.837394843600082,
 'ratio_sd': 14.190463593429826,
 'raw': array([ 6.05878312,  8.29689782, 21.24182855,  1.34601037,  2.15910605,
         7.41025668,  5.32871905,  5.41668054,  2.44122092,  2.0187965 ,
         1.41193159,  8.07752467,  2.75440738, 56.80401556,  1.79474385])}

sac_analysis.acceleration_deceleration_ratios(serie)

{'ratio_mean': 1.0227356324045165,
 'ratio_sd': 0.20737330131319145,
 'raw': array([0.83001453, 0.76844482, 0.95591614, 0.90568553, 1.40519326,
        0.99856886, 0.86289771, 1.34558891, 0.87495454, 1.17762181,
        1.07623297, 1.3028838 , 1.13145461, 0.91867744, 0.78689955])}

sac_analysis.main_sequence(serie)

{'slope_amplitude_duration': 564.0959146659854,
 'slope_log_peak_velocity_log_amplitude': 0.6162975867633347,
 'raw_amplitude_duration': array([[4.31069e+02, 3.50647e+02, 3.17880e+02, 6.56930e+01, 1.48412e+02,
         4.91634e+02, 6.14051e+02, 2.95985e+02, 2.79154e+02, 1.30954e+02,
         1.85546e+02, 2.53139e+02, 1.27006e+02, 1.20422e+02, 1.42280e+02],
        [9.80000e-02, 2.53000e-01, 3.48000e-01, 1.90000e-02, 3.20000e-02,
         1.74000e-01, 1.03000e-01, 1.26000e-01, 3.60000e-02, 2.80000e-02,
         2.20000e-02, 1.34000e-01, 3.80000e-02, 2.35000e-01, 2.80000e-02]]),
 'raw_log_peak_velocity_log_amplitude': array([[10.19056495,  9.3500275 ,  9.87319903,  8.44545361,  9.21170584,
          9.9492996 , 10.36621516,  9.45126533,  9.84849823,  9.15289842,
          9.38497434,  9.6329397 ,  9.12760576, 10.27877902,  9.11821002],
        [ 6.06626817,  5.85978002,  5.76167395,  4.18499237,  4.99999219,
          6.19773454,  6.42007799,  5.69030878,  5.6317636 ,  4.87484612,
          5.22330283,  5.53393874,  4.84423433,  4.79100224,  4.95779695]])}

Pursuit Analysis Functions#

The Vision Toolkit provides comprehensive pursuit analysis functions:

Basic Metrics#

count() - Count the number of pursuits
frequency() - Calculate pursuit frequency
durations() - Pursuit durations
proportion() - Proportion of time spent in pursuit

Example:

pur_analysis.count(serie)

{'count': 0}

pur_analysis.frequency(serie)

{'frequency': 0.0}

pur_analysis.durations(serie)

{'duration_mean': nan, 'duration_sd': 0.0, 'raw': array([], dtype=float64)}

pur_analysis.proportion(serie)

0.0

Velocity Analysis#

velocity() - Pursuit velocities
velocity_means() - Mean velocities during pursuits
peak_velocity() - Peak velocities during pursuits

Example:

pur_analysis.velocity(serie)

{'velocity_mean': nan, 'velocity_sd': nan, 'raw': array([], dtype=float64)}

pur_analysis.velocity_means(serie)

{'velocity_mean_mean': nan,
 'velocity_mean_sd': 0.0,
 'raw': array([], dtype=float64)}

pur_analysis.peak_velocity(serie)

{'velocity_peak_mean': nan,
 'velocity_peak_sd': 0.0,
 'raw': array([], dtype=float64)}

Spatial Analysis#

amplitude() - Pursuit amplitudes
distance() - Total distance traveled during pursuits
efficiency() - Pursuit efficiency (amplitude/distance)

Example:

pur_analysis.amplitude(serie)

{'pursuit_amplitude_mean': nan,
 'pursuit_amplitude_sd': 0.0,
 'raw': array([], dtype=float64)}

pur_analysis.distance(serie)

{'pursuit_cumul_distance_mean': nan,
 'pursuit_cumul_distance_sd': 0.0,
 'raw': array([], dtype=float64)}

pur_analysis.efficiency(serie)

{'pursuit_efficiency_mean': nan,
 'pursuit_efficiency_sd': 0.0,
 'raw': array([], dtype=float64)}

Pursuit Task Analysis Functions#

The Vision Toolkit provides specialized pursuit task analysis functions that compare eye movements with theoretical target trajectories:

Note: Pursuit task analysis functions require a df_theo DataFrame parameter containing theoretical target coordinates.

Loading Example Pursuit Data#

# Load example pursuit data with theoretical coordinates
df_pt = pd.read_csv(f"{vt2.example_dataset_dir()}/example_pursuit.csv")
df_theo_pt = pd.read_csv(f"{vt2.example_dataset_dir()}/example_pursuit_theo.csv")

df_pt

gazeX	gazeY
0.0288211931218482	0.0106036887451069
-0.0631863318262917	0.0424576956174804
-0.0417897107394136	-0.0870415965809288
0.0057507248530428	0.0825739279774412
0.0511850769140803	-0.0902064852115022
...	...
0.0649128167562948	-0.0237703949124262
0.0256697880621413	-0.0325704022102016
-0.0764059439041511	-0.0287189289858926
-0.0996245922863675	0.0903048575196924
-0.0312704500582591	0.0814406116932641

1000 rows x 2 columns

df_theo_pt

gazeX	gazeY
0.019998666693333	0.019998666693333
0.0399893341866341	0.0399893341866341
0.0599640064794445	0.0599640064794445
0.0799146939691727	0.0799146939691727
0.0998334166468281	0.0998334166468281
...	...
-0.4575358937753213	-0.4575358937753213
-0.4752270271347798	-0.4752270271347798
-0.4927280760196602	-0.4927280760196602
-0.5100320402437544	-0.5100320402437544
-0.527131998452086	-0.527131998452086

499 rows x 2 columns

# Create a Serie from the pursuit data
serie_pt = vt2.Serie.read_csv(
    f"{vt2.example_dataset_dir()}/example_pursuit.csv",
    size_plan_x=512,
    size_plan_y=512,
    sampling_frequency=1000,
    distance_type="euclidean",
)

Basic Metrics#

count() - Count the number of pursuits
frequency() - Calculate pursuit frequency
durations() - Pursuit durations
proportion() - Proportion of time spent in pursuit

Example:

pt_analysis.count(serie_pt, df_theo_pt)

{'count': 2}

pt_analysis.frequency(serie_pt, df_theo_pt)

{'frequency': 4.008016032064128}

pt_analysis.durations(serie_pt, df_theo_pt)

{'duration_mean': 0.07450000000000001,
 'duration_sd': 0.03606244584051393,
 'raw': array([0.1  , 0.049])}

pt_analysis.proportion(serie_pt, df_theo_pt)

0.2985971943887776

Comparison Metrics#

slope_ratios() - Ratio of eye movement slope to theoretical slope
slope_gain() - Gain between eye and theoretical movement slopes
overall_gain() - Overall gain across all dimensions
overall_gain_x() - Gain in X dimension
overall_gain_y() - Gain in Y dimension

Example:

pt_analysis.slope_ratios(serie_pt, df_theo_pt)

{'slope ratios': {'x': array([-1.29368165, -0.66278861]),
  'y': array([-1.29325865, -0.66166223])}}

pt_analysis.slope_gain(serie_pt, df_theo_pt)

{'slope gain': {'gain_x': -1.0862067599539853, 'gain_y': -1.0855524467645192}}

pt_analysis.overall_gain(serie_pt, df_theo_pt)

{'overall_gain': 4.430965455931988}

pt_analysis.overall_gain_x(serie_pt, df_theo_pt)

{'overall_gain_x': -2.079321691524132}

pt_analysis.overall_gain_y(serie_pt, df_theo_pt)

{'overall_gain_y': -3.174250490599}

Advanced Analysis#

sinusoidal_phase() - Phase difference for sinusoidal movements
crossing_time() - Time when eye crosses theoretical target path
accuracy() - Accuracy of pursuit relative to theoretical target
entropy() - Entropy measure of pursuit performance

Example:

pt_analysis.sinusoidal_phase(serie_pt, df_theo_pt)

{'phase_difference': 3.4957071049527455}

pt_analysis.crossing_time(serie_pt, df_theo_pt)

{'crossing_time': {'x': 0.0, 'y': 0.0}}

pt_analysis.accuracy(serie_pt, df_theo_pt)

{'accuracy': {'x': 0.0, 'y': 0.0}}

pt_analysis.entropy(serie_pt, df_theo_pt)

{'entropy': {'x': -0.002042901629797811, 'y': -0.002042901629797811}}