Update 'README.md'

README.md

@@ -1,2 +1,44 @@
-# sensorium_2023_dataset
+
+
+# Data for the <a href="https://www.sensorium-competition.net">Sensorium2023</a> competition
+
+
+**!!! Note: GIN does not support bulk downloads. You need to download the files individually !!!**
+
+Previous dataset - you can use it additionally - <a href="https://gin.g-node.org/pollytur/Sensorium2023Data">Link</a> 
+
+# Dataset Structure
+
+Below we provide a brief explanation of the dataset structure and how to access all the information contained in them.
+
+Have a look at our white paper for in depth description of the data. [White paper on arXiv](https://arxiv.org/abs/2305.19654)
+
+We provide the datasets in the .zip format. Unzipping them will create two folders **data** and **meta**.
+
+- **data:** includes the variables that were recorded during the experiment. The experimental variables are saved as a collection of numpy arrays. Each numpy array contains the value of that variable at a specific image presentation (i.e. trial). Note that the name of the files does not contain any information about the order or time at which the trials took place in experimental time. They are randomly ordered.
+  - **videos:** This directory contains NumPy arrays where each single `X.npy` contains the video that was shown to the mouse in trial `X`.
+  - **responses:** This directory contains NumPy arrays where each single `X.npy` contains the deconvolved calcium traces (i.e. responses) recorded from the mouse in trial `X` in response to the particular presented image.
+  - **behavior:** Behavioral variables include pupil dilation and running speed. The directory contain NumPy arrays (of size `1 x 2`) where each single `X.npy` contains the behavioral variables (in the same order that was mentioned earlier) for trial `X`.
+  - **pupil_center:** the eye position of the mouse, estimated as the center of the pupil. The directory contain NumPy arrays (of size `1 x 2`) for horizontal and vertical eye positions.
+- **meta:** includes meta data of the experiment
+    - **neurons:** This directory contains neuron-specific information. Below are a list of important variables in this directory
+        - `cell_motor_coordinates.npy`: contains the position (x, y, z) of each neuron in the cortex, given in microns. **Note:** The
+    - **statistics:** This directory contains statistics (i.e. mean, median, etc.) of the experimental variables (i.e. behavior, images, pupil_center, and responses).
+      - **Note:** The statistics of the responses are or particular importance, because we provide the deconvolved calcium traces here in the responses.
+      
+        However, for the evaluation of submissions in the competition, we require the responses to be **standardized** (i.e. `r = r/(std_r)`).
+        
+    - **trials:** This directory contains trial-specific meta data. 
+       
+        - `tiers.npy`: contains labels that are used to split the data into *train*, *validation*, and *test* set
+          - The *training* and *validation* split is only present for convenience, and is used by our ready-to-use PyTorch DataLoaders.
+          - The *test* set is used to evaluate the model preformance. In the competition datasets, the responses to all *test* images is withheld.
+     
+# License
+This data is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/4.0/">Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License</a>. This license requires that you contact us before you use the data in your own research. In particular, this means that you have to ask for permission if you intend to publish a new analysis performed with this data (no derivative works-clause).
+
+<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/4.0/"><img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-nd/4.0/88x31.png" /></a>
+
+
+