Skip to content

Commit e05d305

Browse files
supernordsupernord
committed
Update tools.md to align with workflows.md v1.3 structure
Other additions - biotools and EDAM - table of contents - formatting changes Thanks also to - @tracychew - @georgiesamaha
1 parent e50c7aa commit e05d305

File tree

6 files changed

+139
-43
lines changed

6 files changed

+139
-43
lines changed

‎LICENSE.md‎

Whitespace-only changes.

‎README.md‎

Lines changed: 9 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,25 @@
11
[tool / workflow name]
22
==============
3-
Australian BioCommons Documentation Guidelines
43

5-
```
6-
###################################################################################
7-
### Delete this section when the first version of the documentation is complete ###
8-
###################################################################################
9-
10-
You can make use of this template repository as a base template for a new GitHub repository.
11-
12-
General information about the guidelines
13-
14-
- This **template** repository contains a set of guidelines for documenting bioinformatics tools and workflows.
15-
- The initial version uploaded to GitHub was informed by current documentation practices and structures used in the GitHub community.
16-
- These guidelines will be further developed as needed to meet the requirements of the Australian BioCommons community.
17-
```
4+
> ## Delete this section when the first version of the documentation is complete
5+
> You can make use of this template repository as a base template for a new GitHub repository.
6+
>
7+
> **General information about the guidelines**
8+
>- This **template** repository contains a set of guidelines for documenting bioinformatics tools and workflows.
9+
>- The initial version uploaded to GitHub was informed by current documentation practices and structures used in the GitHub community.
10+
>- These guidelines will be further developed as needed to meet the requirements of the Australian BioCommons community.
1811
1912
---
2013

2114
# General recommendations for using [tool / workflow name]
2215

23-
```
24-
Recommendations on using the workflow: for example, based on data set size, infrastructure suitability.
25-
```
16+
> Recommendations on using the workflow: for example, based on data set size, infrastructure suitability.
2617
2718
---
2819

2920
# Resources available here
3021

31-
This repository contains structured documentation for [workflow name], including links to existing repositories and community resources, as well as a description of the optimisations achieved on the following compute systems:
22+
This repository contains structured documentation for ```[workflow name]```, including links to existing repositories and community resources, as well as a description of the optimisations achieved on the following compute systems:
3223

3324
- [system name](infrastructure_optimisation.md)
3425
- ...

‎change_log.md‎

Whitespace-only changes.

‎test_data/.keep‎

Whitespace-only changes.

‎tools.md‎

Lines changed: 128 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,158 @@
1-
*Tool name*
1+
[tool name]
22
==========
33

