Skip to content

Commit

Permalink
Merge pull request #85 from SainsburyWellcomeCentre/style-guide
Browse files Browse the repository at this point in the history 
Style guide
  • Loading branch information
@ClementineDomine
ClementineDomine authored Aug 17, 2023
2 parents 2fd4037 + 573e0c5 commit fdebbff
Showing 1 changed file with 200 additions and 1 deletion.
201 changes: 200 additions & 1 deletion documents/style_guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Style Guide
# Style Guide

We are following to the best of our abilities the [PEP8](https://www.python.org/dev/peps/pep-0008/) and [numpy docstring](https://numpydoc.readthedocs.io/en/latest/format.html) style convention. Note: Pycharm has an inbuild checking framework that will help you follow the style guide.
The pre-commit bot will enforces these style guide requierements.
Expand Down Expand Up @@ -335,3 +335,202 @@ Additionally your class will also inherit the necessary methods that the rest of
> - Description: Number of time steps maintained in the render of the history.
> - Returns: None
> - Description: Render the environment live through iterations.
## Experiment <!-- A bunch of the links below that I copied from the readme go to clem's user and not SWCs -->
Implementing a style format for experimental classes is more complex due to the wide variety of data formats and experimental setups. For consistency and ease of future development, when creating a new experimental class the `Experiment` class should be inherited from "experiment_core.py". However, for the moment this class remains empty and provides no variables or functionality. It then becomes key that the steps described in [How To Contribute](https://github.com/SainsburyWellcomeCentre/NeuralPlayground/tree/main/neuralplayground/experiments#3-how-to-contribute) are followed. In particular providing a minimal example of the functionality offered by the class in [Examples](https://github.com/ClementineDomine/NeuralPlayground/tree/main/examples/experimental_examples/) is very important. This allows for future developers to easily use the class (without having a base class available to extrapolate from) but also to find similarities between experimental classes. For example [Hafting2008Data](https://github.com/ClementineDomine/NeuralPlayground/blob/main/neuralplayground/experiments/hafting_2008_data.py) offers a simple class for 2D Experimental data. Consequently our implementation of [Sargolini2006Data](https://github.com/ClementineDomine/NeuralPlayground/blob/main/neuralplayground/experiments/sargolini_2006_data.py) inherits from [Hafting2008Data](https://github.com/ClementineDomine/NeuralPlayground/blob/main/neuralplayground/experiments/hafting_2008_data.py). This is ideal and aligns well with the motivation of this package - to begin to standardise the presentation and interface with neuroscience research. For the purpose of example we will describe the style of [Hafting2008Data](https://github.com/ClementineDomine/NeuralPlayground/blob/main/neuralplayground/experiments/hafting_2008_data.py).

### hafting_2008_data.py
The original article of Hafting et al. 2008. can be found at https://www.nature.com/articles/nature06957. The data can be obtained from https://archive.norstore.no/pages/public/datasetDetail.jsf?id=C43035A4-5CC5-44F2-B207-126922523FD9. This class only consider animal raw animal trajectories and neural recordings.

The class does not contain its own attributes and only provides functions which interface with the data. These functions are:
> * `__init__( )`
> - Accepts:
> - `data_path` : *str*
> - Default: `None`
> - Description: If `None` then fetch the data from the NeuralPlayground data repository, else load data from the given path.
> - `recording_index` : *int*
> - Default: `None`
> - Description: If `None` then load data from default recording index.
> - `experiment_name`: *str*
> - Default: "FullHaftingData"
> - Description: A string to identify the object in case multiple instances of the class are being used.
> - `verbose`: *bool*
> - Default: `False`
> - Description: If `True` then it will print original readme and data structure when initializing this object.
> - Returns: None
> - Description: Function which initialises an object of the class. Providing no inputs will default the object to reload the dataset from the repositories.
>
> * `set_animal_data()`
> - Accepts:
> - `recording_index`: *int*
> - Default: `0`
> - Description: Provides a unique digit for the recording.
> - `tolerance`: *float*
> - Default: `1e-10`
> - Description: Degree of allowable deviation or variance when calculating the head direction.
> - Returns: `None`
> - Description: Set position and head direction of the animal to be used by an Arena-based class later.
>
> * `_find_data_path()`
> - Accepts:
> - `data_path`: *str*
> - Default: `None`
> - Description: File path to data.
> - Returns: `None`
> - Description: Fetch data from NeuralPlayground data repository if no data path is supplied by the user or fetches the data from the path.
>
> * `_load_data()`
> - Accepts: `None`
> - Returns: `None`
> - Description: Parse data according to specific data format. If you are a user check the notebook examples.
>
> * `_create_dataframe()`
> - Accepts: `None`
> - Returns: `None`
> - Description: Generates dataframe for easy display and access of data.
>
> * `show_data()`
> - Accepts:
> - `full_dataframe`: *bool*
> - Default: `False`
> - Description: If True then it will show all available data, a small sample otherwise
> - Returns:
> - `recording_list`: *Pandas dataframe*
> - Description: List of available data, columns with rat_id, recording session and recorded variables
> - Description: Print of available data recorded in the experiment.
>
> * `show_readme()`
> - Accepts: `None`
> - Returns: `None`
> - Description: Print original readme of the dataset.
>
> * `get_recorded_session()`
> - Accepts:
> - `recording_index`: *int*
> - Default: `None`
> - Description: Recording identifier, index in pandas dataframe with listed data
> - Returns:
> - `rat_id`: *str*
> - Description: The rat identifier from experiment
> - `sess`: *str*
> - Description: The recording session identifier from experiment
> - `recorded_vars`: *list of str*
> - Description: Variables recorded from a given session
> - Description: Get identifiers to sort the experimental data.
>
> * `get_recording_data()`
> - Accepts:
> - `recording_index`: *int*
> - Default: `None`
> - Description: The recording identifier - an index in the pandas dataframe with listed data
> - Returns:
> - `session_data`: *dict*
> - Description: Dictionary with recorded raw data from the session of the respective recording index. Format of this data follows original readme from the authors of the experiments.
> - `rec_vars`: *list of str*
> - Description: The keys of session_data dict and recorded variables for a given session
> - `identifiers`: *dict*
> - Description: Dictionary with rat_id and session_id of the returned session data
> - Description: Get experimental data for a given recordin index.
>
> * `_find_tetrode()`
> - Accepts:
> - `rev_vars`: *list of strings*
> - Description: The recorded variables for a given session, tetrode id within it
> - Returns:
> - `tetrode_id`: *str*
> - Description: The first tetrode id which is found in the recorded variable list.
> - Description: Static function to find tetrode id in a multiple tetrode recording session.
>
> * `get_tetrode_data()`
> - Accepts:
> - `session_data`: *str*
> - Default: `None`
> - Description: If None the the session used corresponds to the default recording index
> - `tetrode_id`: *str*
> - Default: `None`
> - Description: The tetrode id in the corresponding session
> - Returns:
> - `time_array`: *ndarray*
> - Description: The array with the timestamps in seconds per position of the given session.
> - `test_spikes`: *ndarray*
> - Description: The spike times in seconds of the given session.
> - `x`: *ndarray*
> - Description: The x position throughout recording of the given session.
> - `y`: *ndarray*
> - Description: The y position throughout recording of the given session.
> - Description: Return time stamp, position and spikes for a given session and tetrode.
>
> * `plot_recording_tetr()`
> - Accepts:
> - `recording_index`: *int, tuple of ints, list of ints*
> - Default: `None`
> - Description: The recording index to plot spike ratemap, if list or tuple, it will recursively call this function to make a plot per recording index. If this argument is list or tuple, the rest of variables must be list or tuple with their respective types, or keep the default None value.
> - `save_path`: *str, list of str, tuple of str*
> - Default: `None`
> - Description: The saving path of the generated figure. If None then no figure is saved
> - `ax`: *mpl.axes._subplots.AxesSubplot, list of ax, or tuple of ax*
> - Default: `None`
> - Description: An axis or list of axis from subplot from matplotlib where the ratemap will be plotted. If None, ax is generated with default options.
> - `tetrode_id`: *str, list of str, or tuple of str*
> - Default: `None`
> - Description: tetrode id in the corresponding session.
> - `bin_size`: *float*
> - Default: `2.0`
> - Description: The bin size to discretize space when computing ratemap
> - Returns:
> - `h`: *ndarray (nybins, nxbins)*
> - Description: Number of spikes falling on each bin through the recorded session, nybins number of bins in y axis, nxbins number of bins in x axis (returned as list or tupe depending on the argument type).
> - `binx`: *ndarray (nxbins +1,)*
> - Description: The bin limits of the ratemap on the x axis (returned as list or tupe depending on the argument type).
> - `biny`: *ndarray (nybins +1,)*
> - Description: The bin limits of the ratemap on the y axis (returned as list or tupe depending on the argument type).
> - Description: Plot tetrode ratemap from spike data for a given recording index or a list of recording index. If given a list or tuple as argument, all arguments must be list, tuple, or None.
>
> * `plot_trajectory()`
> - Accepts:
> - `recording_index`: *int, tuple of ints, list of ints*
> - Default: `None`
> - Description: The recording index to plot spike ratemap, if list or tuple, it will recursively call this function to make a plot per recording index. If this argument is list or tuple, the rest of variables must be list or tuple with their respective types, or keep the default None value.
> - `save_path`: *str, list of str, tuple of str*
> - Default: `None`
> - Description: The saving path of the generated figure. If None then no figure is saved
> - `ax`: *mpl.axes._subplots.AxesSubplot, list of ax, or tuple of ax*
> - Default: `None`
> - Description: An axis or list of axis from subplot from matplotlib where the ratemap will be plotted. If None, ax is generated with default options.
> - `plot_every`: *int*
> - Default: `20`
> - Description: The number of time steps skipped to make the plot to reduce cluttering.
> - Returns:
> - `x`: *ndarray (n_samples,)*
> - Description: The x position throughout recording of the given session.
> - `y`: *ndarray (n_samples,)*
> - Description: The y position throughout recording of the given session.
> - `time_array`: *ndarray (n_samples,)*
> - Description: An array with the timestamps in seconds per position of the given session.
> - Description: Plot of the animal trajectory from a given recording index, corresponding to a recording session.
>
> * `recording_tetr()`
> - Accepts:
> - `recording_index`: *int, tuple of ints, list of ints*
> - Default: `None`
> - Description: The recording index to plot spike ratemap, if list or tuple, it will recursively call this function to make a plot per recording index. If this argument is list or tuple, the rest of variables must be list or tuple with their respective types, or keep the default None value.
> - `save_path`: *str, list of str, tuple of str*
> - Default: `None`
> - Description: The saving path of the generated figure. If None then no figure is saved
> - `tetrode_id`: *str, list of str, or tuple of str*
> - Default: `None`
> - Description: tetrode id in the corresponding session.
> - `bin_size`: *float*
> - Default: `2.0`
> - Description: The bin size to discretize space when computing ratemap
> - Returns:
> - `h`: *ndarray (nybins, nxbins)*
> - Description: Number of spikes falling on each bin through the recorded session, nybins number of bins in y axis, nxbins number of bins in x axis (returned as list or tupe depending on the argument type).
> - `binx`: *ndarray (nxbins +1,)*
> - Description: The bin limits of the ratemap on the x axis (returned as list or tupe depending on the argument type).
> - `biny`: *ndarray (nybins +1,)*
> - Description: The bin limits of the ratemap on the y axis (returned as list or tupe depending on the argument type).
> - Description: The tetrode ratemap from spike data for a given recording index or a list of recording index. If given a list or tuple as argument, all arguments must be list, tuple, or None.
The example usage of this class can then be found in the ["experimental_data_examples.ipynb"](https://github.com/SainsburyWellcomeCentre/NeuralPlayground/blob/main/examples/experimental_examples/experimental_data_examples.ipynb) notebook as per the instructions on adding an experimental class. <!-- this example notebook should probably be improved if we say people must make clear examples to add an experimental class -->

0 comments on commit fdebbff

Please sign in to comment.