Ratinabox

Bug fixes and implementation of independent `head_direction` variable for the `Agent` class which (by default) is a smoothed version of the velocity vector. The head direction is what is used by `HeadDirectionCells` and `BoundaryVectorCells` (egocentric) etc. to determine firing rate and smoothing can aid stability of processes which rely heavily on these classes.

What's Changed
* Doc file fix by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/51
* Possible fix for issue 52 by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/53
* New RewardCache setting, Verbosity changes, Test functions/scripts by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/59
* env changes, add_hole etc. by TomGeorge1234 in https://github.com/TomGeorge1234/RatInABox/pull/61
* Merge pull request 61 from TomGeorge1234/dev by TomGeorge1234 in https://github.com/TomGeorge1234/RatInABox/pull/62
* Moved OVC initialization steps to methods by colleenjg in https://github.com/TomGeorge1234/RatInABox/pull/65
* Update FieldOfViewNeurons.py by Alxec in https://github.com/TomGeorge1234/RatInABox/pull/67
* TaskEnvironment: option to delay episode terminate by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/68
* flexible head direction by mehulrastogi in https://github.com/TomGeorge1234/RatInABox/pull/72
* fix goal_cache attribute and replenish typos by kushaangupta in https://github.com/TomGeorge1234/RatInABox/pull/74

New Contributors
* Alxec made their first contribution in https://github.com/TomGeorge1234/RatInABox/pull/67
* kushaangupta made their first contribution in https://github.com/TomGeorge1234/RatInABox/pull/74

**Full Changelog**: https://github.com/TomGeorge1234/RatInABox/compare/v1.7.0...v1.8.0

Wrapper: RatInABox now supports OpenAI's `gymnasium` <img src=".images/readme/gymnasium_logo.svg" width=25> API
A new wrapper contributed by [SynapticSage](https://github.com/SynapticSage) allows `RatInABox` to natively support OpenAI's [`gymnasium`](https://gymnasium.farama.org) API for standardised and multiagent reinforment learning. This can be used to flexibly integrate `RatInABox` with other RL libraries such as Stable-Baselines3 etc. and to build non-trivial tasks with objectives and time dependent rewards. Check it out [here](https://github.com/TomGeorge1234/RatInABox/blob/dev/ratinabox/contribs/TaskEnv_example_files/TaskEnvironment_basics.md).

Overhaul of GridCell structure
How `GridCells` are initialised has been restructured. This is mostly backwards compatible and is explained in the GridCell docstring.
To initialise grid cells you specify three things: (i) params['gridscale'], (ii) params['orientation'] and (iii) params['phase_offset']. These are all sampled from a distribution (specified as, e.g. params['phase_offset_distribution']) and then used to calculate the firing rate of each grid cell. For each of these there quantities the value you specify parameterises the distribution from which it is sampled. For example params['gridscale':0.45,'gridscale_distribution':'uniform'] will pull gridscales from a uniform distribution between 0 and 0.45m. The 'delta' distribution means a constant will be taken. For all three of these you can optionally just pass an array of length GridCells.n (in which case the corresponding distribution parameter is ignored). This array is set a the value for each grid cell.

Other minor changes
* Changes to how BVCs are initialised (similar to grid cells)

What's Changed
* Distance tuning by jquinnlee in https://github.com/TomGeorge1234/RatInABox/pull/47
* TaskEnvironment by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/49
* TaskEnvironments: flexible observation space and action_space bug by SynapticSage in https://github.com/TomGeorge1234/RatInABox/pull/50

New Contributors
* jquinnlee made their first contribution in https://github.com/TomGeorge1234/RatInABox/pull/47
* musicinmybrain made their first contribution in https://github.com/TomGeorge1234/RatInABox/pull/48
* SynapticSage made their first contribution in https://github.com/TomGeorge1234/RatInABox/pull/49

**Full Changelog**: https://github.com/TomGeorge1234/RatInABox/compare/v1.6.3...v1.7.0

* Minor bug fixes to how figures are made. Some global params (`MOUNTAIN_PLOT_WIDTH_MM`, `MOUNTAIN_PLOT_SHIFT_MM` etc.) were created to help make figures more uniform across the package.

* A new function was created to help make the process of extracting saved data between any two timestamps a bit easier. Figure plotting has been updated to use this function.


Agent.get_history_slice(t_start, t_end, framerate)
""" "
Returns a python slice() object which can be used to get a slice of history lists between t_start and t_end with framerate. Use case:
>>> slice = get_history_slice(0,10*60,20)
>>> t = self.history['t'][slice]
>>> pos = self.history['pos'][slice]
t and pos are now lists of times and positions between t_start=0 and t_end=10*60 at 20 frames per second

Args:
• t_start: start time in seconds (default = self.history['t'][0])
• t_end: end time in seconds (default = self.history["t"][-1])
• framerate: frames per second (default = None --> step=0 so, just whatever the data frequency (1/Ag.dt) is)
"""


* Some minor QOL improvement and bug fixes (again, mostly to figure plotting stuff).

Note tiny 1 line bug fix over 1.6.2

Thats about it

Official new features
* `SuccessorFeatures()`: New `Neurons` subclass for SRs and accompanying `successor_features_example.ipynb` demo script.
* Ability to visualise multiple `Agents` with `Ag.plot_trajectory(plot_all_agents=True)`
* `PlaceCells.remap()` reinitialises place cell locations
* Minor bug fixes

What's Changed
* Successor features branch by TomGeorge1234 in https://github.com/TomGeorge1234/RatInABox/pull/41
**Full Changelog**: https://github.com/TomGeorge1234/RatInABox/compare/V1.5.1...v1.6.0

Parameter checking
New feature created by colleenjg which checks parameters passed by the user in the `params` dict. It works as follows:

If I initialise, for example, some `GridCells` (a subclass of `Neurons`) then at the point of initialisation of the parent `Neurons` class a check is performed: starting from the child class (`GridCells`) and working upwards to the top-level parent (`Neurons`) a dictionary of all valid default params -- the super set of `GridCells.default_params` and `Neurons.default_params` -- is established. Then, if any of the passed default params is not present in this set a warning is thrown. Example


GCs = GridCells(Ag,{"gridscalee":0.1}) note typo: "gridscale" --> "gridscalee"

returns:


UserWarning: Found 1 unexpected params key(s) while initializing Environment object: 'boundary_conditcions'.
If you intended to set this parameter, ignore this message. To see all default parameters for this class call Environment.get_all_default_params().


It this parameter is a new intended by the user then they can ignore the warning. If not it will help prevent silent errors where parameters were incorrectly defined.

In order for this to work **`default_params` now live as a class attribute and are defined in the preamble before `__init__()`**

Users can query the default params of any class, including those inherited from their parents, by runnings:


GridCells.get_all_default_params()

Just minor changes to plotting stuff e.g. `utils.save_figure()` now usefully prints _where_ a figure/animation is saved any time it does so.