The SceneWalk Model Object¶

This class contains all the core functionalities of the SceneWalk Model.

Scenewalk Model Implementation

Lisa Schwetlick 2019

University of Potsdam

class scenewalk.scenewalk_model_object.scenewalk(inhib_method, att_map_init_type, shifts, locdep_decay_switch, omp, data_range, kwargs_dict=None)¶

Model class. Makes a scenewalk model according to the configurations given at instantiation (see below). Some of the most important features for the workflow are:

whoami() displays a string describing the configuration.

get_param_list_order() displays the exposed parameters that result from the chosen configuration.

update_params() lets you set parameter values.

get_scanpath_likelihood returns a scan path likelihood given the model.

simulate_scanpath returns a scan path simulated by the model.

Parameters

inhib_method{‘subtractive’, ‘divisive’}

How are attention and inhibition map combined?

att_map_init_type{‘zero’, ‘cb’}

How is the attention map initialized?

postsaccadic_shift_switch{‘on’, ‘off’}

is there a postaccadic attention shift?

presaccadic_shift_switch{‘on’, ‘off’}

is there a presaccadic attention shift?

locdep_decay_switch{‘on’, ‘off’}

Is there slower decay on he previous fixation location?

omp{“off”, add”, “mult”]}

Adds occulomotor potential

data_rangedict

dictionary ({‘x’ : [0,127], ‘y’ : [0,127]}) of the data range.

kwargs_dictdict

any other model attributes you may want to set. They pertain mainly to how the parameters of the model are exposed in set_params. For Example

exponents [1 or 2]: are Lambda and Gamma independent?

coupled_oms [True, False]: True changes the parametrization of omega to have om_i = om_a / om_frac

coupled_sigmas [True, False]: True changes the parametrization of sigma to be sig_i = sig_a

logged_cf [True, False]: True makes the cf = 10**input_cf

logged_z [True, False]: True makes the zeta = 10**input_zeta

logged_ompf [True, False]: True makes the ompf = 10**input_ompf

coupled_facil [True, False]: True makes omega_prevloc = om_a / omega_prevloc_frac

estimate_times [True, False]: True exposes the tau variables

saclen_shift [True, False]: True makes the postsaccadic shift depend of the saccade length

Notes

time data is always given in seconds (not ms)
position data is always given in degrees (not pixels)
the model is tested mainly on an internal representation of 128x128 pixels. Using set_mapsize() this can be changed.
the model uses an internal representation of np.float128. This is because for estimation, parameters can have “extreme” values that make the model numerically instable due to floating point problems. It also makes the computation slower, of course. Using set_precision() this can be changed.

Methods