4-
## Description
5-
4+
- [Description](#description)
5+
- [Diagram](#diagram)
6+
- [User guide](#user-guide)
7+
- [Install](#install)
8+
- [Quick start guide](#quick-start-guide)
9+
- [Infrastructure usage and
10+
recommendations](#infrastructure-usage-and-recommendations)
11+
- [Compute resource usage across tested
12+
infrastructures](#compute-resource-usage-across-tested-infrastructures)
13+
- [Benchmarking](#benchmarking)
14+
- [Workflow summaries](#workflow-summaries)
15+
- [Metadata](#metadata)
16+
- [Required (minimum)
17+
inputs/parameters](#required-minimum-inputsparameters)
18+
- [Additional notes](#additional-notes)
19+
- [Help/FAQ/Troubleshooting](#helpfaqtroubleshooting)
20+
- [3rd party Tutorials](#3rd-party-tutorials)
21+
- [License(s)](#licenses)
22+
- [Acknowledgements/citations/credits](#acknowledgementscitationscredits)
23+
24+
---
25+
26+
# Description
27+
28+
```
629
Introduction of tool, including its input(s)/output(s) as well as a list (or link to) of available shell commands (useful when building interfaces/wrappers for containers)
730
31+
Table with embedded registry links, if suitable.
32+
```
33+
834
| Repository / Registry | Available? |
935
|-------------|:--------:|
1036
| GitHub | [●]()|
1137
| bio.tools | [●]()|
1238
| BioContainers | [●]()|
1339
| bioconda | [●]()|
1440

15-
## Required (minimum) inputs / parameters
41+
---
1642

17-
## Key link(s) & additional information (e.g. input(s), parameter(s), output(s))
43+
# Diagram
1844

19-
## Third party tools / dependencies
45+
> Logical visual description of processing steps for tool, e.g. for pipelines shipped as packages (Falcon, Cellranger, ..)
2046
21-
# Diagram
47+
---
48+
49+
# User guide
50+
51+
## Install
52+
53+
> General installation guide.
54+
55+
> If there are different installation requirements based on infrastructures you could indicate these here, or in the individual infrastructure documentation template: https://github.com/AustralianBioCommons/doc_guidelines/blob/master/infrastructure_optimisation.md
56+
57+
---
58+
59+
## Quick start guide
60+
61+
> General guide for deployment across multiple infrastructures (distinct from specific infrastructure quick start guide).
62+
63+
---
64+
65+
## Infrastructure usage and recommendations
66+
67+
> You could include:
68+
> + a link to installation instructions for each computational infrastructure
69+
> + recommendations for use on a specific computational infrastructure
70+
71+
> Documentation for a specific infrastructure should go into a infrastructure documentation template https://github.com/AustralianBioCommons/doc_guidelines/blob/master/infrastructure_optimisation.md
72+
73+
---
74+
75+
## Compute resource usage across tested infrastructures
76+
77+
> Table with high level compute resource usage information for standalone runs or testing of specific versions on specific computational infrastructures.
2278
23-
Logical visual description of processing steps for tool, e.g. for pipelines shipped as packages (Falcon, Cellranger, ..)
79+
| Tool | Version | Sample description | Wall time | Cores | Peak RAM in GB (requested) | Drive (GB) | HPC-HTC | If HPC-HTC is other, specify | Scheduler | Year-Month |
80+
| ----- | ------- | ------------------ | --------- | ----- | -------------------------- | ---------- | ------- | ---------------------------- | --------- | ---------- |
81+
| | | | | | | | | | | |
2482

25-
# Usage
83+
---
2684

27-
## Summary
85+
## Benchmarking
2886

29-
| Version | Infrastructure | Scheduler | Workflow manager | Container | Install method |
30-
|---------------|---------|-----------|------------------|-----------|----------------|
31-
|||||||
87+
> Benchmarking for a specific infrastructure should go here: if this document is complicated it should go into a benchmarking template, or be provided elsewhere (e.g. Zenodo).
3288
33-
## High level resource usage
89+
---
3490

35-
Table with embedded Compute infrastructure name optimisation -> "HPC-HTC" column
91+
# Tool summary
3692

37-
| Version | Group | Sample name (e.g. organism) | Other sample detail (e.g. *Genus species*) | Other sample detail (e.g. genome size (GB)) | Hours required | Cores | Peak RAM in GB (requested) | Drive (GB) | HPC-HTC | Month-Year |
38-
|---------|---------|-------|---------------|---------------|------------------|----------------|-------|----------------------------|---------------|---------|
39-
||||||||||||
93+
## Metadata
4094

41-
## Additional notes
95+
> Example table below - **based on requirements for [bio.tools](https://bio.tools/)**
4296
43-
Any comment on major features being introduced, or default/API changes that might result in unexpected behaviours.
97+
> **To discover appropriate [EDAM](https://github.com/edamontology/edamontology) ontology terms**, you can use [EDAM browser](https://edamontology.github.io/edam-browser/)
4498
45-
# Install
99+
> bio.tools citation: Ison, J. *et al.* (2015). [Tools and data services registry: a community effort to document bioinformatics resources.](http://nar.oxfordjournals.org/content/early/2015/11/03/nar.gkv1116.long) _Nucleic Acids Research_.
100+
doi: [10.1093/nar/gkv1116](http://dx.doi.org/10.1093/nar/gkv1116) PMID: [26538599 ](http://www.ncbi.nlm.nih.gov/pubmed/26538599)
46101

47-
# Tutorials
102+
> EDAM citation: Ison, J., Kalaš, M., Jonassen, I., Bolser, D., Uludag, M., McWilliam, H., Malone, J., Lopez, R., Pettifer, S. and Rice, P. (2013). [EDAM: an ontology of bioinformatics operations, types of data and identifiers, topics and formats](http://bioinformatics.oxfordjournals.org/content/29/10/1325.full). _Bioinformatics_, **29**(10): 1325-1332.
103+
[![10.1093/bioinformatics/btt113](https://zenodo.org/badge/DOI/10.1093/bioinformatics/btt113.svg)](https://doi.org/10.1093/bioinformatics/btt113) PMID: [23479348](http://www.ncbi.nlm.nih.gov/pubmed/23479348) _Open access_
104+
105+
106+
|metadata field | value |
107+
|-------------------|:---------------------------------:|
108+
|Tool name | |
109+
|Description | |
110+
|Homepage URL | |
111+
|Software version(s)| |
112+
|EDAM topic(s) | |
113+
|EDAM operation(s) | |
114+
|Maturity | |
115+
|Creators | |
116+
|License | |
117+
|Container | |
118+
|Install method | |
119+
|GitHub | |
120+
|bio.tools | |
121+
|BioContainers | |
122+
|bioconda | |
123+
124+
---
125+
126+
## Required (minimum) inputs / parameters
127+
128+
> The minimum inputs required for the workflow to run.
129+
130+
---
131+
132+
## Third party tools / dependencies
133+
134+
> Add / list known dependencies, or link to a list of these dependencies.
135+
136+
---
137+
138+
# Additional notes
139+
140+
> Any comment on major features being introduced, or default/API changes that might result in unexpected behaviours.
141+
142+
---
48143

49144
# Help / FAQ / Troubleshooting
50145

51-
# Licence
146+
---
147+
148+
# 3rd party Tutorials
149+
150+
---
151+
152+
# License(s)
153+
154+
---
52155

53156
# Acknowledgements / citations / credits
157+
158+
> Any attribution information that is relevant to the tool being documented.

‎workflows.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,15 +132,15 @@ The minimum inputs required for the workflow to run.
132132

133133
---
134134

135-
# Help/FAQ/Troubleshooting
135+
# Help / FAQ / Troubleshooting
136136

137137
---
138138

139139
# 3rd party Tutorials
140140

141141
---
142142

143-
# Licence(s)
143+
# License(s)
144144

145145
---
146146

0 commit comments

Comments
 (0)