initial commit

Author: emkrause14

.gitignore

@@ -0,0 +1,26 @@
+# data
+*.obj
+*.npy
+*.mat
+*.csv
+*.ai
+results/*
+data/*
+
+# python
+**/__pycache__/*
+**/.ipynb_checkpoints/*
+
+# mac
+.DS_store
+
+# vscode
+.vscode/*
+
+# figures
+*.png
+*.svg
+*.pdf
+
+# poetry
+replay_structure.egg-info/*

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022, Drugowitsch Lab
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,119 @@
+# Replay Spatio-Temporal Dynamics Analysis
+
+This repo contains the code for Krause and Drugowitsch (2022). "A large majority of 
+awake hippocampal sharp-wave ripples feature spatial trajectories with momentum". Neuron. 
+
+This repo uses [Poetry](https://python-poetry.org/docs/) to manage Python dependences.
+
+## Code file structure
+
+`replay_structure` - python files that contain analysis code
+
+`scripts` - python cli scripts for running analysis
+
+`notebooks` - jupyter notebooks for producing the figures in the paper
+
+## High-level overview of analysis pipeline
+
+This code was written for analyzing the dataset from Pfieffer and Foster (2013, 2015).
+Please contact Pfeiffer and Foster for the dataset.
+
+The code is split into modules that house the analysis code (stored in 
+`/replay-structure`), and command line interfaces for running
+the analyses (stored in `/scripts`). The analysis pipeline can roughly be broken down 
+into 3 parts: 
+1. Data preprocessing
+2. Dynamics model analysis
+3. Behavioral analysis
+
+I will briefly describe how the files are interrelated, to hopefully help interpret the
+structure of the code in this repo. 
+I will describe the steps in terms of the cli used to run the analysis, referencing the 
+modules that are implicated in each step.
+
+*Note:* The "dynamics" models described in Krause and Drugowitsch (2022) are referred to 
+in the code as "structure" models. Additionally, the "Gaussian" model is referred to as
+"Stationary Gaussian" in the code.
+
+### Data preprocessing
+
+The Pfieffer and Foster (2013, 2015) dataset is initially loaded and reformatted by 
+running the cli `preproccess_ratday_data.py` (imports the module `ratday.py`). 
+From this initial preprocessing stage, neural data is 
+extracted from SWRs, HSEs, or run snippets by running `preprocess_spikemat_data.py`
+(which imports the modules `ripple_preprocessing.py`,
+`highsynchronyevents.py`, or `run_snippet_preprocessing.py`, respectively, for each
+type of data preprocessing).
+
+Simulated neural data is generated using `generate_model_recovery_data.py` (imports 
+`simulated_trajectories.py`, `simulated_neural_data.py` and `model_recovery.py`).
+
+Running `reformat_data_for_structure_analysis.py` (imports `structure_analysis_input.py`)
+then puts the preprocessed data (SWRs, HSEs, run snippets, and simulated SWRS) into a 
+consistent format for feeding into the dynamics models.
+
+### Dynamics model analysis
+
+
+#### Dynamics models
+
+The dynamics models are implemented in the `structure_models.py` module. The 
+Diffusion and Momentum models both utilize the forward-backward algorithm (Bishop 2006), 
+which is implemented in `forward_backward.py`. 
+
+The dynamics models without parameters that require a parameter gridsearch (
+the Stationary and Random model) are run using the cli `run_model.py`.
+For the dynamics models with parameters (the Diffusion, Momentum, and Gaussian 
+models), we used the Harvard Medical School computing cluster (called o2) to parallelize 
+running the same model many times across a parameter gridsearch (code is stored in
+ `scripts/o2/`). The module `structure_models_gridsearch.py` houses the code for 
+running the dynamics models across a parameter gridsearch.
+
+The cli `run_deviance_explained.py` (imports `deviance_models.py`) calculates the 
+deviance explained of each model for each SWR.
+
+For visualization purposes, the cli `get_marginals.py` (imports `marginals.py`) 
+calculates the position marginals for each dynamics model.
+
+#### Model comparison
+
+Running the dynamics models calculates the model evidence of each model for each SWR.
+Model comparison across the dynamics modes is run using the cli `run_model_comparion.py` 
+(imports `model_comparison.py`). 
+
+#### Trajectory decoding
+
+In addition to identifying the spatio-temporal dynamics of SWRs, we also decoded the 
+most likely trajectories within each SWR. Trajectories are extracted by running 
+`get_trajectories.py` (imports `structure_trajectories.py`). We use the viterbi 
+algorithm (Bishop, 2006) for decoding, which is implemented in `viterbi_algorithm.py`.
+
+
+### Behavioral analysis
+
+The behavioral analysis described in Figures 6 and 7 is run using
+`get_descriptive_stats.py` (imports `descriptive_stats.py`) and
+`run_predictive_analysis.py` (imports `predictive_analysis.py`), respectively.
+
+
+### Other
+
+#### Configuration files
+
+The parameters used in for running the data preprocessing and dynamics models are 
+stored in `config.py`.
+
+The custom Python types for the data type (e.g. ripples, run_snippets),
+session type (e.g. real recording sessions, simulated sessions),
+dynamics model type (e.g. diffusion, stationary, etc.), and
+likelihood type (e.g. poisson, neg_binomial) are defined in `metadata.py`.
+
+#### Implementations of previous methods
+
+The comparison of our dynamics models to the method described 
+in Stella et al. (2019), described in Figure 5, is run using `run_diffusion_constant.py` 
+(imports `diffusion_constant.py`).
+
+We also implemented the decoding method from Pfeiffer and Foster (2013) for
+visualization purposes, which is run using `run_pf_analysis.py` 
+(imports `pf_analysis.py`).