`add_noise`(self, ustar)	adds zeta noise
`check_params_for_config`(self)	Checks whether all necessary parameters are present for the current configuration.
`check_params_in_bounds`(self)	Checks if all specified parameters fall in the defined range of the model
`clear_params`(self)	Clears all parameters
`combine_att_fixdens`(self, gaussAttention, …)	add empirical density information to gaussian attention mask
`combine_divisive`(self, mapAtt, mapInhib)	Combine attention and inhibition in a divisive way
`combine_subtractive`(self, mapAtt, mapInhib)	Combine attention and inhibition in a subtractive way
`convert_deg_to_px`(self, dat, dim[, fix, …])	Converts degree values to pixels on the grid.
`convert_px_to_deg`(self, dat, dim[, grid_sz])	Converts pixel values to degrees on the grid.
`differential_time_att_locdep`(self, duration, …)	QUICKER version of differential_time_att_locdep_round.
`differential_time_att_locdep_round`(self, …)	SLOWER version of differential_time_att_locdep evolve the maps over time with the normal attention decay parameter everywhere except around the previous fixation location.
`differential_time_att_org`(self, duration, …)	evolve the maps over time using the attention decay parameter
`differential_time_basic`(self, duration, …)	evolve the maps over time, given a decay paramter
`empirical_fixation_density`(self, x_locs_deg, …)	Calculates the empirical fixation density given fixation points and range information using the “scott” bandwidth (as in Schütt et al, 2017)
`evolve_maps_both`(self, durations, fixs_x, …)	Evolve maps with pre- and postsaccadic shift.
`evolve_maps_main`(self, durations, fixs_x, …)	Evolve maps with basic model
`evolve_maps_postsac`(self, durations, fixs_x, …)	Evolve maps with postsaccadic shift.
`evolve_maps_presac`(self, durations, fixs_x, …)	Evolve maps with presaccadic shift.
`fixation_picker_max`(self, likelihood_map[, …])	Picks the next fixation location according to the maximum activation value (deterministic).
`fixation_picker_stoch`(self, likelihood_map)	Picks the next fixation location according to the cumulative probability method (linear selection algorithm)
`get_param_list_order`(self)	Returns the names and order of the parameters required by the current model configuration
`get_params`(self)	Returns the current parameters as a dictionary
`get_phase_times_both`(self, nth, durations)	Helper function that computes the durations of each phase 1.
`get_scanpath_likelihood`(self, x_path, …)	calculate likelihood of one scanpath under scenewalk model with params in scene_walk_params.
`get_unit_vector`(self, point1, point2)	get the unit vector between 2 points.
`initialize_center_bias`(self)	Initializes a map with with a central gaussian
`initialize_map_unif`(self)	Initializes a map with near 0 activation everywhere
`make_attention_gauss`(self, fixs_x, fixs_y)	make gaussian window at fixation point for attention
`make_attention_gauss_post_shift`(self, …[, …])	make gaussian window at fixation point for attention during the post-saccadic shift
`make_inhib_gauss`(self, fixs_x, fixs_y)	make gaussian window at fixation point for inhibition
`make_om_potential`(self, fix_x, fix_y)	makes an occulomotor potential map where the cardinal directions have higher activation than the oblique.
`make_om_potential_neg`(self, fix_x, fix_y)	makes an occulomotor potential map where the cardinal directions have lower activation than the oblique.
`make_positive`(self, u)	cuts off negative components
`set_mapsize`(self, map_size)	Set up the operating grid size for calculation.
`set_precision`(self, data_type)	Set up the operating datatype for the whole model.
`simulate_durations`(self, amount)	generate durations from gamma distribtion.
`simulate_scanpath`(self, dur_path, fix_dens, …)	Simulates a scanpath given durations.
`update_params`(self, scene_walk_parameters)	Update model parameters
`whoami`(self)	Returns the model identity as a string
`window`(self, iterable[, n_before, n_after])	Sliding window iterator.

add_noise(self, ustar)¶

adds zeta noise

Parameters

ustararray: map without noise

Returns

array: uFinal; map with noise

check_params_for_config(self)¶

Checks whether all necessary parameters are present for the current configuration.

Returns

bool: True if all parameters are okay

check_params_in_bounds(self)¶

Checks if all specified parameters fall in the defined range of the model

Returns

bool: True if all parameters are okay

clear_params(self)¶: Clears all parameters

combine_att_fixdens(self, gaussAttention, fix_density_map)¶

add empirical density information to gaussian attention mask

Parameters

gaussAttentionarray: attention mask (usually 128x128)
fix_density_maparray: fixation desinty map (usually 128x128)

Returns

array: combined attention map (usually 128x128)

combine_divisive(self, mapAtt, mapInhib)¶

Combine attention and inhibition in a divisive way

Parameters

mapAttarray: attention map (128x128)
mapInhibarray: inhibition map (128x128)

Returns

array: combined map (128x128)

combine_subtractive(self, mapAtt, mapInhib)¶

Combine attention and inhibition in a subtractive way

Parameters

mapAttarray: attention map (128x128)
mapInhibarray: inhibition map (128x128)

Returns

array: combined map (128x128)

convert_deg_to_px(self, dat, dim, fix=False, cutoff=True, grid_sz=None)¶

Converts degree values to pixels on the grid.

Parameters

datint or float: number to convert in degrees
dim{‘x’ or ‘y’}: dimension along which to convert
fixbool: if true, returned pixel value is between 0 and 127 (in the grid)
cutoffbool: if True points outside the grid are set to the border
grid_szint: enables setting the grid size to another size than the internal model size

Returns

float: pixel value

convert_px_to_deg(self, dat, dim, grid_sz=None)¶

Converts pixel values to degrees on the grid.

Parameters

datint or float: number to convert in pixels
dim{‘x’ or ‘y’}: dimension along which to convert
grid_szint: enables setting the grid size to another size than the internal model size

Returns

float: degree value

differential_time_att_locdep(self, duration, current_map, prev_map, fixs_x=None, fixs_y=None)¶

QUICKER version of differential_time_att_locdep_round. Evolve the maps over time with the normal attention decay parameter everywhere except around the previous fixation location. A Rectangular aperture around the previous location defines the are of reduced decay.

Parameters

durationfloat: current fixation duration in seconds
current_mapfloat: current attention map
prev_mapfloat: previous attention map
fixs_xtuple: x fixation locations (prev, current, next)
fixs_y: tuple: y fixation location (prev, current, next)

Returns

array: evolved map

differential_time_att_locdep_round(self, duration, current_map, prev_map, fixs_x=None, fixs_y=None)¶

SLOWER version of differential_time_att_locdep evolve the maps over time with the normal attention decay parameter everywhere except around the previous fixation location. A circular aperture around the previous location defines the are of reduced decay.

Parameters

durationfloat: current fixation duration in seconds
current_mapfloat: current attention map
prev_mapfloat: previous attention map
fixs_xtuple: x fixation locations (prev, current, next)
fixs_y: tuple: y fixation location (prev, current, next)

Returns

array: evolved map

differential_time_att_org(self, duration, current_map, prev_map, **kwargs)¶

evolve the maps over time using the attention decay parameter

Parameters

durationfloat: current fixation duration in seconds
current_mapfloat: current attention map
prev_mapfloat: previous attention map

Returns

array: evolved map

differential_time_basic(self, duration, current_map, prev_map, omega)¶

evolve the maps over time, given a decay paramter

Parameters

durationfloat: current fixation duration in seconds
current_mapfloat: current attention or inhibition map
prev_mapfloat: previous attention or inhibition map
omegafloat: decay parameter to use

Returns

array: evolved map

empirical_fixation_density(self, x_locs_deg, y_locs_deg)¶

Calculates the empirical fixation density given fixation points and range information using the “scott” bandwidth (as in Schütt et al, 2017)

Parameters

x_locs_deg, y_locs_degfloat: coordinates in degrees

Returns

int: x coordinates in px
int: y coordinates in px
array: fixation density map

evolve_maps_both(self, durations, fixs_x, fixs_y, map_att_prev, map_inhib_prev, fix_density_map, nth, sim=False)¶

Evolve maps with pre- and postsaccadic shift. Parameters ———- fixs_x : tuple

of the shape (previous, current, next) fixation location’s x in degrees

fixs_ytuple: of the shape (previous, current, next) fixation location’s y in degrees
durationstuple: of the shape (previous, current, next) of durations in seconds
map_att_prevarray: previous attention map
map_inhib_prevarray: previous inhibition map
fix_density_maparray: empirical fixation density of the image
nthint: number of the fixation in the sequence

Returns

array: attention map
array: inhibition map
array: final map
tuple: coordinates for the next fixation in degrees (x, y)
float: likelihood of the next fixation

evolve_maps_main(self, durations, fixs_x, fixs_y, map_att_prev, map_inhib_prev, fix_density_map, nth, sim=False)¶

