Skill Assessment Tutorial (R)

Hello and welcome to the BRN Skill Assessment tutorial 👋!

My name is BRN bot and I will help you get started today (**beep boop** 🤖).

Let's dive in so you can earn your first Skill Assessment badge 🏆.

Instructions

Every BRN Skill Assessment contains Instructions which provide the following information:

Requirements (the requirements for successful completion of the assessment)
Guidance (additional instructions and hints to aide you in this task)

If you are ready to dive in, jump to the Requiments section next.

Or stop and check out this additional information about BRN Skill Assessments:

Assessment metadata

Each Skill Assessment also contains metadata, in the form of badges like these:

These badges describe the assessment and provide additional useful information.

To learn all about these metadata badges, please check the info sheet here.

Privacy, Code of Conduct, and Academic Honesty

BRN has several policies which apply to Skill Assessments. During the sign up process, you agreed to each. Here, I will recap their main points:

Privacy Policy
- The Privacy Policy gives you the right to request access to all of your data from BRN and for us to delete all your data. You can request either at any time by emailing privacy@bioresnet.org.
Code of Conduct
- BRN is dedicated to maintaining appropriate conduct standards throughout its online and in-person spaces. The Code of Conduct is the policy which governs acceptable behavior. It forbids discrimination, harassment, and other types of inappropriate conduct.
- While this tutorial will not involve interacting with human reviewers, subsequent assessments will -- so please be mindful of your behavior during those exchanges as well as the behavior of the reviewers.
- If you observe violations of this policy, you are encouraged to contact codeofconduct@bioresnet.org.
Academic Honesty
- BRN strictly enforces policies that discourage cheating, fraud, and plagiarism in its Academic Honesty Policy. Because these skill assessments certify individual capability in bioinformatics, cheating and plagiarism guidelines are stricly enforced.
- The most common way for cheating to arise is when you share (or recieve) Skill Assessment code or answers from another BRN member. Therefore, we expressly forbid sharing code or discussing Skill Assessments with anyone who is not a member of the BRN Skill Assessment working group or BRN leadership team.
- The most common way for plagiarism to arise is when a trainee copies code from other sources on the internet and does not appropriately attribute it. Copying code (with or without modification) from sources like Stack Overflow is fine as long as the source of that code is mentioned (see example below). This policy does not prevent using AI-based programming tools like Tabnine, Kite, and GitHub Copilot.

# This function copied from: https://www.stackoverflow.com/url_link
function_from_stack_overflow <- function(params) {
    function code...
}

# This function adapted from: https://www.stackoverflow.com/url_link2
function_adapted_from_stack_overflow <- function(params) {
    function code...
}

Requirements

Badge Requirements:

Testing environment:

Assessment Premise:

This Skill Assessment will require you to write a script, main.R, which contains a function called hello() that returns the phrase "Hello, world!".

Therefore, the requirements for success in the assessment are:

Write a script, main.R
Create a function hello() in main.R.
hello() should return "Hello, world!".
The repository must pass the automated checks (learn about these checks here)

Based on the requirements, users should be able to import your script and run hello via the following commands:

source("main.R")

print(hello())  # Says "Hello, world!"

Guidance

The BRN Skill Assessment Interface

Since I am helping you with this skill assessment, we will need a way to talk to eachother 💬. Fortunately, GitHub provides Pull Requests which will allow us to communicate. Navigate to the "Pull requests" tab and click the one called "Feedback". You should see a welcome message from me 🤖.

Using the pull request comments, you can issue bot commands which perform various tasks. The welcome message lists the ones that are available to you in this skill assessment.

For example, issue the "hello" command by posting this comment:

@brnbot hello

Then I will reply:

Hello, @<your_username>! 😊

You will need to use bot commands to complete the assignment, so get used to typing "@brnbot <command>" in the pull request.

Completing the assessment

