update

Author: sebffischer

paper/README.md

@@ -5,27 +5,27 @@ Note that there is also a brief section on reproducibility in the appendix of th
 ## Computational Environment
 
 In order to reproduce the results, you can either use the provided docker images or recreate the `renv` environment that is described in `paper/renv.lock`.
-To work with the renv environment, go into the `paper` directory and start an interactive R session, which will bootstrap the environment.
-Then, run:
+To work with the renv environment, go into the `paper` directory and start an interactive R session, which will bootstrap the `renv` package.
+Then, restore the environment by running:
 
 ```r
 renv::restore()
 ```
 
-which will ask you whether you want to proceed installing the missing packages, which you have to confirm.
+It will prompt ask you whether you want to proceed installing the missing packages, which you have to confirm.
+Afterwards, you need to install torch via:
 
-
-```{r}
+```r
 torch::install_torch()
 ```
 
 We are providing two docker images, one for CPU and one for CUDA GPU that have the same packages from the `renv.lock` file installed.
-The images can be downloaded from Zenodo: https://doi.org/10.5281/zenodo.17130368, either via the web interface, or, for example, using wget:
+The images can be downloaded from Zenodo: https://doi.org/10.5281/zenodo.17130368, either via the web interface, or, for example, using `wget` or a similar tool:
 
 ```bash
 # Docker images
-wget https://zenodo.org/records/17864153/files/IMAGE_CPU.tar.gz
-wget https://zenodo.org/records/17864153/files/IMAGE_GPU.tar.gz
+wget https://zenodo.org/records/18456360/files/IMAGE_CPU.tar.gz
+wget https://zenodo.org/records/18456360/files/IMAGE_GPU.tar.gz
 ```
 
 At the time of writing, the images are also hosted on dockerhub, but this is not a permanent storage:
@@ -49,11 +49,11 @@ cd /mnt/data/paper
 The CUDA image can be started with the command below, which requires the [nvidia extension](https://docs.nvidia.com/ai-enterprise/deployment/vmware/latest/docker.html).
 
 ```bash
-docker run -it --gpus all --rm -v ../:/mnt/data sebffischer/mlr3torch-jss:gpu
+docker run -it --gpus all --rm -v <parent-dir-to-paper>:/mnt/data sebffischer/mlr3torch-jss:gpu
 cd /mnt/data/paper
 ```
 
-Note that the `.Rprofile` file ensures that when running R programs from the `paper` directory, the renv environment will be used unless the code is run in the docker container, where we are not relying on renv directly.
+Note that the `.Rprofile` file in `paper` ensures that when running R programs from the `paper` directory, the renv environment will be used unless the code is run in the docker container, where we are not relying on renv directly.
 
 ## Running the Benchmark
 
@@ -88,7 +88,8 @@ There are three scripts:
 **Important**:If one of the folders already exists and you want to re-run the benchmarks, you need to delete or move the folder, otherwise you will get an error.
 This is to ensure that the benchmark results are not accidentally overwritten.
 
-To run the GPU benchmarks (using the CUDA docker image) on linux, run:
+To run the GPU benchmarks (using the CUDA docker image) on linux, either start it via Rscript or source it interactively:
+If you source it interactively and the folder already exists, it will ask you whether you want to delete it, which you have to confirm.
 
 ```bash
 Rscript benchmark/linux-gpu.R
@@ -168,8 +169,6 @@ It was extracted from the tex manuscript almost fully programmatically but adjus
 
 We also added some additional comments to make it easier to associate the code with the paper.
 
-The results we obtained via `knitr::spin()` are stored in `paper/paper_results/`
-
 ### Possible Data Unavailability
 
 The code shown in the paper downloads various datasets from standard resources.
@@ -180,18 +179,26 @@ In the unlikely but possible event that these datasets are not available anymore
 
 in the Zenodo data.
 
-If one of the downloads (1) fails, download the `cache.tar.gz` file from zenodo, untar it and put it in the location where the cache is (put the `R` folder of the cache into `/root/.cache/R` and the `torch` folder into `/root/.cache/torch` when using the docker images).
+If one of the downloads (1) fails, do the following (before starting the docker container):
 
-If (2) fails, download `dogs-vs-cats.tar.gz` from Zenodo, untar it and put it into the `paper/data` subdirectory where you are running the `paper_code.R` (so the directory structure is `paper/data/dogs-vs-cats`).
+1. Download the `cache.tar.gz` file, e.g. via:
+   ```bash
+   wget https://zenodo.org/records/18456360/files/cache.tar.gz
+   ```
+2. Create a `cache` folder in the parent directory of `paper` (name `cache` is arbitrary) and move the `cache.tar.gz` file there
+3. Untar the `cache.tar.gz` folder using `tar -xzf cache.tar.gz`
+4. There should now be a `.cache` sub-directory in the `cache` folder.
 
-To do this in the Docker image you can, e.g., put the files into the parent directory of the `paper` directory (which will be mounted) and then after starting the container, copy the files into the correct location.
-Assuming the unpacked cache files are in `/mnt/data/cache`, you can copy them into the correct location with:
+After starting the docker container with the correct mount instructions, (like shown earlier), run:
 
 ```bash
-cp -r /mnt/data/cache/R/mlr3torch /root/.cache/R
-cp -r /mnt/data/cache/torch /root/.cache/torch
+cp -r /mnt/data/cache/.cache/R/mlr3torch /root/.cache/R
+cp -r /mnt/data/cache/.cache/torch /root/.cache/torch
 ```
 
+If (2) fails, download `dogs-vs-cats.tar.gz` from Zenodo, untar it and put it into the `paper/data` subdirectory where you are running the `paper_code.R` (so the directory structure is `paper/data/dogs-vs-cats/`).
+
+
 ### Other errors
 
 When reproducing the results with `knitr` in the docker container, we sometimes encountered issues with the weight downloads for the ResNet-18 model.