cognate-beginnings

We recommend two ways of reproducing or inspecting the code of this repository. One option is to clone the Docker image we have pused to Dockerhub. A Docker image is just a virtual machine that contains all dependencies, code, and files necessary to run the code. Everything is already installed and setup, you will only have to open http://localhost:8787 in your browser, and a RStudio session will open for you. This option is more robust (dependencies are difficult to get right when using your own computer), but it also requires Docker to be installed.

A second option is the more traditional approach of downloading the repository (or cloning it, if you know your way through Git/GitHub), installing the necessary dependencies (we recommend using renv for R dependencies, other system dependencies are listed below), and running the code (we recommend using the targets workflow).

Docker

Download and install Docker (Windows, Mac, Linux)
Pull the gongcastro/cognate-beginnings image. Two ways of doing this:
1. Using the Docker CLI: open your console/terminal/command prompt, and run:
```
docker pull gongcastro/cognate-beginnings
```
1. Using the Docker Desktop app: go the “Images” tab, click on “Search images to run”, search for “gongcastro/cognate-beginnings”, and click “Pull”.
Run the image in a Docker container. Two ways of doing this:
1. Using the Docker Desktop app: in the “Images” tab, look for the gongcastro/cognate-beginnings image and click “Run”.
2. Using the Docker CLI:
```
docker run --rm -ti -e ROOT=true -e PASSWORD=rstudio -p 8787:8787 --name rstudio gongcastro/cognate-beginnings:latest
```
Open http://localhost:8787 in your browser. Log in using rstudio as user, and rstudio as password. An RStudio session should open, with all files, code and dependencies installed and ready. To retrieve and explore a given object, run targets::tar_load(target_name), where target_name is the name of the rarget you want to explore (e.g., targets::tar_load(items)).

💡 The RStudio session opened by Docker does not have root permissions (you will not be able to run targets::tar_make() to run the code from the R console). Instead, open the “Terminal” tab, and run sudo Rscript -e "targets::tar_make()". The targets workflow should now be triggered.

💡 The targets workflow is run to completion before your Rstudio session is open in Docker. This means that even if you trigger targets::tar_make(), virtually all targets will be skipped, as they are completed. If you want to run a specific target, delete it first (or any other target it depends on), and the targets workflow will be run, now generating all deleted targets again. Be aware that this might take some time, especially when fitting the models anew.

GitHub

Download this repository
Install software dependencies
Install package dependencies with renv
Running the code with targets
Repository structure and files

0. Download this repository ⬇️

First, you will need to download this repository to your local machine. We suggest three different ways:

Git terminal: download and install Git with default settings and clone this repository locally running the following command in your console:

git clone https://github.com/gongcastro/cognate-beginnings.git

💡 You don’t need to run this command from the Git console. Just open Command Prompt or Power Shell in Windows (just make sure that Git is included in your PATH variables, which should be already done after the recommended Git installation), Terminal in MacOS, or command line in Linux and run this command.

GitHub releases: download the latest release of the repository.
Direct download: click the green button “Code” in this page (upper-right corner), click “Download ZIP”, and unzipping the downloaded repository.

1. Install software dependencies 💻

Here’s a list of programs that you might need to install in your machine to make the project work:

R (4.2.2 or greater)
RStudio: although not strictly necessary, we encourage the use of Rstudio for reproducing the present project. We have not tested the reproducibility of the project in other IDEs.
Quarto (1.3.340 or greater): we use this software to generate the manuscript and lab notes. We recommend installing version 1.3.340 or higher, although previous version might work as well.
Rtools (4.3 or greater).
CmdStan (2.31.0 or greater): we use the CmdStan backend in brms to fit our Bayesian models. We recommend installing CmdStan using its R interface CmdStanR following the Getting started with CmdStanR vignette. You can also install it following the CmdStan installation guide, and then letting CmdStanR know the path to the folder using cmdstanr::set_cmdstan_path().

💡 Installing CmdStan is sometimes inconvenient, and might require some time to set up, specially if it’s your first time doing so. Have patience and follow the CmdStan installation guide closely. If you encounter problems and just don’t have the time, you can download the models from the Open Science Framework repository and skip the model-fitting steps.

2. Install package dependencies with renv 📦

Open the downloaded repository folder and click on the cognate-beginnings.Rproj to open an RStudio session (recommended) or just open an R session and set the working directory to the downloaded folder. Once open run:

install.packages("renv") # in case you need to install renv
renv::restore()

This might take a couple of minutes, depending on the number of packages that need installation or an update.