Since this is your first time, I've gone ahead and completed Requirements 1-3 for you 😊. But even I make mistakes sometimes 🤖... so, you may want to check my code for errors 🔍.

You can view and edit the code using any of the following options:

Code editing options

Clone the repository to your local computer, and then open the code in your favorite editor (e.g., RStudio, VS Code, atom, vim). Once you are happy with your changes, use git to add your changes, commit them, and then push them back to this GitHub repo. (Recommended approach)
Edit the code in your browser by pressing the "." key to open an in-browser VS Code session. Commit your changes using the built-in version control panel.
You can also simply navigate to the file you want to modify in the GitHub repo and click the edit icon to add your changes and commit them directly.
Request access to the BRN Orchestra server (contains RStudio, VS Code, and Jupyter IDEs) by contacting training@bioresnet.org. Once granted, you will be able to open the repo in your own server sessions and add, commit, and push it back to GitHub.

Once you push your changes back to the GitHub repo, run the checks to see if your code works correctly. You can run checks by issuing this bot command:

@brnbot check

I will see this comment and run the checks for you. You can monitor the progress of the checks in the "Actions" panel and see the results there. Once the checks are done, I will write a comment and I will tell you whether they passed or failed. If they failed, examine the log in the "Actions" tab to see what went wrong. Then update your code accordingly and rerun the checks.

Check details

The automated checks are run with GitHub Actions using the workflow defined in .github/workflows/tests.yml within this repo.

When triggered, GitHub actions creates a new computing environment using the details in tests.yml. For this assessment, the environment contains R v4.2.0. We also install the testthat R package. That is defined in this part of the file:

- uses: r-lib/actions/setup-r@v2
    with:
        use-public-rspm: true
        r-version: '4.2.0'
- run: Rscript -e 'install.packages("testthat")'

The repo code is then tested in the last part of the workflow:

- run: Rscript -e 'testthat::test_dir("tests/", stop_on_failure = T)'

The testthat::test_dir() command finds all the tests in the tests/ folder and then executes them.

For this skill assessment, there is only one test in tests/test_main.R:

library(testthat)

source("../main.R")

test_that("hello() works", {    
    expect_equal(hello(), "Hello, world!")  
})

This test simply imports the main.R script and then executes the hello() function. It then uses the expect_equal statement to ensure that the output matches the expected value: "Hello, world!". If it does not, then the test will fail.

To complete a BRN Skill Assessment, all tests have to pass successfully.

Finally, it can be inconvenient to push your code to GitHub every time you want to run testthat::test_dir(). Fortunately, you can run tests locally by opening an R console session on your computer, installing the testthat library, and then running the tests yourself.

# Install testthat
install.packages("testthat")

# Run testthat
testthat::test_dir("tests/")

A note about academic honesty and tests:

The tests/ folder contains the "correct answers" to these Skill Assessments. Therefore, it is possible to ignore the assignment prompt and write your code to exactly match the outputs that the tests expect. While this might work for assessments which have no reviewers, it is still dishonest and may lead to your account being suspended and badges revoked.

Once you pass the checks, I will issue your badge 🏆 and archive the repo. You will get an email with the link to your badge and it will also appear in your profile on the BRN Skill Assessment web platform 🔥.

External resources

For a tutorial on how to use git and GitHub, check out these resources:

Written tutorials: GitHub official tutorial, freecodecamp.org, analyticsvidhya
YouTube tutorials: Tech with Tim, freecodecamp.org, Amigoscode

For basic R programming, check out these resources:

Written tutorials: Introduction to R (book), Hands-On Programming with R (book), W3 schools
YouTube tutorials: Simplilearn, Algovibes, BIG Bioinformatics
MOOCs: EdX, Coursera
Online learning platforms: DataCamp, dataquest, codecademy

For learning how to use testthat, check out these resources:

Written: Official testthat docs, R-bloggers
YouTube: InfoWorld

Requirements metadata

Requirements contains metadata, in the form of badges like these: