Package: gazel
gazelgazel provides fixation algorithms for aggregating gazes, as well as tools to help you deal with edits that occur during eyetracking sessions.Getting startedInstallationRequirementsgazel requires python 3.8.5InstallationYou can install gazel usingpip install gazelgazel comes with a command line interface as well as a python library.To use either version, you need 3 things:itrace core file outputgaze file outputchangelogoriginal source file(s)To get started:# import gazelfromgazelimportfixation_filter,Tracker# run fixation filter to get fixationsfixations=fixation_filter(gazes,changelog,sources,**opts)# Now track edits using Trackertracker=Tracker(fixations,changelog,sources,language)# Note that you need to pass in the source code language,# to help `gazel` determine which parser to use.Base FunctionalityThe main goal ofTrackeris to track fixations and source code tokens across edits. Once you create aTrackeryou can query it to get snapshots etc.SnapshotsTrackermaintains a list of snapshots corresponding to the original file and subsequent edits. The original version is stored at index0and the first edit is stored at index1.# get originaltracker.get_snapshot(0)# get first edittracker.get_snapshot(1)Each snapshot is represented by aSnapshot. ASnapshotis defined as:classSnapshot:id:intsource:Sourcetokens:Tuple[Token,...]changes:Tuple[TokenChange,...]=()time:float=0.0Snapshot.timerepresents the time at which a snapshot was created. It corresponds to the timestamp in the changelog that was used to create thisSnapshot.Snapshot.tokensrepresents the parsed source code tokens.Snapshot.changesrepresents all the token changes that happened to thisSnapshotsince the last version. For theSnapshotrepresenting the original source,Snapshot.changesis empty.Snapshots.sourceis aSourceobject, containing the raw text of the source code, as well as mappings from text indices to line/column numbers and vice-versa. It is defined as follows:@dataclass(frozen=True)classSource:text:strmapping:PositionMappinglanguage:strGazesYou can retreive gazes for a given time window as follows:tracker.get_gazes()# all gazestracker.get_gazes(start,end)# returns a dataframe that is filteredThe gaze dataframe is simply apandas.DataFramecontaining the original gazes, with some additional columns:syntax_node- The syntax node associated with the gaze.Noneif the gaze doesn't fall on a token.syntax_node_id- A stable id for the token associated with this gaze.Noneif the gaze doesn't fall on a token.syntax_node_idis a unique id that is assigned to each token in the source code across different snapshots. For a given token, this id is unique across time and space. Thus, you can use this id to determine howdiffstracker.diff(0,2)# gives you the diff between version 0 & version 1tracker.diff_time(2300,2400)# gives you the diff between time unit 2300 & time unit 2400ASnapshotDiffis defined as follows:classSnapshotDiff(NamedTuple):old:Snapshotnew:Snapshottoken_changes:List[TokenChange]gaze_changes:List[GazeChange]gazes:pd.DataFrameIt gives you a list of all token changes and gaze changes.Token changes can be of 3 types:inserted,movedordeleted.Gaze changes can be of 2 types:deletedormoved. (deletedmeans that the token to which the gaze was mapped to has been removed from the source.)By default,tracker.diff(start, end)will include all the gazes from the start of the experiment (the time at which the first gaze is recorded), up until theendsnapshot time. If you want to only include gazes within the timespan of thestartandendsnapshots, you can pass an optional parameter:diff=tracker.diff(0,3,window_only=True)gazelalso provides a pretty-printer to help you print diffs for inspecting the data. It supports print gaze changes, token changes andSnapshotDiffs.fromgazelimportpprintdiff=tracker.diff(2,3)pprint(diff)pprint(diff.token_changes)pprint(diff.gaze_changes)gazelprovides a moduletransformsto help you manipulategazelstructures includingSnapshotsandSnapshotDiff.fromgazelimporttransformsasTdiff=tracker.diff(2,5)# TODO