Example Usage Instructions

The software has default settings included so that a user should be able to download and just run it without changing any settings to see an example of its results. A user will need to supply either a rate map of grid cell firing in a 32x32 pixel matrix or an autocorrelogram in a 63x63 pixel matrix (with use_ac set to 1) to run the software on a user’s new data. The configuration option convert_to_ac is supplied to convert a rate map matrix into an autocorrelogram matrix if that is wanted. The matrix should be stored as a plain text file.

In gridcell_metrics.m, the user should enter the file path to their matrix file in the variable plot_filepath. The software comes with a variety of example rate maps and autocorrelograms in .mat binary format. If those binary files are used as matrix input then the option use_binary_input should be set to 1.

The software includes multiple parameters in config.txt. A user should run run_config_convert_linux.sh or run_config_convert_win.bat to generate run_gridcell_metrics_with_config.sh or run_gridcell_metrics_with_config.bat. The run_gridcell_metrics scripts run the runtime software with configuration options set in config.txt. A user should copy the command line arguments from the run_gridcell_metrics scripts into run_gridcell_metrics.m to use the arguments when running the software from source code in MATLAB instead of using the runtime file.
One available configuration parameter is px2cm, and this specifies what number of centimeters each pixel in the matrix represents, and this is used for statistics reporting. Another parameter is nonfld_filt_perc, and this parameter sets the percentage of non-grid-field firing to filter out. Non-grid-field firing is approximated by a set percentage firing level that is below the peak firing level. For example, if the peak firing rate was 4 spikes per second, a 0.31 threshold would filter out firing that is below 4*.31=1.24 spikes per second. Suggested threshold are covered in a section below.

The software can be run (from the source code) by clicking the run button in Matlab while the run_gridcell_metrics.m script is open in the editor window. Optional parameters in config.txt include use_ac, and this sets if the program should process a rate map or autocorrelogram. Plotting setting include plot_fields_detected and plot_orig_firing. These should be set to show the detected field and/or the original firing plot (rate map or autocorrelogram). The runtime version of the software is downloadable in the releases section of the Github page. A user can launch the runtime version of the software using config.txt parameters with the run_gridcell_metrics .sh or .bat scripts.

Statistics will be printed in the commend prompt once the program is run. They are also saved in metric_results.csv by default. These statistics include mean field size, spacing, and angle measurements. Matching centroid number is the centroid from the detected grid field with the smallest angle to the center field. Grid fields reported are the number of grid fields included in analyses and does not take into account any manually excluded fields. Grid fields filtered out is the number of grid fields beyond the “grid fields reported” that were filtered out. Any plots set in parameters to appear will be displayed. If print_angles is set to 1 a list of angles between fields will be printed and a histogram of angles will be shown.

Suggested nonfld_filt_perc thresholds

The threshold found have the best performance in (R. G. et al., 2024) was 31%. Users can test different thresholds with that threshold as a suggested starting point. Smaller thresholds can detect larger field areas but are at risk of unwanted merging of fields with neighboring fields. Larger fields can better avoid that risk but detect smaller field areas, and in some cases not detect fields because of the increased firing rate filtering.

References

R. G., R., Ascoli, G. A., Sutton, N. M., & Dannenberg, H. (2024). Spatial periodicity in grid cell firing is explained by a neural sequence code of 2-D trajectories. eLife, 13.