diff --git a/.gitignore b/.gitignore index 1a68b4a..225bb27 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .DS_Store .venv/ .vscode +site/ diff --git a/docs/img/bryn-notebook.png b/docs/img/bryn-notebook.png new file mode 100644 index 0000000..1649bfe Binary files /dev/null and b/docs/img/bryn-notebook.png differ diff --git a/docs/index.md b/docs/index.md index 3a62a65..4843ee6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,13 +2,18 @@ ![CLIMB-BIG-DATA](img/climb_big_data_white_450px.png){ width=250 style="background-color: black;" } -Welcome to the CLIMB-BIG-DATA documentation! +Welcome to the [CLIMB-BIG-DATA](https://climb.ac.uk/) documentation! These docs are designed to help you get the best out of the CLIMB-BIG-DATA infrastructure. -### Getting started +## Getting started -How to access CLIMB-BIG-DATA and find your way around via the Bryn web interface. +How to access CLIMB-BIG-DATA and find your way around via the **Bryn** web interface. +[Bryn](https://bryn.climb.ac.uk) is the web interface for CLIMB-BIG-DATA, and is the primary way to access the infrastructure. +From Bryn you can manage your team, its resources, the S3 buckets and your notebooks. **CLIMB Notebooks**, on the other hand, +are Jupyter notebooks fully integrated with CLIMB and its storage, with first-class support to Nextflow pipelines. + +![Bryn vs CLIMB notebook](img/bryn-notebook.png){ width=600 style="background-color: white; margin: auto;" } [Registration](getting-started/how-to-register.md) How to register and access CLIMB-BIG-DATA. @@ -16,7 +21,7 @@ How to register and access CLIMB-BIG-DATA. [Authentication](getting-started/authentication.md) How to login to Bryn, and setup two-factor authentication. -### Notebook Servers +## Notebook Servers Everything you need to understand, use and get the most out of Jupyter Notebook Servers. @@ -29,7 +34,7 @@ How to launch, access and get started using a notebook server. [Using the terminal](notebook-servers/using-the-terminal.md) How to use the terminal inside a notebook server, with an explanation of caveats. -[Using VS Code](using-vscode.md) +[Using Visual Studio Code](notebook-servers/using-vscode.md) How to connect to your CLIMB Notebook using VS Code [Understanding storage](storage/index.md) @@ -47,7 +52,7 @@ A simple walk-through of some CLIMB-BIG-DATA functionality. [QIIME 2](walkthroughs/qiime2.md) How to install QIIME 2 on a notebook server and basic usage. -[nf-core pipelines](walkthroughs/nfcore.md) +[nf-core pipelines](walkthroughs/nfcore.md) How to run some of the nf-core pipelines on CLIMB notebooks [How to fix login error 403](notebook-servers/403-forbidden-error.md) diff --git a/docs/notebook-servers/img/tabs.png b/docs/notebook-servers/img/tabs.png new file mode 100644 index 0000000..fe9ca79 Binary files /dev/null and b/docs/notebook-servers/img/tabs.png differ diff --git a/docs/notebook-servers/img/tabs2.png b/docs/notebook-servers/img/tabs2.png new file mode 100644 index 0000000..b09b991 Binary files /dev/null and b/docs/notebook-servers/img/tabs2.png differ diff --git a/docs/notebook-servers/index.md b/docs/notebook-servers/index.md index 9865826..e3b0565 100644 --- a/docs/notebook-servers/index.md +++ b/docs/notebook-servers/index.md @@ -20,7 +20,7 @@ How to install software using Conda, in the context of a containerized environme [Using Nextflow](using-nextflow.md) How to use Nextflow with CLIMB-BIG-DATA. -[Using Visual Studio Code](using-vscode.md) +[Using Visual Studio Code](using-vscode.md) How to connect to your CLIMB Notebook and work from Visual Studio Code [How to fix login error 403](403-forbidden-error.md) diff --git a/docs/notebook-servers/using-interface.md b/docs/notebook-servers/using-interface.md new file mode 100644 index 0000000..3349efa --- /dev/null +++ b/docs/notebook-servers/using-interface.md @@ -0,0 +1,60 @@ +# Using the Jupiter Notebook Interface + +![Screenshot](img/tabs.png) + +The Jupyter notebooks are easy to use yet powerful. The interface, for example, allows to: + +* Easily navigate the **file system**, to create, upload, download and manage files and directories. +* Have multiple tabs, that can be arranged and *snapped* to a corner, to a side, bottom or top of the "snapping area". +* Tabs can be: + * One or more **terminal** tabs, to run commands and scripts. + * One or more **notebook** tabs, to write and run code, and to create and manage documents. + * One or more **text editor** tabs, to write and edit text files. You can directly edit the text (and save it) from the interface. + * Built in preview for HTML files (for example, MultiQC reports), tables (csv, tsv, etc.), and images. + +The interface consists of four main components: + +![Notebook panel](img/tabs2.png) + +1. The **menu bar**, where you can access settings (including font size etc.), and manage the notebook. +2. The side bar will allow you to select the appropriate side tab. +3. The **side area**, which is by default set to the **File Browser**. From here you can navigate directories and upload/download files. You can quickly upload a file by dragging it from your computer and dropping it in the file browser. + 1. Right-clicking to a file will allow you to download it, rename it, or to "open it" with the appropriate application. +4. The **snapping tabs area**, where you can place all your open tabs, and arrange them as you like. + + +## Common tasks + +### Quickly upload some files to the Notebook + +1. Use the side bar (File Browser) to navigate to the appropriate location. Remember that your home directory is not a safe place for storage, and that you should use the `shared-team` directory for your data. +2. If appropriate, create a new sub directory (e.g. right click in the white area of the file browser and select "New Folder", then type a name for it) +3. On your local computer, open the directory with the files you want to upload. +4. Drag the files from your local computer and drop them in the file browser of the notebook interface. +5. If the file size is relevant you will get a warning. For very large uploads, you should consider using the S3 storage instead. + + +### Edit a file and save it + +1. Use the side bar (File Browser) to navigate to the appropriate location. +2. Some files will open in an editor automatically, otherwise right click on the file and select **"Open with" -> "Editor"**. +3. When you edit the file, a dot (⚫️) will appear in the tab, indicating that the file has been modified. +4. Use `Ctrl + S` to save the file (or `Cmd + S` on macOS), or click the save button in the editor. + +### Live preview of a (supported) file + +1. Use the side bar (File Browser) to navigate to the appropriate location. +2. Right click on the file and select **"Open with" -> "Editor"**. +3. Now right-click again on the file and select **"Open with" -> "CSV Previe"** (or other supported preview: like Markdown, HTML...). +4. When you edit and **save** the file with the editor, the preview will update automatically. + +💡 You can use a similar arrangement to keep, for example, a script editor on your left and a terminal to run the script on your right. + +### Using the Python notebook with custom libraries + +1. Open a terminal tab. +2. Create a new environment with the requested libraries plus `ipykernel`, using `conda create -n EnvName ... ipykernel`. Suppose you want to create an environment called `dataexplorer` with Pandas, Seaborn, and Matplotlib, you would use `conda create -n dataexplorer pandas seaborn matplotlib ipykernel`. +3. Open the launcher, and you will see a new icon with the environment name under the Python Icon. Click on it to create a new notebook with the new environment. +4. From that notebook you will be able to `import pandas as pd`, for example. + +See: [Using Jupyter](using-jupyter.md) for more details. \ No newline at end of file diff --git a/docs/notebook-servers/using-jupyter.md b/docs/notebook-servers/using-jupyter.md index 9443b14..cf234a8 100644 --- a/docs/notebook-servers/using-jupyter.md +++ b/docs/notebook-servers/using-jupyter.md @@ -64,7 +64,7 @@ These are just some of the basic Markdown syntax elements you can use to format | `*Italic Text*` | *Italic Text* | | `~~Strikethrough~~` | ~~Strikethrough~~ | | `[Link](https://climb.ac.uk/)` | [Link](https://climb.ac.uk/) | -| `![Image Alt Text](image.jpg)` | ![Image Alt Text](image.jpg) | +| `![Image Alt Text](image.jpg)` | ![Image Alt Text](https://picsum.photos/80/80) | | `1. Item 1` | 1. Item 1 | | `2. Item 2` | 2. Item 2 | | `- Unordered List` | - Unordered List | diff --git a/docs/walkthroughs/metagenomics-tutorial.md b/docs/walkthroughs/metagenomics-tutorial.md index 7389cff..ae8c8c1 100644 --- a/docs/walkthroughs/metagenomics-tutorial.md +++ b/docs/walkthroughs/metagenomics-tutorial.md @@ -285,7 +285,7 @@ head(df) ``` - +
@@ -318,7 +318,7 @@ df %>% -![svg](output_47_0.svg) +![svg](output_46_0.svg) diff --git a/mkdocs.yml b/mkdocs.yml index fd9f38d..5f78725 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,6 +44,7 @@ nav: - notebook-servers/index.md - "Read This First!": "notebook-servers/read-this-first.md" - "Quick start": "notebook-servers/quick-start.md" + - "Using the interface": "notebook-servers/using-interface.md" - "Using the terminal": "notebook-servers/using-the-terminal.md" - "Using Jupyter notebooks": "notebook-servers/using-jupyter.md" - "Using RStudio": "notebook-servers/using-rstudio.md"
A tibble: 6 × 5
taxonomy_idnamerankpluspfpstandard16