Skip to content

Commit f100772

Browse files
MitchobMitchob
committed
Initial guide draft from BioCommons guide template
1 parent 264d9a5 commit f100772

9 files changed

Lines changed: 797 additions & 67 deletions

File tree

‎CITATION.cff‎

Lines changed: 37 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,38 @@
1-
cff-version: 0.0.0
2-
message: "Please cite as below."
1+
cff-version: 1.2.0
2+
title: BioShell how-to guide
3+
message: >-
4+
If you use this guide, please cite it using the metadata in this file.
5+
type: software
36
authors:
4-
- family-names: [family name goes here]
5-
given-names: [given names go here]
6-
orcid: [ORCID goes here]
7-
title: "Title of repository goes here"
8-
version: 0.0.0
9-
doi: [DOI goes here]
10-
date-released: YYYY-MM-DD
7+
- given-names: Mitchell
8+
family-names: O'Brien
9+
orcid: https://orcid.org/0000-0003-0662-9101
10+
affiliation: Sydney Informatics Hub, Australian BioCommons
11+
- given-names: Fred
12+
family-names: Jaya
13+
orcid: https://orcid.org/0000-0002-4019-7026
14+
affiliation: Sydney Informatics Hub, Australian BioCommons
15+
- given-names: Georgina
16+
family-names: Samaha
17+
orcid: https://orcid.org/0000-0003-0419-1476
18+
affiliation: Sydney Informatics Hub, Australian BioCommons
19+
- given-names: Wenjing
20+
family-names: Xue
21+
affiliation: National Computational Infrastructure, Australian BioCommons
22+
- given-names: Ziad
23+
family-names: Al Bkhetan
24+
orcid: https://orcid.org/0000-0002-4032-5331
25+
affiliation: Australian BioCommons
26+
- given-names: Andy
27+
family-names: Botting
28+
affiliation: Australian Research Data Commons, Nectar Research Cloud
29+
- given-names: Johan
30+
family-names: Gustafsson
31+
orcid: https://orcid.org/0000-0002-2977-5032
32+
affiliation: Australian BioCommons
33+
repository-code: https://github.com/Sydney-Informatics-Hub/How-to-Guide-BioShell
34+
url: https://sydney-informatics-hub.github.io/How-to-Guide-BioShell/
35+
license: CC-BY-4.0
36+
version: # AUTHOR TO SUPPLY — e.g. 1.0.0
37+
date-released: # AUTHOR TO SUPPLY — e.g. 2026-06-03
38+
doi: # AUTHOR TO SUPPLY — Zenodo DOI once minted

‎_config.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
title: How-to Guide
1+
title: BioShell
22
# This appears in the html browser tab for the site title (seen mostly by search engines, not users)
33

4-
#topnav_title: Website title
4+
#topnav_title: BioShell
55
# Optional: this appears on the top navigation bar next to the main_logo.svg icon
66

7-
description: "A bioinformatics focused How-to Guide"
7+
description: "A guide to accessing and using BioShell, a preconfigured cloud bioinformatics environment on NCI Nirin and ARDC Nectar Research Cloud."
88
# Metadata description of the website
99

1010
remote_theme: ELIXIR-Belgium/elixir-toolkit-theme@2.5.0

‎_data/CONTRIBUTORS.yml‎

Lines changed: 35 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,45 @@
1-
21
############################
32
### List of contributors ###
43
############################
54

65
### see https://github.com/ELIXIR-Belgium/elixir-toolkit-theme
76

8-
#############################################################################################################################################
9-
### add maintainers/contributors below and use their name in the contributors metadata section on each page they have contributed towards ###
10-
#############################################################################################################################################
7+
Mitchell O'Brien:
8+
git: Mitchob
9+
orcid: 0000-0003-0662-9101
10+
role: lead
11+
affiliation: Sydney Informatics Hub, Australian BioCommons
12+
13+
Fred Jaya:
14+
git: fredjaya
15+
orcid: 0000-0002-4019-7026
16+
role: author
17+
affiliation: Sydney Informatics Hub, Australian BioCommons
18+
19+
Georgina Samaha:
20+
git: georgiesamaha
21+
orcid: 0000-0003-0419-1476
22+
role: author
23+
affiliation: Sydney Informatics Hub, Australian BioCommons
1124

