start-project.qmd

# Starting a New Project 

These steps only need to be completed once, at the beginning of a project.

---

## Checklist ✅ {.unnumbered}

- [ ] Create a private repository by new project.  
- [ ] Add the Lab Team to the repository. 
- [ ] Clone the repository and associate it with an RStudio Project. 
- [ ] Add your Data folder to `.gitignore`. 
- [ ] Complete the `README` file using the template. 

---

::: {.callout-note appearance="simple"}
The most comprehensive book on using Git and GitHub for R users is [Happy Git and GitHub for the useR](https://happygitwithr.com/) [@bryan_happy_git]
:::


## Create a private repository by new project 

When starting to work on a new project, your first step is to create a **private** repository in the lab's GitHub organization: [StringhiniLab GitHub](https://github.com/StringhiniLab).

1. Click the green **New** button to open a window like this:

![](img/create_repository.png){width=70%}

2. Complete/select using the following criteria:

- [ ] **Owner**  
  Select `StringhiniLab` as the owner, not your personal GitHub account.

- [ ] **Repository Name**  
  Choose a name that represents your project. Since this repository will be private, append `_private` to the name.  
  For example, if the repository name is `chronic-diseases`, name it `chronic-diseases_private`.

- [ ] **Description**  
  Provide a more detailed description of the project here. This helps identify the repository's content in the organization.

- [ ] **Public or Private?**  
  Ensure the repository is set to `Private`.

- [ ] **Initialize Repository With**  
  Add a `README.md`.

Ignore the other options for now.  
If everything works, you’ll see your repository within [the GitHub organization](https://github.com/StringhiniLab) labeled as `Private`.

---

## Add the Lab Team to the repository

![](img/teams.png){width=100%}

1. **Navigate to the repository’s `Settings` tab.**  
In the left-hand sidebar, find and click on `Collaborators and teams`.  

2. Click **Add teams** and add `Lab Team`.  
By default, you will select the Read role for the team. The idea is that other Lab Members can view the repository but will not be able to edit it by mistake.

![](img/add-teams.png){width=70%}

This allows all current Lab Members to view (but not modify) your project.  
If you don't want to share an analysis with other Lab Members, you can create a repository in your personal GitHub account instead. However, **always ensure sensitive data is not pushed to GitHub** for confidentiality reasons.  

All repositories in `StringhiniLab` should be accessible to the Lab Team, which is why these repositories are hosted in the organization instead of personal accounts. Remember that individuals who are Owners of the organization can view all repositories even if there are not part of the Team.

---

## Clone the repository and associate it with an RStudio Project

::: {.callout-note appearance="simple"}

## Before start using RStudio:
We recommend changing the default option `Restore .RData into workspace at startup` as explained [in this section](https://docs.posit.co/ide/user/ide/get-started/index.html#blank-slate). [@rstudio_user_guide]

:::

1. **Open RStudio**  
   If RStudio is not installed, complete first the installation instructions in the Onboarding section.  

2. **Clone the Repository**  
   In RStudio:  
   `File` > `New Project` > `Version Control` > `Clone a Project from a Git Repository`.  
   
![](img/rstudio-versioncontrol.png){width=70%}
![](img/rstudio-versioncontrol2.png){width=70%}

 Go back to the repository and copy the repository’s URL.
   
   
   ![](img/github-url.png){width=70%}

And paste it in the correct field:

![](img/rstudio-versioncontrol3.png){width=70%}

If successful, you’ll see a folder containing your project, including the `README` file that we created on GitHub, in the `Files` tab at the bottom-right of RStudio. 

Note that an `.Rproj` icon has appeared. Clicking on this icon outside of RStudio will open RStudio directly within the project. 

Additionally, the project name now appears in the top-right corner. By opening that menu, you can easily switch between projects without leaving the RStudio IDE.

You’ll also notice a tab named Git in the top-right panel.

![](img/rstudio-project.png){width=100%}

::: {.callout-note appearance="simple"}

## Do you want to learn more about the use of RStudio and how to create projects?

- Check the [RStudio IDE User Guide](https://docs.posit.co/ide/user/) [@rstudio_user_guide]

- Read the [Projects section in Chapter 6](https://r4ds.hadley.nz/workflow-scripts.html#projects) of R for Data Science [@r4ds]
:::

---

### Add your Data folder to `.gitignore` 

We work with sensitive data. If working locally, create a `data` folder (e.g., click the `+ Folder` icon in the `Files` tab). Move your data files into this folder.  

Open the `.gitignore` file and add the line `data/`. This tells Git to ignore the contents of the `data` folder, preventing accidental data pushes.  

We recommend creating at least two sub-folders within `data/`:

- `raw/`: Use this folder to store the original datasets.
- `processed/`: Use this folder to save any datasets generated as preliminary or final results from your analyses.

If `data/` is listed in your `.gitignore` file, both subfolders will automatically be ignored by Git since they are located within the `data/` folder.

If the folder is not in the project root or has a different name, adjust the `.gitignore` settings accordingly.

Your project structure should look like this:

```
project-folder/ 
├── .gitignore # Specifies files and folders to ignore in version control 
├── README.md # Documentation about the project 
├── data/ # Folder to store datasets 
    ├── raw/ # Original datasets (never modified directly) │
    └── processed/ # Cleaned and processed datasets
```

::: {.callout-note appearance="simple"}

## What type of document should you use for your data analysis?

There are many files you can use run your code. You can use a [basic R script](https://r4ds.hadley.nz/workflow-scripts.html#scripts) [@r4ds], an RMarkdown document or its more current version Quarto.

If you're unsure where to start, we recommend using a Quarto Document. A Quarto document, just like RMarkdown, allows you to include code chunks throughout a text and save it as a Word, PDF, or HTML report. Combining text where you explain your reasoning and the details of the analysis with the code chunks makes it much easier to understand each section of code, both for yourself and for other readers.

- To use Quarto, you must first [install it](https://quarto.org/docs/get-started/)
- [Tutorial to learn how to create a document with Quarto](https://quarto.org/docs/get-started/hello/rstudio.html) [@quarto_hello_rstudio] 

It's important to note that there is a learning curve for using tools like Quarto. [Creating a simple R script](https://r4ds.hadley.nz/workflow-scripts.html#scripts) might be a good enough option if you're looking to start your analysis more straightforwardly.

**We encourage you to discuss this on the lab Slack to hear the experiences of other researchers. If any consensus emerges, feel free to open a New Issue [here](https://github.com/StringhiniLab/GitHubProceduresLab/issues) to improve this guide.**

:::

and you `.gitignore` file should look like this:

```
.Rproj.user
.Rhistory
.RData
.Ruserdata
data/
```

---

## Complete the `README` using the template

Before starting work, fill out the `README.md` file with the following information:  

````
# Title

## Author  
**Name:** [Your Name]  
**Email:** [Your Name]

## Start Date  
[YYYY-MM-DD]  

## Objective  
The objective of this project is to ...  

## Database Used and Version  
**Database Name:** [Name]
**Data Version:** [Specify version or date accessed]  

-[] Sensitive data is stored locally and excluded from version control using `.gitignore.`
-[] All analyses comply with the data use agreements.

## Project Structure  

chronic-diseases/
├── data/ # Folder for datasets
│ ├── raw/ # Original datasets (never modified directly)
│ └── processed/ # Cleaned and processed datasets
├── scripts/ # R scripts for analysis
├── outputs/ # Figures, tables, and other results
├── README.md # Project overview and documentation
└── .Rproj # RStudio project file

## Reproducibility
Run `sessionInfo()` in the console and paste the output between the two lines with backticks:

```

```  

````

There is more material available on organizing project structures [@ubclibrary], using `.gitignore` [@turing] or other resources listed [here](https://book.the-turing-way.org/project-design/sdpw/pd-sdp-resources), or creating good [README files](https://book.the-turing-way.org/project-design/project-repo/project-repo-readme) [@turing] and name conventions [@ubclibrary] if you want to explore further.

Additionally, UBC Library offers some basic data management courses that might be helpful to you: [Short courses](https://libcal.library.ubc.ca/calendar/?t=g&q=Data%20Bites&cid=-1&cal=-1&ct=339) [@ubclibrary]

## References {.unnumbered}