Name:
Andrew ID:
Collaborated with:

On this homework, you can collaborate with your classmates, but you must identify their names above, and you must submit your own homework as an knitted HTML file on Canvas, by Monday August 5 at 10pm, next week.

Introduction to percolation

In this homework, we’ll be coding a series of functions to investigate percolation via simulation. We’ll spend this section to discuss the problem and setup. You can read related literature on this topic at Wikipedia, but we’ll be working with a simplified setting for this homework. As a word of caution, this is a coding heavy homework (as opposed to statistical), so be prepared to spend a lot of time debugging and testing.

Here’s the idea. Imagine you have a square board (10 by 10 squares) like the left board show below. This board consist of white “open” squares and black “blocked” squares. We are interested in knowing (abstractly) if we “pour water” from the top of the matrix, does the water “leak” from the bottom of the matrix. This is demonstrated in the right board. (Don’t worry, we’ll explain all the necessary specifics later.) You can think of this as the following: we indefinitely keep pouring water into each white square in the top row at the same time, and water runs through the board by spreading to any adjacent white square (left, right, top, and bottom). We keep pouring water until all the possibly-flooded squares are flooded. These are the blue squares shown below in the right board. Once we’re done, we see if the water reached any of the open squares in the bottom row of the board (i.e., are there any blue squares in the bottom row?). If so, we say the board “percolates”. Otherwise, it does not percolate. In the figure shown below, the displayed board percolates (left is the original board, and right is the percolated board).

However, not all boards percolate. Consider the next board, shown below. Once again, we show the initial board on the left, and we start pouring water, resulting in the board on the right.

Now imagine we had a way to randomly generate these boards. We would like to see if there are certain types of randomly-generated boards that more likely to percolate. We’ll formalize this task in this homework.

So what are the goals of this homework? We will be developing a package with version control and github connection. This package will encapsulate a set of functions related to a new object, called board. While developing our package, we will be writing the following functions: generate_board_mat() will generate a random board (matrix version) with white “open” squares and black “blocked” squares. is_valid() will check whether or not a given board matrix is correctly formatted. plot.board() will plot the board, similar to the four boards shown above. The last two functions contribute the challenges to this homework: percolate.board(), which determines whether or not a board percolates, and read_board() reads in a text file that specifies many boards. Note that plot.board() and percolate.board() will be methods of the class.

We will not give you explicit guidance on how to debug and test throughout most of this homework, but the concepts and tools you’ve learned in lecture will certainly be beneficial as you write and try out your code.

Note: The grading of this homework with depend mainly on whether or not you pass the test cases provided. Your implementation of percolate.board() and read_boards() might look quite different from another classmates, but be you sure that your code passes the tests if you want full credit!

Making a package and using version control

As you will be learning version control and connection to github during Wednesday’s lecture and making packages but you should start this assignment early in the week, I provide 3 ways to approach this homework (conditional on your experience and willingness to read future lectures). I recommend that you try to at least start with Approach 2 if you have some knowledge about Github.

Approach 1 (Base Approach):

Start writing all you code into this homework .Rmd file as usual. As long as the code you write well documented the you can transfer your code to a package with version control at the very end (this is less prefered in terms of using version control - but is fine for now). At the very end of the assignment will be guidance on how to create your package with version control. Note: the “Approach 2/3” comments throught this document can also aid this this endeavor.

In this approach - it is very important that all functions and tests you write deal well with the “local” vs “global” paradigm - that is, don’t assume more things are in the global environment than you need.

Approach 2 (Github start):

Using the guide in Wednesday’s Lecture, create a new github public repository please call it percolate and create a project in your Rstudio that links to it. Please additionally make folders R/ and /tests/testthat/ in this new directory. We will put your functions and class definitions in .R files in the R/ folder and your tests in .R files in the tests/testthat/ folder. I provide a small section at the end of the homework on how you should moving from being “approach 2” to “approach 3”.

Approach 3 (package start):

Similar to the Approach 2, create a new github public repository please call it percolate and create a project in your Rstudio that links to it. Using usethis::create_package("percolate") create a package in this directory. Make sure in your console you call this function when you are in the folder that contains the folder precolate.

To navigate in the console use `setwd()` and `getwd()` (which sets the directory you're in and returns which directory you're currently in)

You will be using usethis to set up your package and devtools to check your tests, document your functions and more. Please also see closing remarks at the bottom of the file.

Generating and plotting boards

In the first section, we will be creating our new class board as well as helper function and a plot function for our object. We will write generate_board_mat(), and create a class object that can either take in a matrix or generate the board with certain parameters. In this section we will also create the function is_valid() and the method plot.board(). To no surprise, we can represent these boards as square, numeric matrices with dimension n by n. These matrices will only have values 0 (for black “blocked” squares), 1 (for white “open and dry” squares), and 2 (for blue “open and flooded”) squares.

Approach 2: you’ll see the names of files to create / update. Just run the code in these files into your console to get interactions.