howto.Rmd

---
title: "HowTo"
---

```{r, include=FALSE}

knitr::knit_hooks$set(class = function(before, options, envir) {
  if(before){
    sprintf("<div class = '%s'>", options$class)
  }else{
    "</div>"
  }
})
```

<style>
.blue-outline {
   border-style: solid;
   border-color: black;
   border: 10px;
   
}
</style>


# Exercise Material

All exercise material can be accessed via this webpage.

Exercises are provided as a practical addition to the lectures and will help you to better understand the topics of the lecture.

Results will be discussed in the weekly exercise sessions.

## Setup

You can access individual exercise sheets using the navigation bar.

:::{#img1-p .extra-m}
```{r, echo=FALSE, out.width="90%", fig.align='center'}
knitr::include_graphics("figures/howto/navbar.png")
```
::::

All exercise sheets are made for self-learning and provide questions, hints and a master-solution.

There are no deadlines when exercises should be finished.
Keep in mind though that exercise discussions will be held every week for a certain exercise sheet. We advise you to do one exercise sheet every week to not lose track of the discussions.

A detailed schedule is available on our ILIAS page.


# Programming Tasks

Some exercise sheets have programming tasks.

:::: {#explaining .message-box }

::: {#note-exp .note-header}
```{r, include=knitr::is_html_output(), echo=FALSE,}
knitr::include_graphics("figures/infoicon.svg")
```
**Note**
:::
::: {#note-exp .note-body}


We will explain how to do the programming tasks during the first exercise session

:::


::::

Whenever a programming task is available you will be redirected to our Github Classroom page:

::::{#img1-p .extra-m}
::: {#img1 .tutorial-img}
```{r, echo=FALSE, out.width="100%", fig.align='left'}
knitr::include_graphics("figures/howto/programming.png")
```
:::
::::

In Github Classroom we provide automated testing for solutions written in Python. You are of course welcome to use whatever language you prefer, but the automatic tests will not work for other languages.

The link provided will lead you to the specific assignment.

::::{#img1-p .extra-m}
::: {#img2 .tutorial-img}
```{r, echo=FALSE, out.width="100%", fig.align='left'}
knitr::include_graphics("figures/howto/accept.png")
```
:::
::::

Once you accept the prompt shown on Github, a custom Github repository will be created for yourself, with your Github Name as a suffix.

::::{#img1-p .extra-m}
::: {#img3 .tutorial-img}
```{r, echo=FALSE, out.width="100%", fig.align='left'}
knitr::include_graphics("figures/howto/ready.png")
```
:::
::::

If you follow this link you will be able to see your personal Github repository. This will contain all the necessary files and descriptions to complete the programming task.
The task description will be given in the README.md which is also visible below the source code.

The important file for you will be the `exercise-sheet.py` file. It contains skeletons for all the functions you need to write with additional explanations.

You can either edit this file directly via Github using the edit button, or clone the repository to your PC and edit it with your preferred IDE.



# Recommended good practices


For this course, you will mainly need the basic `git clone`, `git add`, `git commit`, `git push` and `git pull` commands. 


:::: {#explaining .message-box }

::: {#note-exp .note-header}
```{r, include=knitr::is_html_output(), echo=FALSE,}
knitr::include_graphics("figures/infoicon.svg")
```
**Note**
:::
::: {#note-exp .note-body}

```{r, include=knitr::is_html_output(), echo=F}
knitr::asis_output('If you are not familiar with Github or similar systems, we recommend that you spend some time to get used to it: <a href="https://docs.github.com/en/get-started" title=" ">Github Docs</a>')
```
:::
::::

Here we have included some best practices helping you solve the exercises as efficiently as possible. For demonstration purposes we will use the first exercise sheet.

First, clone the assignment repository.

::: {#code .code}
git clone git<!-- breaklink -->@github.com:Bioinformatics-teaching/exercise-sheet-01-biology-basics-{userID}.git
:::

Now you should have a local copy of your git repository. Within the directory you will find a file called `exercise_sheet1.py`.
It contains the skeleton functions of the Programming assignment.
Open it with your favorite text editor or IDE and fill in the skeleton functions such that they return the expected result.

You can now check the status of your repository again via:

::: {#code .code}
git status
:::

It will show you that you have `Changes not staged for commit`, namely the modified `exercise_sheet1.py`.
The following commands will add the changes and commit them.

::: {#code .code}
git add exercise_sheet1.py

git commit -m "solved sheet"
:::

Now that you set up everything locally you can push your changes to GitHub, thus triggering the **Autograding**

::: {#code .code}
git push origin main
::: 


::::: {#explaining .message-box }

:::: {#note-exp .note-header}
```{r, include=knitr::is_html_output(), echo=FALSE,}
knitr::include_graphics("figures/infoicon.svg")
```
**Note**
::::
:::: {#note-exp .note-body}

If you want to test locally whether you solved the Programming Task correctly you can use `pytest`.
Just install it via:

::: {#code .code}
pip install pytest
::: 

`cd` into the directory where the `exercise_sheet1.py` lives and call:

::: {#code .code}
pytest
:::

::::
:::::




Once you have solved the programming task, you can push your changes to the repository, which will trigger the automatic testing of your code.

In the following video it is shown how to check if the tests succeeded



```{r, include=knitr::is_html_output(), echo=F}
knitr::asis_output('
<div class=extra-m>
<div class=tutorial-video>
<video width="100%" controls>
  <source src="figures/howto/autograding.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
</div>
</div>
' 
)
```


As you can see Programming Tasks a) and b) were solved perfectly. However the tests
for part c) failed. In such a case you would have to check the part c) again and fix it.
In some cases the autograding will also print hints about what was tested and 
how your output differed from the expected result.


:::: {#explaining .warning-box }

::: {#note-exp .warning-header}
```{r, include=knitr::is_html_output(), echo=FALSE,}
knitr::include_graphics("figures/warningicon.svg")
```
**Warning**
:::
::: {#note-exp .note-body}

Autograding might contain errors. If you are sure that you solved the task
correctly but the autograding fails, let us know either in the exercise session
or in the ILIAS forum.

:::


::::