Evolve maps with basic model

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s x in degrees
fixs_ytuple: of the shape (previous, current, next) fixation location’s y in degrees
durationstuple: of the shape (previous, current, next) of durations in seconds
map_att_prevarray: previous attention map
map_inhib_prevarray: previous inhibition map
fix_density_maparray: empirical fixation density of the image
nthint: number of the fixation in the sequence

Returns

array: attention map
array: inhibition map
array: final map
tuple: coordinates for the next fixation in degrees (x, y)
float: likelihood of the next fixation

evolve_maps_postsac(self, durations, fixs_x, fixs_y, map_att_prev, map_inhib_prev, fix_density_map, nth, sim=False)¶

Evolve maps with postsaccadic shift.

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s x in degrees
fixs_ytuple: of the shape (previous, current, next) fixation location’s y in degrees
durationstuple: of the shape (previous, current, next) of durations in seconds
map_att_prevarray: previous attention map
map_inhib_prevarray: previous inhibition map
fix_density_maparray: empirical fixation density of the image
nthint: number of the fixation in the sequence

Returns

array: attention map
array: inhibition map
array: final map
tuple: coordinates for the next fixation in degrees (x, y)
float: likelihood of the next fixation

evolve_maps_presac(self, durations, fixs_x, fixs_y, map_att_prev, map_inhib_prev, fix_density_map, nth, sim=False)¶

Evolve maps with presaccadic shift.

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s x in degrees
fixs_ytuple: of the shape (previous, current, next) fixation location’s y in degrees
durationstuple: of the shape (previous, current, next) of durations in seconds
map_att_prevarray: previous attention map
map_inhib_prevarray: previous inhibition map
fix_density_maparray: empirical fixation density of the image
nthint: number of the fixation in the sequence

Returns

array: attention map
array: inhibition map
array: final map
tuple: coordinates for the next fixation in degrees (x, y)
float: likelihood of the next fixation

fixation_picker_max(self, likelihood_map, get_lik=False)¶

Picks the next fixation location according to the maximum activation value (deterministic).

Parameters

likelihood_maparray: (usually 128x128) map from which to pick
get_likbool: if true, return the point’s likelihood value

Returns

float: x value in degrees
float: y value in degrees
float (optional): likelihood

fixation_picker_stoch(self, likelihood_map, get_lik=False)¶

Picks the next fixation location according to the cumulative probability method (linear selection algorithm)

Parameters

likelihood_maparray: (usually 128x128) map from which to pick
get_likbool: if true, return the point’s likelihood value

Returns

float: x value in degrees
float: y value in degrees
float (optional): likelihood

get_param_list_order(self)¶: Returns the names and order of the parameters required by the current model configuration

get_params(self)¶: Returns the current parameters as a dictionary

get_phase_times_both(self, nth, durations)¶

Helper function that computes the durations of each phase 1. You always have the post phase, no matter what 2. the main phase can be skipped if the post phase is already too long 3. from the time that is left for the main phase we then subtract the pre phase. If that leaves the main phase less than 10 ms short, we skip the pre phase. 4. The post phase is always skipped for the first fixation

Parameters

nthint: the how many’th fixation in the sequence are we dealing with
durationstuple: of the shape (previous, current, next) of durations

Returns

float: duration of post phase (secs)
float: duration of main phase (secs)
float: duration of pre phase (secs)

get_scanpath_likelihood(self, x_path, y_path, dur_path, fix_dens)¶

calculate likelihood of one scanpath under scenewalk model with params in scene_walk_params.

Parameters

x_patharray: array with a datapoint for each fixation’s x coordinate
y_patharray: array with a datapoint for each fixation’s y coordinate
dur_patharray: array with a datapoint for each fixation’s duration
fix_densarray: empirical fixation density of the viewed image

Returns

float: sum log likelihood of the scanpath

Notes

