Adaptation of olfactory receptor abundances for efficient coding

This repository contains the code for reproducing all the results from the paper. We also share the data necessary for obtaining our results, with many thanks to the authors of Hallem&Carlson (Cell, 2006), Saito et al. (Science signaling, 2009), and Ibarra-Soria et al. (eLife, 2017) both for collecting the data and for agreeing to share it with us and to allow us to share it on GitHub. More details in the Data sources section below.

Installation

To install, simply clone or download and unzip the compressed repository in a location of your choice. Before using the code for the first time in a Matlab session, run the

setup_paths

script in the root directory. This adds the necessary folders to Matlab's path and must be done every time Matlab is restarted. To avoided possible clashes between functions with the same name, we recommend exiting Matlab to clear the paths before working on a different project.

Usage

All the scripts and functions in the repository have documentation that can be accessed using the help command. For instance,

help run_dyn_model

will display information about how to run a simulation of the dynamical model described in our paper.

However, the easier way to get started is by looking at some examples. The script make_generic_plots.m is a great starting point because it showcases the most important components of our code in a simple example, while also generating some of the plots that made it into the paper. The analyze_Ktot_dependence.m is a good follow-up. The scripts analyze_dynamical_model.m and analyze_nonlinear_example.m are interesting because they use parts of the code (the dynamical model and the nonlinear model, respectively) that are distinct from what is used in the other scripts.

In general, the paper/ folder contains scripts that were used to generate all the plots in the paper, but many rely on results files that are generated by scripts from analysis/.

To go into a bit more detail about the organization of the code, the main functions are

• calculate_optimal_dist.m (which calculates the optimal receptor distribution using our linear model)
• run_dyn_model.m (which runs the dynamical model described in our paper)
• calculate_info_nonlinear.m (which estimates the mutual information for the case of a nonlinear response model)

The generate_random_sensing.m and generate_environment.m scripts are used to generate artificial sensing matrices and environment covariance matrices, respectively.

Finally, the scripts in graphing are utilities that facilitate the production of plots, while the scripts in utils are more general-purpose routines.

Data sources

Along with the code, this repository also contains data needed to generate our results. This data was obtained by other groups and was generally lightly processed by us for easier use in Matlab scripts, as described below. We are very thankful to the authors for agreeing to allow us to share this data. We emphasize that we are responsible for converting the data from the original formats to Matlab files and thus we are responsible for any errors that might have occurred during this conversion.

• Drosophila olfactory receptor affinity data from Hallem&Carlson (Cell, 2006)
  • we obtained an Excel file of receptor-odorant affinities from the authors, matching Table S1 in the supplementary information of their paper; this file contained the exact firing rate values obtained from the data, without the rounding to integers that occurs in that Table
    • we exported this file to a CSV after separating out the OR names, odorant names, and background activity rates
    • we then combined these into a structure in a Matlab .mat file
  • we also obtained individual Excel files for each OR from the authors
    • from these files we only used the information about background rates
    • we calculated the standard deviation of the background rates and added this as another field in the Matlab .mat file
  • we saved all this data in the data/flyResponsesWithNames.mat file
  • we confirmed with the authors on Feb. 11, 2019 that we can share our .mat file on GitHub
• human and mouse olfactory receptor affinity data from Saito et al. (Science signaling, 2009)
  • we obtained from the authors the response curves for 62 mouse and human receptors against a panel of odorants at a range of concentration values
    • the files were in GraphPad Prism format and we used the trial version of the software to export them to CSV
    • we then used a Python script to parse the data and convert it to a Matlab file, under data/mouse_receptor_curves.mat
  • we confirmed with the authors on Jan. 24, 2019 that we can share our .mat file on GitHub
• expression levels of OR genes measured in control and exposed mice from Ibarra Soria et al. (eLife, 2017)
  • we used the source data from Figure 5 in the paper
    • we exported the data from Excel to CSV
    • parsed the data and plotted it using an iPython notebook, analysis/visualize_ibarra_soria.ipynb
  • the article was published under a Creative Commons license that explicitly allows for unrestricted use and redistribution of the contents