# Instructions This project repository contains all the files related to the project "It’s new, but is it good? How generalization and uncertainty guide the exploration of novel options" by Hrvoje Stojić, Eric Schulz, Pantelis P. Analytis and Maarten Speekenbrink. Public version can be found at Open Science Framework, at the following [link](https://osf.io/c8u9t/). Licences for using the code, data and other materials in this repository: see `LICENSE` file. ## Corresponding author If you have questions about the files in this repository or find some errors, please get in touch with Hrvoje Stojić the main author of the documentation. You can find my updated contact details at [ORCID profile](https://orcid.org/0000-0002-9699-9052). ## Organization of the files Directories with **c** prefix contain code for running various types of analyses. There is a designated directory `cSimulations` with the code related to simulating the models, a directory `cCleaning` with the code that process the raw data, a directory `cFigs` with the code that produces figures, and a directory `cAnalysis` with the code that analyses the behavioral data, performs tests etc. Directories with **d** prefix contain data. Raw behavioral data from the experiments is in `dRaw` directory, while in `dProcessed` directory we save the output from simulations, model fits and processed raw behavioral data. Note that we provide data from model simulations even though it can be reproduced exactly, as it takes substantial amount of time. We don't provide the model fitting output from `cAnalysis/hierBinomial.R` as it is too large. Directory `pManuscript` contains the article, together with the source LaTeX and Bibtex files. There are few other specific directorys: `figs` contains all the figures produced by code in `cFigs` while `fisgOthers` contains figures not generated by code. `tables` contains all the output from the analysis code in `cAnalysis`, these are largely results from the statistical tests reported in the artice. `exp` contains all the files related to the experiment, from the experimental stimuli to experimental software and instructions used during the experiment. Each directory contains additional README file if additional details are needed on using the files contained in it. In README files in **c** directories you can find detailed information about the software dependencies, in case you wish to execute the code, but see also the section below on this topic. ## Dependencies The project was completed using Linux operating system and some tools rely on Unix environment. More specifically, I have used Ubuntu 18.04 Linux operating system. For example, `GNU make` that I mention below is a program that comes on most Linux distributions by default. Note that Mac OS is Unix based and it should have them as well, or they are easily installed. Hence, if you are attempting to use the files on a Windows system or follow the instructions, I cannot provide much guidance. For simulations and producing figures we have relied on R and matlab, together with several R packages and matlab libraries. If you wish to execute the code, you should first visit [R website](https://www.r-project.org/) and read in more details there how to install R on your computer (I recommend [RStudio](https://www.rstudio.com/) as a nice user interface for R). For GP-UCB model simulations only you will also need [matlab](https://uk.mathworks.com/products/matlab.html) and [GPML matlab library](http://www.gaussianprocess.org/gpml/code/matlab/doc/). In README files in **c** directories you can find detailed information about the packages used to execute the code contained within the directory. Note that exact package versions are listed for which you should get the same results. If you will have newer/older versions installed, some code might not run at all. Software for the experiment was programmed in JavaScript and HTML, using [jsPsych library](http://www.jspsych.org/). There is no need to install anything, regular browser should suffice. However, since experiment is designed for usage on Amazon Turk (AMT) online labour market and we use [Psiturk](https://psiturk.org/) Python library to interact with the AMT, to actually use the software yourself you will need to install Python (if you are on Unix machine you should have Python available already) and Psiturk (check the documentation on the link provided). More detail is available in the README file in `exp` directory. For compiling the manuscript, you will need a (full) LaTeX installation on your computer. For guidance on installing required libraries on your operating system, see for example this [wikibooks](https://en.wikibooks.org/wiki/LaTeX/Installation) entry. Operating System on which the code was developed and tested: ```{bash} Linux hfunk 4.16.0-041600rc4-generic #201803041930 SMP Mon Mar 5 00:32:34 UTC 2018 x86_64 x86_64 x86_64 GNU/Linux ``` ## Usage We rely on `GNU make` files to automatize certain things. For example, to produce all the figures required for the article, one can simply open terminal in `cFigs` folder and execute `make` command. I tried documenting how to use each folder, if it was necessary, with README files. Finally, there is a makefile at the top level, where this README file resides, that you can use to clean the behavioral data, perform the analyses, produce the figures and compile the article with a single `make` call. Whether this will succeed depends on your operating system and whether all dependencies are satisfied. Note that simulations and hierarchical Bayesian model fitting require substantial amount of time to complete - at least a week on an ordinary personal computer. On a more powerful 16 core machine it takes about 1 day. Hence, if you wish to rerun the simulations and perform model fitting, you are welcome to do so, but bear in mind the time they will need to complete.