Merge pull request #95 from paxtonfitzpatrick/master

links to live paper

README.md

@@ -1,23 +1,37 @@
-# Geometric models reveal behavioral and neural signatures of transforming naturalistic experiences into episodic memories
+# Geometric models reveal behavioural and neural signatures of transforming naturalistic experiences into episodic memories
 
-This repository contains data and code used to produce the paper "[_Geometric models reveal behavioral and neural signatures of transforming naturalistic experiences into episodic memories_](https://www.biorxiv.org/content/10.1101/409987v3)" by Andrew C. Heusser, Paxton C. Fitzpatrick, and Jeremy R. Manning. The repository is organized as follows:
+<p align="center"
+  <a href="https://www.nature.com/articles/s41562-021-01051-6">
+    <img src="https://img.shields.io/badge/paper-Nature%20Human%20Behaviour-blue.svg" alt="Paper (Nature Human Behaviour)">
+  </a>
+  <a href="https://rdcu.be/cfsYs">
+    <img src="https://img.shields.io/badge/paper-PDF-blue.svg" alt="Paper (Direct PDF link)">
+  </a>
+  <a href="https://socialsciences.nature.com/posts/how-is-experience-transformed-into-memory">
+    <img src="https://img.shields.io/badge/Behind%20the%20Paper-blog%20post-blue.svg" alt="Behind the Paper (blog post)">
+  </a>
+</p>
 
-```
+This repository contains data and code used to produce the paper "[_Geometric models reveal behavioural and neural signatures of transforming naturalistic experiences into episodic memories_](https://rdcu.be/cfsYs)" by Andrew C. Heusser, Paxton C. Fitzpatrick, and Jeremy R. Manning.
+
+The repository is organized as follows:
+
+```yaml
 root
-├── code : all code used in the paper
+├── code : all analysis code used in the paper
 │   ├── notebooks : Jupyter notebooks for paper analyses
-│   ├── scripts : python scripts used to perform various analyses on a cluster
-│   │   ├── embedding : scripts used to optimize the UMAP embedding for the trajectory figure
-│   │   └── searchlights : scripts used to perform the brain searchlight analyses
-│   └── sherlock_helpers : package with assorted helper functions and variables for analyses
-├── data : all data used in the paper
-│   └── raw : raw data before processing
+│   ├── scripts : Python scripts for running analyses on a HPC cluster (Moab/TORQUE)
+│   │   ├── embedding : scripts for optimizing the UMAP embedding for the trajectory figure
+│   │   └── searchlights : scripts for performing the brain searchlight analyses
+│   └── sherlock_helpers : Python package with support code for analyses
+├── data : all data analyzed in the paper
+│   └── raw : raw video annotations and recall transcripts
 │   └── processed : all processed data
 └── paper : all files to generate paper
-    └── figs : pdf copies of each figure
+    └── figs : pdf copies of all figures
 ```
 
-We also include a Dockerfile to reproduce our computational environment. Instruction for use are below (copied and modified from the [MIND](https://github.com/Summer-MIND/mind-tools) repo):
+We also include a `Dockerfile` to reproduce our computational environment. Instruction for use are below (copied and modified from the [MIND](https://github.com/Summer-MIND/mind-tools) repo):
 
 ## One time setup
 1. Install Docker on your computer using the appropriate guide below:
@@ -26,7 +40,7 @@ We also include a Dockerfile to reproduce our computational environment. Instruc
     - [Ubuntu](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/)
     - [Debian](https://docs.docker.com/engine/installation/linux/docker-ce/debian/)
 2. Launch Docker and adjust the preferences to allocate sufficient resources (e.g. >= 4GB RAM)
-3. To build the Docker image, open a terminal window, navigate to your local copy of the repo, and enter `docker build -t sherlock .`  
+3. To build the Docker image, open a terminal window, navigate to your local copy of the repo, and run `docker build -t sherlock .`  
 4. Use the image to run a container with the repo mounted as a volume so the code and data are accessible.
     - The command below will create a new container that maps the repository on your computer to the `/mnt` directory within the container, so that location is shared between your host OS and the container. Be sure to replace `LOCAL/REPO/PATH` with the path to the cloned repository on your own computer (you can get this by navigating to the repository in the terminal and typing `pwd`).  The below command will also share port `9999` with your host computer, so any Jupyter notebooks launched from *within* the container will be accessible at `localhost:9999` in your web browser
     - `docker run -it -p 9999:9999 --name Sherlock -v /LOCAL/REPO/PATH:/mnt sherlock `

code/notebooks/main/searchlight_analyses.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This notebook replicates the brain-related analyses. Note: the fMRI data can be downloaded into the data folder from here: https://dataspace.princeton.edu/jspui/handle/88435/dsp01nz8062179"
+    "This notebook loads the output of the searchlight analyses run using the scripts in [`code/scripts/searchlights`](https://github.com/ContextLab/sherlock-topic-model-paper/tree/master/code/scripts/searchlights). The fMRI data used in the searchlight analyses can be downloaded using the script at [`code/scripts/download_neural_data.sh`](https://github.com/ContextLab/sherlock-topic-model-paper/blob/master/code/scripts/download_neural_data.sh)."
    ]
   },
   {

code/notebooks/main/searchlight_figs.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note: This notebook loads in some data from the fMRI dataset collected by Chen et al. (2017). If you want to run this notebook, you can download the dataset using script at code/helpers/download_neural_data.sh."
+    "Note: This notebook loads in some data from the fMRI dataset collected by Chen et al. (2017). If you want to run this notebook, you can download the dataset using the script at [`code/scripts/download_neural_data.sh`](https://github.com/ContextLab/sherlock-topic-model-paper/blob/master/code/scripts/download_neural_data.sh)."
    ]
   },
   {