💡 What does this step do? The code in this repository needs some packages to run, many of which might not have been already installed in your local machine. Instead of having to install them yourself one by one or updating already installed ones (which might change how they behave, possibly breaking some of your code in other projects) this repository uses the R package renv to deal with package libraries. The command renv::restore() will install all necessary packages in the appropriate version (listed in the file renv.lock in a self-contained R package library. This process will not affect the packages that you had already installed in your machine.

💡 Something went wrong with renv. Now what? Although renv facilitates the reproducibility of the repository, it is not guaranteed that things will work perfectly. If you encounter trouble installing the packages using renv, try installing them individually using (install.packages() or renv::install()) and try fixing whatever issues arise (they might depend on your particular setup). Some packages are used by RStudio itself, and might refiuse to update them while you’re using RStudio. Try installing them from the R console outside of RStudio. Open an issue on this repository if you need further assistance! We’ll get back to you ASAP. :smile:

3. Running the code with targets 🚀

Once the package dependencies have been solved with renv, run the following command:

targets::tar_make()

Mind that this process might take some time. Refitting the brms models might take very long (days even, depending on your set-up). If you want to skip this step, download the “results” folder in the Open Science Framework repository and replace it in the repository.

💡What does this step do? This repository’s workflow is based on targets. This means that the code is run in the appropriate order according to its internal dependencies. The code is organised as targets, defined in the _targets.R file. Sometimes targets operate with the outcomes of other targets. For instance, one target might run a function that takes the outcome of a different target as argument. {targets} makes sure that the functions and objects needed to run each target have already been previously defined. You can visually explore this repository’s targets and its dependency structure by running targets::tar_visnetwork(). You can explore the contents of the executed targets by running targets::tar_load_everything(), which will load all defined targets into your workspace.

--- --- We recommend two ways of reproducing or inspecting the code of this repository. One option is to clone the [Docker image](https://hub.docker.com/r/gongcastro/cognate-beginnings) we have pused to Dockerhub. A Docker image is just a virtual machine that contains all dependencies, code, and files necessary to run the code. Everything is already installed and setup, you will only have to open [http://localhost:8787](http://localhost:8787) in your browser, and a RStudio session will open for you. This option is more robust (dependencies are difficult to get right when using your own computer), but it also requires Docker to be installed. A second option is the more traditional approach of downloading the repository (or cloning it, if you know your way through Git/GitHub), installing the necessary dependencies (we recommend using renv for R dependencies, other system dependencies are listed below), and running the code (we recommend using the targets workflow). ### Docker {{< fa brands docker >}} --- 1. Download and install Docker ([Windows](https://docs.docker.com/desktop/install/windows-install/), [Mac](https://docs.docker.com/desktop/install/mac-install/), [Linux](https://docs.docker.com/desktop/install/linux-install/)) 2. Pull the [gongcastro/cognate-beginnings image](https://hub.docker.com/r/gongcastro/cognate-beginnings). Two ways of doing this: a) Using the Docker CLI: open your console/terminal/command prompt, and run: ```bash docker pull gongcastro/cognate-beginnings ``` b) Using the Docker Desktop app: go the "Images" tab, click on "Search images to run", search for "gongcastro/cognate-beginnings", and click "Pull". 3. Run the image in a Docker container. Two ways of doing this: a) Using the Docker Desktop app: in the "Images" tab, look for the `gongcastro/cognate-beginnings` image and click "Run". b) Using the Docker CLI: ```bash docker run --rm -ti -e ROOT=true -e PASSWORD=rstudio -p 8787:8787 --name rstudio gongcastro/cognate-beginnings:latest ``` 4. Open [http://localhost:8787](http://localhost:8787) in your browser. Log in using `rstudio` as user, and `rstudio` as password. An RStudio session should open, with all files, code and dependencies installed and ready. To retrieve and explore a given object, run `targets::tar_load(target_name)`, where `target_name` is the name of the rarget you want to explore (e.g., `targets::tar_load(items)`). > 💡 The RStudio session opened by Docker does not have root permissions (you will not be able to run `targets::tar_make()` to run the code from the R console). Instead, open the "Terminal" tab, and run `sudo Rscript -e "targets::tar_make()"`. The targets workflow should now be triggered. > 💡 The targets workflow is run to completion before your Rstudio session is open in Docker. This means that even if you trigger `targets::tar_make()`, virtually all targets will be skipped, as they are completed. If you want to run a specific target, delete it first (or any other target it depends on), and the targets workflow will be run, now generating all deleted targets again. Be aware that this might take some time, especially when fitting the models anew. ## GitHub {{< fa brands github >}} 0. Download this repository 1. Install software dependencies 2. Install package dependencies with renv 3. Running the code with targets 4. Repository structure and files ### 0. Download this repository ⬇️ First, you will need to download this repository to your local machine. We suggest three different ways: a) **Git terminal**: download and install [Git](https://git-scm.com/downloads) with default settings and clone this repository locally running the following command in your console: ``` bash git clone https://github.com/gongcastro/cognate-beginnings.git ``` > 💡 You don't need to run this command from the Git console. Just open > Command Prompt or Power Shell in Windows (just make sure that Git is > included in your [PATH > variables](https://www.delftstack.com/howto/git/add-git-to-path-on-windows/), > which should be already done after the recommended Git installation), > Terminal in MacOS, or command line in Linux and run this command. b) **GitHub releases**: download the latest [release](https://github.com/gongcastro/cognate-beginnings/releases) of the repository. c) **Direct download**: click the [green button](https://github.com/gongcastro/cognate-beginnings/archive/refs/heads/main.zip) "Code" in this page (upper-right corner), click "Download ZIP", and unzipping the downloaded repository. ### 1. Install software dependencies 💻 Here's a list of programs that you might need to install in your machine to make the project work: - [R](https://www.r-project.org/) (4.2.2 or greater) - [RStudio](https://posit.co/download/rstudio-desktop/): although not strictly necessary, we encourage the use of Rstudio for reproducing the present project. We have not tested the reproducibility of the project in other IDEs. - [Quarto](https://quarto.org/docs/get-started/) (1.3.340 or greater): we use this software to generate the manuscript and lab notes. We recommend installing version 1.3.340 or higher, although previous version might work as well. - [Rtools](https://cran.r-project.org/bin/windows/Rtools/) (4.3 or greater). - [CmdStan](https://mc-stan.org/users/interfaces/cmdstan) (2.31.0 or greater): we use the CmdStan backend in brms to fit our Bayesian models. We recommend installing CmdStan using its R interface [CmdStanR](https://mc-stan.org/cmdstanr/) following the [*Getting started with CmdStanR*](https://mc-stan.org/cmdstanr/articles/cmdstanr.html) vignette. You can also install it following the [CmdStan installation guide](https://mc-stan.org/users/interfaces/), and then letting CmdStanR know the path to the folder using `cmdstanr::set_cmdstan_path()`. <div> > 💡 **Installing CmdStan** is sometimes inconvenient, and might > require some time to set up, specially if it's your first time > doing so. Have patience and follow the CmdStan installation guide > closely. If you encounter problems and just don't have the time, > you can download the models from the [Open Science Framework > repository](https://osf.io/hy984/) and skip the model-fitting > steps. </div> ### 2. Install package dependencies with renv 📦 Open the downloaded repository folder and click on the [cognate-beginnings.Rproj](cognate-beginnings.Rproj) to open an RStudio session (recommended) or just open an R session and set the working directory to the downloaded folder. Once open run: ``` r install.packages("renv") # in case you need to install renv renv::restore() ``` This might take a couple of minutes, depending on the number of packages that need installation or an update. > 💡 **What does this step do?** The code in this repository needs some > packages to run, many of which might not have been already installed > in your local machine. Instead of having to install them yourself one > by one or updating already installed ones (which might change how they > behave, possibly breaking some of your code in other projects) this > repository uses the R package > [renv](https://rstudio.github.io/renv/articles/renv.html) to deal with > package libraries. The command `renv::restore()` will install all > necessary packages in the appropriate version (listed in the file > [renv.lock](renv.lock) in a self-contained R package library. This > process will not affect the packages that you had already installed in > your machine. > > 💡 **Something went wrong with renv. Now what?** Although renv > facilitates the reproducibility of the repository, it is not > guaranteed that things will work perfectly. If you encounter trouble > installing the packages using renv, try installing them individually > using (`install.packages()` or `renv::install()`) and try fixing > whatever issues arise (they might depend on your particular setup). > Some packages are used by RStudio itself, and might refiuse to update > them while you're using RStudio. Try installing them from the R > console outside of RStudio. Open an > [issue](https://github.com/gongcastro/cognate-beginnings/issues) on > this repository if you need further assistance! We'll get back to you > ASAP. :smile: ### 3. Running the code with targets 🚀 Once the package dependencies have been solved with renv, run the following command: ``` r targets::tar_make() ``` Mind that this process might take some time. Refitting the brms models might take very long (days even, depending on your set-up). If you want to skip this step, download the "results" folder in the [Open Science Framework repository](https://osf.io/hy984/) and replace it in the repository. > 💡**What does this step do?** This repository's workflow is based on > [targets](https://books.ropensci.org/targets/). This means that the > code is run in the appropriate order according to its internal > dependencies. The code is organised as *targets*, defined in the > `_targets.R` file. Sometimes targets operate with the outcomes of > other targets. For instance, one target might run a function that > takes the outcome of a different target as argument. {targets} makes > sure that the functions and objects needed to run each target have > already been previously defined. You can visually explore this > repository's targets and its dependency structure by running > `targets::tar_visnetwork()`. You can explore the contents of the > executed targets by running `targets::tar_load_everything()`, which > will load all defined targets into your workspace.