README.md
In escapeR: Escape Room Adventures for Learning R in Ecological Statistics

escapeR

You are locked inside an Ecological Statistics escape room.

The doors open with R.

escapeR is a classroom game where you learn and practise R by solving small ecological-statistics puzzles. Each room gives you a short story, a task, and a lock. You use ordinary R commands to inspect data, make plots, fit models, and think through ecological evidence. When you have the answer, submit it and move to the next room.

The escapeR Educational Experience

The above image represents a vision. The more accurate vision vs reality meme is at the bottom of this README file.

Install the package from GitHub:

install.packages("remotes")
remotes::install_github("TiagoAMarques/escapeR")

Then begin:

library(escapeR)
escape()

escape() asks for your player name and starts the quest. If you come back later with the same name, your saved progress is loaded automatically.

Read the room. Solve the task in R. Submit the answer.

submit(42)

If you need to see the current room again:

play()

If you need a nudge:

hint()

Some rooms have several hints. Repeated calls reveal them one at a time.

To check where you are:

status()

To start over:

reset_game()

The en2026 escape follows the 25 EN2026 lecture decks, with one room per lecture. It starts with R as a calculator and continues through probability, sampling, experimental design, hypothesis tests, ANOVA, regression, GLMs and GAMs, contingency tables, likelihood, clustering, and PCA. All puzzle data are included in the questions; no downloads or additional packages are required.

library(escapeR)
escape(player = "your_name", escape = "en2026")

To resume, call escape(player = "your_name") without the escape argument. Passing escape again starts a new sequence. enintro contains just the first room. Use hint() for progressive help and submit(your_answer) to unlock each door. Numerical answers accept the requested rounding or greater precision.

Teachers can find the lecture mapping, assumptions, and worked solutions in the Ecologia Numérica guide.

The current escape has 20 rooms across seven parts of an introductory Ecological Statistics journey:

R foundations: arithmetic, vectors, and named objects.
Data import and inspection: built-in data, CSV files, columns, and missing values.
Visualisation: detection patterns, categorical summaries, and hidden structure in data.
Data manipulation: subsetting and ordering data frames.
Ecological modelling: linear models, residuals, and prediction.
Distance sampling: observation processes, detections, and truncation.
Reproducible workflow: comments, web data, GLMs, and Quarto source files.

To see every room:

list_rooms()

For a fuller walkthrough:

vignette("getting-started-with-escapeR", package = "escapeR")

Some rooms use data bundled with the package:

survey <- survey_counts()                       # returns a five-column data frame
dados <- read.csv(escapeR_file("dados1.csv"))  # a separate four-column CSV
escapeR_file("datahide.txt")

survey deliberately contains two NA values in its count column; dados does not. The game expects you to work with these just like normal R data: inspect them, plot them, model them, and check your assumptions.

You can build shorter quests from selected rooms:

river_escape <- build_escape(c("console", "vector", "plotwin"))
escape(player = "student1", reset = TRUE, escape = river_escape)

You can also create and register your own rooms:

parasite_room <- new_room(
  id = "paras",
  module = "R foundations",
  title = "The Parasite Count",
  learning_goal = "Create vectors and summarize them.",
  introduction = "A sample tray holds river fish records.",
  challenge = "Submit the mean parasite count.",
  hints = c("Store the counts in a vector first.", "mean() calculates the average."),
  correct_result = 15,
  success = "The tray label clicks into place."
)

register_rooms(parasite_room)
build_escape(c("console", "paras"))

To make a coursework room and submit it as an R file through Moodle, start with the simple student guide:

vignette("student-room-coursework", package = "escapeR")

It includes a complete ecological example, a reusable .R template, and steps for editing, playing, and submitting your own room.

To learn how to create themed rooms and room packs:

vignette("creating-themed-escape-rooms", package = "escapeR")

escapeR started as a playful way to teach R in an Ecological Statistics context. It is inspired by introductory R teaching material, ecological modelling, and distance-sampling ideas.

Wrong answers return encouraging messages that point students back to useful habits: checking object names, inspecting data structure, iterating carefully, and treating models as tools for thinking rather than magic doors.

Future directions may include more rooms, Portuguese and English text modes, instructor-authored room packs, Shiny or learnr front ends, classroom leaderboards, and export of student progress.

The escapeR Expectation vs Reality

Progress files are small and stored in tools::R_user_dir("escapeR", "data"). Remove profiles when no longer needed with delete_progress("player"). Calling delete_progress() removes the active profile and closes that game. Select another directory with options(escapeR.progress_dir = "path"). For demonstrations, use a temporary directory and remove it afterwards. Names are case-insensitive; punctuation becomes underscores in filenames. The game rejects names that collide with another saved profile.