12-
# an example contributor is included below
13-
# example roles include "lead", "first-author", "author", "editor", "workflow-tester"
25+
Wenjing Xue:
26+
git: eileen-xue
27+
role: author
28+
affiliation: National Computational Infrastructure, Australian BioCommons
1429

15-
#Johan Gustafsson:
16-
# git: supernord
17-
# email: johan@biocommons.org.au
18-
# orcid: 0000-0002-2977-5032
19-
# role: author
20-
# affiliation: Australian BioCommons / University of Melbourne
30+
Ziad Al Bkhetan:
31+
git: ziadbkh
32+
orcid: 0000-0002-4032-5331
33+
role: author
34+
affiliation: Australian BioCommons
2135

36+
Andy Botting:
37+
git: andybotting
38+
role: author
39+
affiliation: Australian Research Data Commons, Nectar Research Cloud
2240

41+
Johan Gustafsson:
42+
git: supernord
43+
orcid: 0000-0002-2977-5032
44+
role: author
45+
affiliation: Australian BioCommons

‎_data/sidebars/main.yml‎

Lines changed: 53 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,53 @@
1-
#subitems:
2-
# - title: About
3-
# url: /index
4-
# - title: Standard example page
5-
# url: /example_page
6-
# - title: Workflow How-to Guide example pages
7-
# subitems:
8-
# - title: Example workflow guide page
9-
# url: /example_bioinformatics_workflow_page
10-
# - title: Example workflow documentation page
11-
# url: /example_workflow_documentation_page
12-
# - title: Contributors
13-
# url: /contributors
14-
1+
subitems:
2+
- title: Home
3+
url: /index
4+
- title: Accessing BioShell
5+
url: /access
6+
subitems:
7+
- title: Eligibility and acceptable use
8+
url: /access#eligibility
9+
- title: Your access pathway
10+
url: /access#pathways
11+
- title: Access duration and renewal
12+
url: /access#duration
13+
- title: Connecting to BioShell
14+
url: /access#connecting
15+
- title: Using BioShell
16+
url: /using-bioshell
17+
subitems:
18+
- title: Choosing a flavour
19+
url: /using-bioshell#flavours
20+
- title: Reproducible tools
21+
url: /using-bioshell#tools
22+
- title: Bio-Shelley
23+
url: /using-bioshell#bio-shelley
24+
- title: Reference datasets
25+
url: /using-bioshell#reference-data
26+
- title: Interactive environments
27+
url: /using-bioshell#interactive
28+
- title: Using Nextflow with CVMFS
29+
url: /using-bioshell#nextflow
30+
- title: Advanced — manual SHPC
31+
url: /using-bioshell#shpc-manual
32+
- title: BioShell in practice
33+
url: /community
34+
subitems:
35+
- title: Training workshops
36+
url: /community#training
37+
- title: Research outcomes
38+
url: /community#research
39+
- title: Get involved
40+
url: /community#get-involved
41+
- title: About
42+
url: /about
43+
subitems:
44+
- title: How to cite
45+
url: /about#cite
46+
- title: Contributors
47+
url: /about#contributors
48+
- title: Acknowledgements
49+
url: /about#acknowledgements
50+
- title: References
51+
url: /about#references
52+
- title: Contributors
53+
url: /contributors

‎index.md‎

Lines changed: 68 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,76 @@
11
---
2-
title: How-to Guide landing page template
3-
type: template
4-
contributors:
5-
description: Add a plain text description here.
6-
affiliations:
2+
title: BioShell
3+
description: A guide to accessing and using BioShell, a preconfigured cloud bioinformatics
4+
environment available on NCI Nirin and ARDC Nectar Research Cloud.
75
sidebar: false
86
---
97

8+
## Introduction
109

11-
**Replace the text below with your guide content!**
10+
BioShell is a ready-to-use cloud bioinformatics environment designed to get you from data to
11+
results with as little setup as possible. Rather than spending time configuring software on
12+
your own machine, you connect to BioShell and find a fully equipped workspace already waiting
13+
for you — with the tools, compute power, and interactive environments you need to run analyses
14+
that would be impractical on a laptop.
1215

