You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/tools.md
+30-90Lines changed: 30 additions & 90 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,7 @@ module avail
31
31
Then load what you need, for example `module load jupyter` or `module load rstudio`. Anything
32
32
not listed, you can install yourself with [**Shelley**](tutorials/shelley-howto).
33
33
34
-
## How BioShell manages bioinformatics software {#tooling-stack}
34
+
## How BioShell manages bioinformatics tools {#tooling-stack}
35
35
36
36
Bioinformatics often requires us to use many different software including command-line software, R and Python packages. BioShell gives you access to over 100,000 bioinformatics packages, managed in three layers for you:
37
37
@@ -41,140 +41,80 @@ Bioinformatics often requires us to use many different software including comman
41
41
-**[sHPC](https://singularity-hpc.readthedocs.io/)** packages containers in cvmfs into installable modules
42
42
-**[Lmod](https://lmod.readthedocs.io/en/latest/)** is the system behind the `module` command you use to load and switch tools
43
43
44
+
45
+
46
+
44
47
You don't need to undersand any of this to use BioShell because **Shelley**, BioShell's command-line assistant, drives all three for you. She:
45
48
46
49
* Searches the tool library
47
50
* Picks the right container version
48
51
* Creates any sHPC registry entry that is missing
49
52
* Installs the module: one command to find a tool, one to install it
50
53
51
-
52
54
53
-
## Finding and installing tools with Shelley :turtle: {#getting-started-with-shelley}
55
+
## Shelley basic usage :turtle: {#basic-usage}
54
56
55
-
Shelley runs from the command line or in an interactive mode. This walkthrough installs a tool
56
-
on a BioShell VM for the first time. Start by confirming Shelley is available:
57
+
Shelley runs from the command line or in an interactive mode. It can be used to manage your bioinformatics tool containers. We currently only support command-line tools and are working on extending this functionality out to R and Python packages.
58
+
59
+
Run Shelley with:
57
60
58
61
```bash
59
62
shelley help
60
63
```
61
64
62
-
You will see a list of available commands.
63
-
64
65
<detailsmarkdown="1">
65
66
<summary>Example output</summary>
66
67
67
68
<br>
68
69
</details>
69
70
<br>
70
71
71
-
### Find a tool you know by name
72
-
73
-
Say you already know you need `fastqc`. Look it up with `find`:
72
+
**From the command line:**
74
73
75
74
```bash
76
-
shelley find fastqc
75
+
shelley find <tool># Look up a specific tool by name
76
+
shelley search "<function>"# Search by keyword or function
77
+
shelley build <tool># Install the tool as a loadable module
77
78
```
78
79
79
-
<detailsmarkdown="1">
80
-
<summary>Example output</summary>
81
-
82
-
<br>
83
-
</details>
84
-
<br>
85
-
86
-
Shelley returns the tool's description, its most recent container versions, and whether it is
87
-
installed as a module yet. `find` is forgiving about naming: case, hyphens, and underscores are
88
-
all handled for you, so `shelley find STAR`, `shelley find bwa-mem2`, and `shelley find samtools`
89
-
all work as expected.
90
-
91
-
### See every available version
92
-
93
-
By default `find` shows only the most recent versions of a tool. To pin an exact version for
94
-
reproducibility, or to match a pipeline's requirements, add the `-v` (verbose) flag to see every
95
-
available container, newest first:
80
+
**In interactive mode:**
96
81
97
82
```bash
98
-
shelley find fastqc -v
83
+
shelley interactive # Launch Shelley in interactive mode
99
84
```
100
85
101
-
<detailsmarkdown="1">
102
-
<summary>Example output</summary>
103
-
104
-
<br>
105
-
</details>
106
-
<br>
86
+
Interactive mode works the same way as the command line. The `find`, `search`, and `build`
87
+
behave identically, except you type just the command name and its arguments, without
88
+
prefixing every call with `shelley`.
107
89
90
+
{% include callout.html type="tip" content="Follow our [Shelley tutorial](tutorials/shelley-howto.md) to practice using Shelley to find, search, and build modules." %}
108
91
109
-
### Search when you only know the task
92
+
##Reference genomes and indexes {#reference-data}
110
93
111
-
Sometimes you know what you want to do but not which tool does it. That's what `search` is for:
94
+
Reference genome builds and pre-built indexes, managed and maintained by the
95
+
[Galaxy Project](https://galaxyproject.org/admin/cvmfs/), sit in two directories:
112
96
113
97
```bash
114
-
shelley search "quality control"
115
-
shelley search "variant calling"
116
-
shelley search "de novo assembly"
98
+
ls /cvmfs/data.galaxyproject.org/byhand/ # by genome build, then index type
99
+
ls /cvmfs/data.galaxyproject.org/managed/ # by index type, then genome build
117
100
```
118
101
119
-
Each result shows the tool name and a brief description of what it does. **Shorter, more
120
-
specific phrases work better than full sentences** — every extra word broadens the match rather
121
-
than narrowing it, so remove words rather than adding them if you get too many results.
{% include callout.html type="note" content="Search is under active development. Results are broad and currently presented alphabetically." %}
131
102
103
+
To use a reference file in your analysis, pass its absolute path directly to your tool or
104
+
pipeline config. For example, the human CHM13 T2T v2.0 FASTA file is at:
132
105
133
-
### Build the module
134
-
135
-
Once you know the tool and version you want, build its module with `shelley build`:
136
-
137
-
```bash
138
-
shelley build fastqc
139
106
```
140
-
141
-
This installs the most recent available version by default.
142
-
143
-
<detailsmarkdown="1">
144
-
<summary>Example output</summary>
145
-
146
-
<br>
147
-
</details>
148
-
<br>
149
-
150
-
{% include callout.html type="tip" content="To install a specific version instead of the most recent one, give `build` the same `<tool>/<version>` spec that `find -v` showed you, for example `shelley build fastqc/0.12.1`." %}
151
-
152
-
### Load and run the tool
153
-
154
-
Load the module the same way you would on any HPC system, then run the tool:
{% include callout.html type="note" content="The reference datasets available through CVMFS are maintained by the Galaxy Project and may not be comprehensive. This is not a replacement for your institution's primary data access methods." %}
117
+
{% include callout.html type="note" content="The reference datasets available through CVMFS are maintained by the Galaxy Project and may not be comprehensive." %}
{% include callout.html type="note" content="Search is under active development. Results are broad and currently presented alphabetically." %}
71
+
72
+
73
+
### Build the module
74
+
75
+
Once you know the tool and version you want, build its module with `shelley build`:
76
+
77
+
```bash
78
+
shelley build fastqc
79
+
```
80
+
81
+
This installs the most recent available version by default.
82
+
83
+
<detailsmarkdown="1">
84
+
<summary>Example output</summary>
85
+
86
+
<br>
87
+
</details>
88
+
<br>
89
+
90
+
{% include callout.html type="tip" content="To install a specific version instead of the most recent one, give `build` the same `<tool>/<version>` spec that `find -v` showed you, for example `shelley build fastqc/0.12.1`." %}
91
+
92
+
### Load and run the tool
93
+
94
+
Load the module the same way you would on any HPC system, then run the tool:
22
95
23
96
```bash
24
-
shelley interactive # Launch Shelley in interactive mode
97
+
module load fastqc
98
+
fastqc --version
99
+
# FastQC v0.12.1
25
100
```
26
101
27
-
Interactive mode works the same way as the command line. The `find`, `search`, and `build`
28
-
behave identically, except you type just the command name and its arguments, without
29
-
prefixing every call with `shelley`.
102
+
That's the whole loop, and it is the same for every tool: find, build, load, run. When you are
103
+
ready for more, [**How to use Shelley**](shelley-howto) covers the other use cases that will
0 commit comments