prerequisites.qmd

---
title: "Pre-requisites and Software"
author: "Jenny Smith"
format: 
  html:
    code-fold: false
    code-tools: false
---

::: callout-tip
## Overview

This page contains README's and internal lab documentation on how to contribute to the Meshinchi lab and Locatelli lab github organizations. Be sure to have the software requirements installed in order to use this guide.
:::

## Operating System

These steps can be followed using a **Linux operating system**, like [Ubuntu](https://ubuntu.com/), or on macbook with [**MacOS**](https://www.apple.com/os/macos/). 

::: callout-important
Team members with Windows PCs will need to use [WSL](https://learn.microsoft.com/en-us/windows/wsl/about) to follow these installation instructions. 

See [Installation of Software on Windows WSL](details/software_install_wsl.qmd) for detailed instructions. 
:::

## Software

We will be using `R`, `Python`, `git`, `gh`, and `Quarto`, with the integrated development editors (IDE) `Rstudio` and `VSCode`. Click on the links below to install the required software.

::: {.external target="_blank"}

-   [**R and Rstudio**](https://posit.co/download/rstudio-desktop/)
-   [**Python**](https://www.python.org/downloads/)
-   [**Github CLI**](https://cli.github.com/)
-   [**Quarto CLI**](https://quarto.org/docs/download/)
-   [**Visual Studio Code**](https://code.visualstudio.com/)

Alternatively, use **Posit cloud** (formerly Rstudio Cloud). [Posit cloud](https://posit.cloud) is free of charge for personal users, yet you need to [sign up](https://posit.cloud/plans/free) for a new user account and have internet connection.

## VS Code Extensions

Install the [Quarto Extension](https://marketplace.visualstudio.com/items?itemName=quarto.quarto) for VS Code provides a variety of tools for working with .qmd files in VS Code. The extension integrates directly with the [Python Extension](https://marketplace.visualstudio.com/items?itemName=ms-python.python) to add Python-specific capabilities.


## Git and Github 

To get started, you will need to authenticate your access to the lab github organization so that you can create repositories and push changes. 

::: callout-important
Your github account (also known as your github profile), must be invited to the lab github organization before this can be completed. 
:::

0. Set-up a Github Account and get added as a member to the Lab organization

Github profiles should have a clear/professional profile photo to ensure that profiles look complete and reliable. Also, each account will need to [set-up 2FA (2 factor authentication)](https://docs.github.com/en/authentication/securing-your-account-with-two-factor-authentication-2fa/configuring-two-factor-authentication#configuring-two-factor-authentication-using-text-messages).


1. Configure `git` for your github username and email account associated with your github account. 

Open a new a new terminal and enter the following commands.

```bash
# print out the current configuration 
git config --global --list
# if not already set, configure them. This example assumes you are using a gmail account.
git config --global user.name MY_GITHUB_USERNAME
git config --global user.email MY_GITHUB_EMAIL@gmail.com
git config --global init.defaultbranch main
```

2. Authenticate the `gh` CLI tool to connect to the lab github organization.

Enter the following commands in the terminal. You will be prompted to `? Authenticate Git with your GitHub credentials? (Y/n)` and select 'Yes'. Follow the prompts on the command line to open a new web browser window to enter your username and password for github.

```bash
# login to github using a web browser
gh auth login --git-protocol 'HTTPS' --hostname GitHub.com --web

# check that you are now authenticated
gh auth status
```

Once you see this message that you are logged in, you were successfully authenticated. 

>   ✓ Logged in to github.com account MY_GITHUB_USERNAME (keyring)
>  - Active account: true
>  - Git operations protocol: https
>  - Token: gho_************************************
>  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'

## Data

The lab NGS datasets can be found here: [**Data Management**](data_management.html)

## Code

The `R` and `Python` packages, scripts, analysis notebooks, and data processing pipelines can be found at the [Meshichi Lab github organization](https://github.com/Meshinchi-Lab).

Repositories have the following nomenclature for easy searching:

-   Data Analysis and Research Projects with collaborators:

    -   `[YEAR-MONTH-DAY]_[DATA-TYPE]_[SHORT-DESCRIPTION]`

        -   **Example**: '2025-06-02_RNAseq_Bulk_T-ALL'

        -   **Example** with two data types: '2025-06-02_RNAseq_WGS_Bulk_T-ALL'

-   Genomic Data pipelines and workflows:

    -   `[DATA-TYPE]_[DATA-PROCESSING]_[WORKFLOW-TYPE]`

        -   **Example**: 'RNAseq_Fusion_Calling_Nextflow'

-   R packages:

    -   `[SHORT-NAME]_R_Package`

        -   **Example**: 'DeGSEA_R_Package'

-   Python packages:

    -   `[SHORT-NAME]_Py_Package`

        -   **Example**: 'DataValidator_Py_Package'

## Getting Started

See the [**Getting Started**](git_github_overview.html) page for the next steps to generate a new analysis or workflow code repository on the github.

If you still need to gain a working knowledge of using `bash`, `R`, and `Python`, then see the following [Resources](prerequisites.html#resources) section below.

## Resources

### Bash and Command Line Tutorial

A good place to start getting familair with common bash commands is to read the following [tutorial](https://www.w3schools.com/bash/bash_commands.php). Be sure to complete the exercises in the box at the bottom of each page, starting with the `ls` command.

For more intermediate bash scripting, you can follow the tutorial [here](https://www.freecodecamp.org/news/bash-scripting-tutorial-linux-shell-script-and-command-line-for-beginners/).s

### Quarto and Visual Studio Code Quick Start

The quarto CLI with VS Code editor [quick start](https://quarto.org/docs/get-started/hello/vscode.html) is a great tutorial to get familiarized with using quarto (.qmd) documents to generate exploratory analysis notebooks and reports.

### R and Rstudio Tutorial

The [RStudio user guide](https://docs.posit.co/ide/user/ide/get-started/) can help you get started with the RStudio user interface, installing your first packages, and generating a quick plot using data.

Detailed descriptions of the RStudio panels, panes, and tabsets can be [found here](https://docs.posit.co/ide/user/ide/guide/ui/ui-panes.html) as well.

### Python Tutorial

Start by learning how the VS Code editor displays and runs [python code](https://code.visualstudio.com/docs/python/python-quick-start).

Next, you can follow along with the [python tutorial](https://www.w3schools.com/python/python_intro.asp) using both the VS Code editor and interactively in a web browser by using the 'try it yourself' buttons.

:::