13-
Example templates that you could use for different guides are available in this repository:
16+
BioShell is available through NCI Nirin and ARDC Nectar Research Cloud and is designed for
17+
researchers and learners at all stages. Whether you are a higher degree student running your
18+
first bioinformatics analysis, a trainer delivering a national workshop, or a researcher who
19+
needs a consistent and reproducible environment to share with collaborators, BioShell removes
20+
the technical overhead so you can focus on your science.
1421

15-
- [Standard page that can be used as a starting point for any type of guide.](example_page)
16-
- [Suggested structure for a guide describing how to use a bioinformatics workflow](example_bioinformatics_workflow_page)
17-
- [Suggested structure for documentation describing a workflow: based on Australian BioCommons documentation guidelines](example_workflow_documentation_page)
22+
This guide walks you through requesting access, choosing the right environment for your work,
23+
and using BioShell's built-in tools and support features. It assumes you are comfortable
24+
with basic command-line navigation, but no prior experience with cloud infrastructure,
25+
containers, or software installation is needed. BioShell is developed by Australian BioCommons
26+
as part of the [ABLeS programme](https://australianbiocommons.github.io/ables/) and supports
27+
the BioCommons Training cooperative and
28+
[Bioinformatics ToolFinder](https://australianbiocommons.github.io/2_tools.html).
1829

19-
Use cases for different guides are described in the [How-to Guide for using this template](https://australianbiocommons.github.io/how-to-guide-template/how_to_guide_types).
30+
> **Note:** This guide does not cover how to provision a virtual machine on Nectar or NCI, or
31+
> how to build a BioShell instance from scratch. See the
32+
> [BioShell GitHub repository](https://github.com/AustralianBioCommons/BioShell) and the
33+
> infrastructure documentation for those topics.
34+
35+
---
36+
37+
## Quick start guide
38+
39+
1. [Check you are eligible](/access#eligibility) — confirm your project is life-science
40+
related and aligns with the five ABLeS principles.
41+
2. [Identify your access pathway](/access#pathways) — most users apply through
42+
[ABLeS](https://australianbiocommons.github.io/ables/eligibility); training organisers
43+
contact the [BioCommons Training Team](https://www.biocommons.org.au/event-support).
44+
3. [Submit your access request](/access#requesting-access) — submit via the appropriate
45+
pathway and wait for your infrastructure placement to be confirmed.
46+
4. [Accept your terms and conditions](/access#terms) — accept the terms for your assigned
47+
infrastructure before access is granted.
48+
5. [Connect to your BioShell environment via SSH](/access#connecting) — use the connection
49+
details provided in your provisioning notification.
50+
6. [Choose your flavour](/using-bioshell#flavours) — select the preconfigured environment
51+
profile that matches your task.
52+
7. [Load a tool and run your analysis](/using-bioshell#tools) — use Bio-Shelley or
53+
`module load` to access tools from the BioShell tool library.
54+
8. [Launch an interactive environment](/using-bioshell#interactive) — open JupyterLab or
55+
RStudio directly in your browser for notebook-based work.
56+
57+
> **Tip:** Not sure which tools are available or how to load them? Run
58+
> `shelley-bio search "<what you want to do>"` for instant suggestions.
59+
60+
---
61+
62+
## How to cite
63+
64+
If you use BioShell in your research or training, please cite it as:
65+
66+
> O'Brien M, Jaya F, Samaha G, Xue W, Al Bkhetan Z, Botting A, Gustafsson J. (2026).
67+
> **BioShell how-to guide**. Australian BioCommons.
68+
> [AUTHOR TO SUPPLY — Zenodo DOI once minted]
69+
70+
---
71+
72+
![](images/bioshell/SCREENSHOT_NEEDED_overview_diagram.png)
73+
74+
*Fig 1. Overview of the BioShell access and use flow: from submitting an access request
75+
through to connecting, choosing a flavour, loading tools, and launching interactive
76+
environments.*

‎pages/about.md‎

Lines changed: 63 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,81 @@
11
---
2-
title: About page template
3-
type: template
4-
contributors:
5-
description: Add a plain text description here.
6-
affiliations:
7-
sidebar: false
2+
title: About
3+
description: How to cite this guide, contributor acknowledgements, and references.
84
---
95

6+
## How to cite this guide {#cite}
107

11-
## About
8+
If you use this guide in your research or training, please cite it as:
129

13-
> Add 2-3 sentences here explaining the purpose of the specific guide you are creating.
10+
> O'Brien M, Jaya F, Samaha G, Xue W, Al Bkhetan Z, Botting A, Gustafsson J. (2026).
11+
> **BioShell how-to guide**. Australian BioCommons.
12+
> [AUTHOR TO SUPPLY — Zenodo DOI once minted]
1413
14+
[AUTHOR TO SUPPLY — add bio.tools entry URL once registered]
1515

16-
## Guide sections
17-
18-
> You can use this section to add navigation tiles for the pages you have created as part of your guide.
16+
[AUTHOR TO SUPPLY — add WorkflowHub entry URL once registered]
1917

18+
---
2019

21-
## Please cite this guide as follows
20+
## Contributors {#contributors}
2221

23-
> [Citation information goes here]
22+
| Name | GitHub | ORCID |
23+
|------|--------|-------|
24+
| Mitchell O'Brien | [@Mitchob](https://github.com/Mitchob) | [0000-0003-0662-9101](https://orcid.org/0000-0003-0662-9101) |
25+
| Fred Jaya | [@fredjaya](https://github.com/fredjaya) | [0000-0002-4019-7026](https://orcid.org/0000-0002-4019-7026) |
26+
| Georgina Samaha | [@georgiesamaha](https://github.com/georgiesamaha) | [0000-0003-0419-1476](https://orcid.org/0000-0003-0419-1476) |
27+
| Wenjing Xue | [@eileen-xue](https://github.com/eileen-xue) | — |
28+
| Ziad Al Bkhetan | [@ziadbkh](https://github.com/ziadbkh) | [0000-0002-4032-5331](https://orcid.org/0000-0002-4032-5331) |
29+
| Andy Botting | [@andybotting](https://github.com/andybotting) | — |
30+
| Johan Gustafsson | [@supernord](https://github.com/supernord) | [0000-0002-2977-5032](https://orcid.org/0000-0002-2977-5032) |
2431

32+
---
2533

26-
## Acknowledgements
34+
## Acknowledgements {#acknowledgements}
2735

28-
> Don't delete anything from this section, only add.
36+
The authors acknowledge the support of Australian BioCommons which is enabled by NCRIS via
37+
Bioplatforms Australia funding.
2938

30-
This guide makes use of the [ELIXIR toolkit theme](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme)
39+
This guide makes use of the [ELIXIR toolkit theme](https://github.com/ELIXIR-Belgium/elixir-toolkit-theme).
3140

3241
{% include image.html file="elixir-toolkit-theme_logo.svg" alt="Elixir Toolkit Theme logo" max-width="15em" %}
3342

34-
## References
43+
This guide is part of the [ABLeS programme](https://australianbiocommons.github.io/ables/),
44+
which supports life science research computing across Australian national infrastructure.
45+
BioShell is available through [ARDC Nectar Research Cloud](https://ardc.edu.au/services/ardc-nectar-research-cloud/)
46+
and [NCI Nirin](https://nci.org.au/our-systems/cloud-computing).
47+
48+
---
49+
50+
## References {#references}
51+
52+
1. Gustafsson J, et al. (2023). Enabling national step changes in bioinformatics through
53+
ABLeS, the Australian BioCommons Leadership Share (3.0). Zenodo.
54+
https://doi.org/10.5281/zenodo.10139651
55+
56+
2. CernVM-FS documentation. https://cvmfs.readthedocs.io/en/stable/
57+
58+
3. Singularity Registry HPC (SHPC) documentation.
59+
https://singularity-hpc.readthedocs.io/
60+
61+
4. BioContainers registry. https://biocontainers.pro/registry
62+
63+
5. Galaxy Project CVMFS repositories. https://galaxyproject.org/admin/cvmfs/
64+
65+
6. Nextflow documentation. https://www.nextflow.io/docs/latest/
66+
67+
7. nf-core community. https://nf-co.re/
68+
69+
8. FastQC. https://bio.tools/fastqc
70+
71+
9. samtools. https://bio.tools/samtools
72+
73+
10. plink. https://bio.tools/plink
74+
75+
11. bwa. https://bio.tools/bwa
76+
77+
12. STAR. https://bio.tools/star
78+
79+
13. SPAdes. https://bio.tools/spades
3580

36-
> Add references as needed.
81+
14. GATK. https://bio.tools/gatk

0 commit comments

Comments
 (0)