05-workspaces.Rmd

# (PART\*) Working on AnVIL {-}

# Workspaces

Workspaces are the building blocks of projects in Terra. Inside a Workspace, you can run analyses, launch interactive tools like RStudio and Galaxy, store data, and share results. 

To get a Workspace of your own, you can

- **Clone a Workspace**: Cloning an existing Workspace allows you to copy existing documentation, code, and/or data into your own experimental space.
- **Create a Workspace**: Creating a new Workspace from scratch allows you to fully customize the contents.

The video below gives a brief introduction to the parts of a Workspace.

<iframe src="https://drive.google.com/file/d/18WUmQfDnulHdaMlrH0Eh6kwIP3zTkaqp/preview" width="640" height="360" allow="autoplay"></iframe>

## Access Your Workspaces

If you are part of a research team, you may have been added to some existing Workspaces.  To find and access your Workspaces, follow the steps below.


```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_workspace_open.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

## Clone an Existing Workspace {#clone-workspace}

Cloning an existing Workspace allows you to copy existing documentation, code, and/or data into your own experimental space.

Cloning creates a new copy of the Workspace that will charge costs to the Billing Project of your choice. Note that you can only clone a Workspace if you are at least a "User" on the Terra Billing Project.  This helps prevent unwanted charges.  Workspaces charge money to their associated Billing Project, regardless of who conducts the activity, so it's important to be careful about who has permission to use the Workspace (see [Add Members to Workspace] for details).

If you need to clone a Workspace but don't have permission to create your own Workspaces, contact your PI or lab manager so that they can either grant you permission or clone the Workspace for you.

The following steps show you how to clone a Workspace that has already been developed by other AnVIL users. When cloning, AnVIL makes a copy of notebooks and code for you to modify. Data however, is linked back to the original Workspace through Data Tables, which saves space!

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_workspace_clone.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

## Create a New Workspace

Creating a new Workspace from scratch allows you to fully customize the contents.

Note that you can only create a new Workspace if you are at least a "User" on a Terra Billing Project.  This helps prevent unwanted charges.  Workspaces charge money to their associated Billing Project, regardless of who conducts the activity, so it's important to be careful about who has permission to use the Workspace (see [Add Members to Workspace] for details).

If you need to create a Workspace but don't have permission, contact your PI or lab manager so that they can either grant you permission or create the Workspace for you.

The following steps show you how to create a Workspace so you can get started.

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_workspace_create.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```

## Add Members to Workspace

Members can be added to a Workspace with a few different permission levels:

```{r, echo=FALSE, fig.alt='Table summarizing Workspace permission levels.'}
ottrpal::include_slide("https://docs.google.com/presentation/d/1hhdPNfuAhbwkl5LlNVlJiCIx_rbzVp3jSJJeksqiR5I/edit#slide=id.g117dd5f15db_0_584")
```

More details about the permissions associated with each Access Level can be found in the [Terra documentation](https://support.terra.bio/hc/en-us/articles/360025851892-Reader-writer-or-owner-Workspace-access-controls-explained).

Managing permissions for a Workspace has important implications:

- **Billing**: Terra charges are associated with Workspaces rather than users.  Any billable activity that takes place in a given Workspace will be charged to the associated Billing Project, regardless of who conducted the activity.  If there are multiple users with permission to compute, it is impossible to tell who conducted the activity.
- **Data access**: Especially when working with protected data, it’s important to ensure that users have proper authorization to view the data before giving them access to a Workspace containing the data.  Terra provides **Authorization Domains** to assist with this.

Make sure you understand what permissions you are granting before adding someone to your Workspace.

To add a member to a Workspace:

```{r, echo = FALSE, results='asis'}
cow::borrow_chapter(
  doc_path = "child/_child_workspace_share.Rmd",
  repo_name = "jhudsl/AnVIL_Template"
)
```