Beware: it HAS to be the sum likelihood. Even if all the scan paths have different lengths. Don’t be tempted to use the average, it messes up the parameter estimation procedure!

get_unit_vector(self, point1, point2)¶

get the unit vector between 2 points. point1 is the origin. Vector goes toward point 2.

Parameters

point1, point2iterables of shape (x, y): points between which to find the unit vector

Returns

list: [unit vector x, unit vector y]
float: magnitude

initialize_center_bias(self)¶

Initializes a map with with a central gaussian

Returns

array: initial starting map

initialize_map_unif(self)¶

Initializes a map with near 0 activation everywhere

Returns

array: initial starting map

make_attention_gauss(self, fixs_x, fixs_y)¶

make gaussian window at fixation point for attention

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s x
fixs_ytuple: of the shape (previous, current, next) fixation location’s y
durationstuple: of the shape (previous, current, next) of durations

Returns

array: gaussian attention map (usually 128x128)

make_attention_gauss_post_shift(self, fixs_x, fixs_y, get_loc=False)¶

make gaussian window at fixation point for attention during the post-saccadic shift

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s y
fixs_ytuple: of the shape (previous, current, next) fixation location’s y
durationstuple: of the shape (previous, current, next) of durations

Returns

array: gaussian attention map (usually 128x128)

make_inhib_gauss(self, fixs_x, fixs_y)¶

make gaussian window at fixation point for inhibition

Parameters

fixs_xtuple: of the shape (previous, current, next) fixation location’s y
fixs_ytuple: of the shape (previous, current, next) fixation location’s y

Returns

array: gaussian inhibition map

make_om_potential(self, fix_x, fix_y)¶

makes an occulomotor potential map where the cardinal directions have higher activation than the oblique.

Parameters

fix_xfloat: x coordinate on which to center the cross
fix_yfloat: y coordinate on which to center the cross

Returns

array: map with oculomotor potential

make_om_potential_neg(self, fix_x, fix_y)¶

makes an occulomotor potential map where the cardinal directions have lower activation than the oblique.

Parameters

fix_xfloat: x coordinate on which to center the cross
fix_yfloat: y coordinate on which to center the cross

Returns

array: map with oculomotor potential

make_positive(self, u)¶

cuts off negative components

Parameters

uarray: map to cut

Returns

array :: ustar

set_mapsize(self, map_size)¶

Set up the operating grid size for calculation.

Parameters

map_sizeint: size of the internal grid

set_precision(self, data_type)¶

Set up the operating datatype for the whole model. np.float128 is best if you want to make sure the model doesnt run into numerical problems during estimation. Lower precision is faster though.

Parameters

data_typedata-type: datatype to be used for internal calculations

simulate_durations(self, amount)¶

generate durations from gamma distribtion.

Parameters

amountint: number of durations to output

Returns

array: vector of durations

simulate_scanpath(self, dur_path, fix_dens, startpos, get_LL=False)¶

Simulates a scanpath given durations.

Parameters

dur_patharray: array with a datapoint for each fixation’s duration
fix_densarray: empirical fixation density of the viewed image
startpostuple: beginning location for the scanpath in degrees (x, y)
get_LLbool: whether to return the LL of the path

Returns

array: x of the simulated scanpath
array: y of the simulated scanpath
array (optional): likelihood of the simulated scanpath

update_params(self, scene_walk_parameters)¶

Update model parameters

Parameters

scene_walk_parameterslist or dict: scene walk params either as list (not numpy array!) or as dict

Returns

left over parameters when list of the wrong size is passed.

whoami(self)¶: Returns the model identity as a string

window(self, iterable, n_before=1, n_after=1)¶

Sliding window iterator. Returns each element and it’s neighbors. None elelments returned as neighbors at beginning and end.

Parameters

iterablelist-ish: list or other kind of iterable
n_beforeint: number of elements to return before each element
n_afterint: number of elements to return after each element

Returns

iterator: that returns each value in the list and it’s surrounding n