01_download_setup.qmd

---
title: "Tutorial 1: Downloads, Setups and Your First Project"
date: last-modified
author: "Danet and Becks, based on originals by Delmas and Griffiths"
format:
    html:
        embed-resources: true
title-block-banner: true
engine: julia
---

```{julia}
#| echo: false
#| include: false
using DataFrames, Random, StatsPlots, Plots
```

## Downloading and Installing Julia and VSCode

**Julia**

Navigate to [this page](https://julialang.org/downloads/) and follow the platform-specific instructions to download and install Julia (we recommend installing the current stable release).

During the installation process, you may be prompted to add Julia to the PATH, this box should be ticked.

::: {.callout-tip collapse="true"}
## Using Juliaup

[Juliaup](https://github.com/JuliaLang/juliaup) is an alternative platform to install and manage multiple versions of Julia you run on your computer. This is useful if you need to run different versions of Julia for different projects but probably not essential for a casual Julia user, although there is also something to be said about setting yourself up with the best toys on the market...
:::  

**VSCode**

Navigate to [this page](https://visualstudio.microsoft.com/) to download and install your platform specific Visual Studio Code (not Visual Studio or Visual Studio for Mac).

## Setting Up VSCode to use Julia

VS Code is a free source-code editor, allowing you to code in multiple coding languages all from a platform that is completely customisable to the user - think of it as a more language agnostic version of RStudio. This flexibility is great but it does mean that you need to spend time telling VS Code what it is you want to do and how. This is where extensions come in; extensions are higher level packages that permit the use of a given coding language like Julia, edit your themes and icons, provide helpful applications like spell checker or Bracket Pair Colorizer, and for adding your own [VS Code pets](https://tonybaloney.github.io/vscode-pets/usage) (a very important part of the VSCode experience).

To install Julia in VS Code do the following (you only need to do this once):

1.  open VS Code (you'll see the welcome page)
2.  navigate to the 'Marketplace' (5th symbol down in the activity bar - vertical panel on the lefthand side of the screen)

![The Marketplace Button](Figs/VSCode_FirstView.png)

3.  search for Julia in the 'Search Extensions in Marketplace' search bar
4.  install `Julia`, this extension provides support for the Julia programming language and install `Julia Formatter`, this extension will help you write clean code that is easier to read

![Selecting the Julia Language Support and Formatter](Figs/JuliaLangAndFormatter.png)

## Making your first Julia project

As with working in R and RStudio, we advocate working in a contained project environment when using Julia. Each unique project may require a different setup (e.g. packages, package versions, working directories, data locations, etc.).

To set up a project in VS Code:

1.  Creating a folder at a location of your choosing (e.g. within your Documents folder). This can be on GoogleDrive, Dropbox or OneDrive. This is OK.

2.  Name the folder with relevant works. Here we will use `Julia - VS code - how to`.

3.  Navigate to VSCode and open your new project by clicking on the 'Explorer' symbol (top left symbol on the activity bar) and click Open Folder and navigate your finder or explorer to the `Julia - VS code - how to` folder.

    -   this folder becomes the working directory (same as when using an `.RProject` in R)

![Opening Your Project](Figs/OpenProject.png)

4.  Create a new file (a script) in your directory: do this by using cmd-N (mac) or ctrl-N (windows) or File -\> New File or by left clicking -\> New File within the directory pane

5.  Name your script as your see fit but please remember to include the .jl file extension (e.g. JuliaTuto.jl). the .jl file extension tells VS Code you want to use the Julia programming language. To save your script at any time use cmd-S (MAC) OR ctrl-S (windows) or File \> Save.

    -   Note, you can also open a project in VS Code by right-clicking on your folder (in Finder, Windows file explorer or Linux nautilus) and selecting Open with -\> Other -\> VS Code.

### Activating the REPL and running some code.

This sequence of figures aligns with the instructions below.

![Initiating and using the REPL](Figs/UsingREPL.png)

Now that you have an active project and a new script file you can open the Julia REPL. REPL stands for *read, execute, print and loop*. The REPL is like the console in R and is where the magic happens. In Eva's words, it's VS Code's way of using Julia for a brain.

To do this you type F1 or cmd/ctrl - shift-p or View -\> Command Palette and choose Julia REPL. The command palette will appear as a drop down menu with a search function at the top of the page.

Now that you have an interface with Julia as a brain, you can actually do something! Try this: type `print("Hello world")` in the REPL and press Enter/Return. If you've done all of the above correctly, Hello world should print in the REPL.

Now, you can also make a 'script'. Type ctrl-n or cmd-n and a document will open at the top. There will be a prompt/link to select your language. Click the link and, yes, search for and choose Julia.

Next, type `print("Hello world")` in the script. Just like RStudio, you can send the information in the script to the REPL. There are two ways to do this. First, and probably what you'll want, is shift-enter(return). This will send the line of code you are on, and move to the next line. ctrl-enter(return) submits the line but does not move the cursor. Try it!

## Activating your project, the Project.toml and Manifest.toml

We mentioned above that it is good practice to work within an environment specific to each project. The Julia package manager (`Pkg`) allows you to do that easily: Unlike traditional package managers, which install and manage a single global set of packages, `Pkg` is designed around environments: independent sets of packages that can be local to an individual project or shared and selected by name (text taken directly from the documentation).

### Getting started: activating your project.

Activating your project is something that only needs doing once per computer. It allows you to add packages and dependencies to the project.

If you move the project to a new computer, or share the project, activation will be needed again.

There are two ways to activate your project.

1.  type `Pkg.activate(".")` in the REPL.
2.  type `]` in the REPL and then `activate .`

The `]` is a shorthand for using the `Pkg` package and opens the package manager. To get out of this, you press the `backspace/delete` button on your keyboard.

There are two ways to double check that you are actually working within your project:

-   check/click the 'Julia env:...' on the bottom of your screen (blue bar), it should match your project name

-   enter the package manager by typing `]` in the Julia REPL, you should see (your-project-name) pkg\> instead of julia\>. Again, exit the package manager using `backspace/delete` button.

### Working with the package manager and growing the project and manifest files

Once your project is activated, there are two ways to use the package manager (Pkg):

1.  directly from the REPL:

-   navigate to the REPL
-   type `]`
-   you will see that instead of seeing julia\> you now see (your-project-name) pkg\>, indicating that all the packages that you now install (or update) will be installed (or updated) within this specific project
-   to add a package, use the function `add`: `] add Plots`

2.  using `Pkg` (this is useful when you want to install packages or manage them from within your script):

-   first type `import Pkg` and execute this line using shift-Enter
-   on subsequent lines, add, remove and update packages from your script using `Pkg` functions such as `Pkg.add()`, `Pkg.remove()` or `Pkg.update()`.
-   To add a packages, the name of the package need to be written with quotes (`Pkg.add("Plots")`).

#### An example using the Plots package

Now that we are all set up, we are going to install a package, check the project's status and remove a package. As this might be your first time installing a package (e.g., Plots), don't be concerned if it takes a couple of minutes to run.

-   type `] add Plots` in the REPL (or `Pkg.add("Plots")`) in your script and execute using Ctrl-Enter.
    -   you just installed the Plots package and a whole bunch of dependencies that Plots needs to work. This is equivalent to Base plots in R.

![Package Installing](Figs/Pkg.adding.png)

-   type `] st` in the REPL. This will check the status of your project and print the content of your Project.toml file, which is the list of main packages, in this case, just Plots.

you should see something like:

![Package Status Check](Figs/StatusCheck.png)

::: {.callout-tip}
## Tip

Packages can removed in the same way i.e. `] rm Plots`  (or `Pkg.rm("Plots")`) will remove the Plots package from your project environment (and its record in the Project.toml and Manifest.toml files)
:::  

## Gearing up to Do More Stuff (what packages do I need).

There are a core set of packages we use for all of our work. These 10 packages are almost always installed when we make a project.

Go ahead and use either the `]` or `Pkg.add("package.name")` method to add all of these to your project.

#### For working with data

`CSV` `DataFrames` `DelimitedFiles`

#### For plotting

`Plots`

#### For statistical things

`Distributions` `Random` `Statistics` `StatsBase` `StatsPlots`

#### For Modelling

`DifferentialEquations`

## Your first script setup.

At this stage, you should have a good understanding about how to create a project folder, activate a project, start the REPL, open a script and add packages to the project.

Now you are ready to 'setup' your first script.

1.  create a new script file (ctrl-n or cmd-n).
2.  choose Julia as the language
3.  Type some informative information at the top of the script
    a.  just like in R and other programming languages, the `#` is a commenter.
4.  The first section of your script is where you declare the packages you'll be using.
    a.  the function to do this is `using`.
    b.  make Plots, Random and DataFrames available.

Now you are ready to do something really simple. Let's make some variables, data frames and a few simple plots.

First, lets get the setup sorted and packages available

```{julia}
# This is my first example script
# 25 Jan 2023

# packages I need
using DataFrames, Plots, Random, StatsPlots
```

Second, let's make some variables and see how Julia prints them to the screen

```{julia}
# make two variables using the rand function
# because we are using random numbers, we'll set the seed here for reproducibility

Random.seed!(12345)

x = rand(10)
y = rand(10)
```

Cool. Now, lets create two data frames, one made of the x and y variables, and another with three variables made directly in a call to `DataFrame`.

```{julia}
# combine into a data frame using the DataFrame function
df = DataFrame(x = x, y = y)
df
```

...and the second

```{julia}
# make a second data frame with three variables
# using DataFrame directly to create variables
df2 = DataFrame(a=1:10, b=10*rand(10), c=10*rand(10))
df2
```

Great. Now, lets see how to plot the 'solo' variables. Note how we specify the `seriestype`. Try getting rid of this....

```{julia}
# plot the data using x and y, as a scatterplot
plot(x, y, seriestype=:scatter)
```

Superb. So, `StatsPlots` provides a special macro to use a dataframe with plots. It's a three step process:

1.  declare the `@df` macro
2.  define the data frame
3.  declare the columns, using the `:`

```{julia}
# plot the data using the data frame macro
# declare the df macro, declare the data frame, use : to signify columns
@df df plot(:x, :y)
```

And here, we use the df2, and plot variable b and c vs. a.

```{julia}
# the same, and plotting two y variables
@df df2 plot(:a, [:b, :c])
```

#### A quick briefing about data frames in Julia versus R and dplyr is here

[DataFrames Comparison R dplyr](https://dataframes.juliadata.org/stable/man/comparisons/#Comparison-with-the-R-package-dplyr)