[DOC] - Notes on occupancy related documentation about spiketools

[TomDonoghue]

In the docstring example for compute_occupancy, it is a little confusing that if you read through the values, it's not intuitive that it seems like it drops the last position sample (of 5):

position = np.array([1.0, 1.5, 2.5, 3.5, 5])
timestamps = np.linspace(0, 1, position.shape[0])
compute_occupancy(position, timestamps, bins=[4])
array([0.5 , 0.25, 0.25, 0.  ])

This is ultimately expected (we compute 'time in location' as the diffs of the timestamps, and so there is one last time-value than pos/timestamp value, and the last location is effectively sampled for 0 time (which shouldn't matter in any real data), but is a little unclear it being visible in the example with no note or context given to explain this.

[TomDonoghue]

The description of time_threshold in compute_place_bins doesn't seem to be correct (describes accumulated time threshold, not the time distance threshold for selecting values)

[TomDonoghue]

Passing in a min_speed to compute_occupancy, without passing in speed silently does nothing. Should raise a warning / error for inconsistent set of inputs.

[TomDonoghue]

Docstring could be clearer on difference between min_time / max_time & minimum in compute occupancy functions.

[TomDonoghue]

In compute_trial_occupancy, it will accept and pass through the minimum occupancy parameter, but since, compute_occupancy gets applied every trial, this is a minimum total time per traversal, not overall per bin (across trials). In the case of a fixed path, this means that minimum and min_time parameters are effectively the same. Note that in an open field (with multiple possible traversals per bin within a trial) this is not the case. In both situations, there is not a direct way to threshold based on total time in bin (across trials). This could be added as a posthoc check (which would help align measures of total occupancy vs. trial by trial). Also: consider adding doc notes / warnings about the fixed track situation.