git_github_overview.qmd

---
title: "Getting Started"
format: 
  html:
    code-fold: false
    code-tools: true
    toc: true
    number-sections: true
author: "Jenny L. Smith"
---

::: callout-tip
## Standardization of Code Repositories

1.  Naming conventions for `github` repositories
2.  Initializing the code repository using `git` and `github`
3.  Using data analysis quarto templates

:::

## Github Repository Naming Conventions

Repositories have the following nomenclature for easy searching:

1.  Exploratory 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'

2.  Genomic Data pipelines and workflows:

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

          -   **Example**: 'RNAseq_Fusion_Calling_Nextflow'

3. R packages:

    -   `[SHORT-NAME]_R_Package`

        -   **Example**: 'DeGSEA_R_Package'

4. Python packages:

    -   `[SHORT-NAME]_Py_Package`

        -   **Example**: 'DataValidator_Py_Package'

### Example

0. First create a folder (directory) name following the standardized naming conventions listed above.

``` bash
DATA_TYPE="RNAseq" 
DESCRIPTION="Example_Repo" 
OUTDIR="$(date +%Y-%m-%d)_${DATA_TYPE}_${DESCRIPTION}"

echo $OUTDIR
```

This will create a variable that is has the value set as the string `2025-06-17_RNAseq_Example_Repo`.



## Create the Data Analysis Notebook Template

::: panel-tabset

## R 

1. Create a ***private*** remote repository in the Meshinchi-Lab lab github organization. 

Then repository name format is the organization name `Meshinchi-Lab/` followed by the name of the analysis directory you just created. 

``` bash
REPO="Meshinchi-Lab/${OUTDIR}"

echo $REPO
```

This will create a variable that is set as the string `Meshinchi-Lab/2025-06-17_RNAseq_Example_Repo`.

``` bash
gh repo create $REPO \
--description "An example R analysis template repo" \
--template "Meshinchi-Lab/r_analysis_template" \
--clone \
--private
```

If `gh repo create` command is successful, you will see:

> ✓ Created repository Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo on GitHub
>   https://github.com/Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo
> ✓ Added remote https://github.com/Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo.git


2. Change directories (`cd`) into the new github repository you've just cloned (by using the `--clone` argument in step 1).

Make sure to use `git pull` in order to have your local repository in sync with your new local repository.

``` bash
cd $OUTDIR && git pull origin main
```

3. Use the `quarto` CLI to download the quarto markdown template and follow the prompts:

- ? Do you trust the authors of this template (Y/n) › **Yes**
- ? Create a subdirectory for template? (Y/n) › **No**

``` bash
quarto use template Meshinchi-Lab/r_analysis_template
```

You will see the following output: 

> Downloading \[###################################\] 0.0 

> \[✓\] Downloading 

> \[✓\] Unzipping 

> Preparing template files... 

> \[✓\] Copying files... 

> Files created: 

> - 2025-06-16_RNAseq_Example_Repo.qmd


The `2025-06-16_RNAseq_Example_Repo.qmd` will be the template for the EDA report. You can rename it if you want. You can now open the `.qmd` file in your text editor and start editing it. 

In this case, the qmd file is named the same as the directory you created, eg `2025-06-16_RNAseq_Example_Repo.qmd`. If you've renamed the qmd, be sure to use the right value for the "$FILE" variable.

``` bash
FILE="${OUTDIR}.qmd"

echo $FILE
```

## Python

1. Create a ***private*** remote repository in the Meshinchi-Lab lab github organization. 

Then repository name format is the organization name `Meshinchi-Lab/` followed by the name of the analysis directory you just created. 

``` bash
REPO="Meshinchi-Lab/${OUTDIR}"

echo $REPO
```

This will create a variable that is set as the string `Meshinchi-Lab/2025-06-17_RNAseq_Example_Repo`.

``` bash
gh repo create $REPO \
--description "An example py analysis template repo" \
--template "Meshinchi-Lab/py_analysis_template" \
--clone \
--private
```

If `gh repo create` command is successful, you will see:

> ✓ Created repository Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo on GitHub
>   https://github.com/Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo
> ✓ Added remote https://github.com/Meshinchi-Lab/2025-06-16_RNAseq_Example_Repo.git


2. Change directories (`cd`) into the new github repository you've just cloned (by using the `--clone` argument in step 1).

Make sure to use `git pull` in order to have your local repository in sync with your new local repository.

``` bash
cd $OUTDIR && git pull origin main
```

Use the `quarto` CLI to download the quarto markdown template and follow the prompts:

- ? Do you trust the authors of this template (Y/n) › **Yes**
- ? Create a subdirectory for template? (Y/n) › **No**

``` bash
quarto use template Meshinchi-Lab/py_analysis_template
```

You will see the following output: 

> Downloading \[###################################\] 0.0 

> \[✓\] Downloading 

> \[✓\] Unzipping 

> Preparing template files... 

> \[✓\] Copying files... 

> Files created: 

> - 2025-06-16_RNAseq_Example_Repo.qmd


The `2025-06-16_RNAseq_Example_Repo.qmd` will be the template for the EDA report. You can rename it if you want. You can now open the `.qmd` file in your text editor and start editing it. 

In this case, the qmd file is named the same as the directory you created, eg `2025-06-16_RNAseq_Example_Repo.qmd`. If you've renamed the qmd, be sure to use the right value for the "$FILE" variable.

``` bash
FILE="${OUTDIR}.qmd"
echo $FILE
```

Then convert the qmd template to ipython notebook (.ipynb) that can be used for EDA analyses. 

``` bash
quarto convert $FILE
```

:::

## Install Dependencies and Render 

::: {.panel-tabset}

## R

Create a virtual environment using `renv` and then install the project dependencies.

``` bash
Rscript -e "renv::activate()"
Rscript -e "renv::restore()"
```

When you are ready to render the HTML report, run:

``` bash
quarto render $FILE
```

## Python

Create a virtual environment using `venv` and then install the initial project dependencies. 

``` bash
python3 -m venv venv 
source venv/bin/activate 
python3 -m pip install -r requirements.txt
```

When you are ready to render the HTML report, run:

``` bash
IPYNB="${OUTDIR}.ipynb"
echo $IPYNB
quarto render $IPYNB
```

:::

## Commit Changes

1. First, add the quarto analysis template qmd file. 

In this case, the qmd file is named the same as the directory you created, eg "2025-06-16_RNAseq_Example_Repo.qmd". If you've renamed the qmd before committing the file, be sure to use the right name for the "$FILE" variable.

``` bash
FILE="${OUTDIR}.qmd"
git status
git add $FILE
git status
```

2. Commit the new template qmd file.

And use `git log` to see what changes were made, for example if you come back late to continue. 

``` bash
git commit -m "Added analysis template"
git log --oneline
```

When you make changes to the analysis qmd and create any new files, you will repeat steps 1 and 2 here. This is summarized in the section below.

## Summary 

In summary, after creating the github repository with the analysis quarto template, you will be repeating the commands below as you make edits. 

1. Ensure the virtual environment is up-to-date and activated. 

For R

``` bash
Rscript -e "renv::activate()"
Rscript -e "renv::status()"
```

For Python

``` bash
source venv/bin/activate 
which python
```

2. Use these 5 git commands as you make changes to files, and install software dependencies

``` bash
git pull
git status
git add [MY FILE THAT CHANGED] [A NEW FILE]
git commit -m "describe what changed"
git status
git log --oneline
```