From 45c736a4fcc3bf888270f0f2f373cdfe3ab04d14 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Thu, 17 Jan 2019 09:21:08 -0200 Subject: [PATCH 01/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 54 ++++++++++++++++++++++++++-------- 1 file changed, 41 insertions(+), 13 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index a049852..c20197e 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -1,22 +1,20 @@ # Guidelines to BIII.eu curators -BIII.eu is a web-based database that includes bioimage analysis tools, such as Software, Training material and Datasets. The guidelines here (under construction) presented will help confirmed taggers add and curate _software_ entries into BIII.eu only. The software entry of the webtool include from simple _components_, such as a gaussian filter, to image processing libraries (_collections_ of components) and _workflows_ (e.g. single particle tracking workflows). +BIII.eu is a web-based database that includes bioimage analysis tools, such as Software, Training material and Datasets. The guidelines here presented will help confirmed taggers add and curate _software_ entries into BIII.eu only. The software entry of the webtool include from simple _components_, such as a gaussian filter, to image processing libraries (_collections_ of components) and _workflows_ (e.g. single particle tracking workflows). -The detailed description of the types of tools that can be included in BIII.eu webtool are still under discussion. However, we ask curators and taggers to include only tools that can be used and relate to image analysis problems in biology (a.k.a bioimage analysis). +The detailed description of the types of tools that can be included in BIII.eu webtool are still under discussion. However, we ask curators and taggers to include only tools that can be used (e.g we do not seek a publication without an implementation of the code publicly available. Commercial software can be accepted if specified as so) and relate to image analysis problems in biology (a.k.a bioimage analysis). The tools are described using two ontologies, [**BISE-core-ontology**](https://github.com/NeuBIAS/bise-core-ontology) and [**EDAM-Bioimaging**](https://github.com/edamontology/edam-bioimaging). **BISE-core-ontology** contains the structure of description of entries in BIII.eu, not only software, and includes entry properties such as author, reference publication, curator and so on. **EDAM-Bioimaging** is used as a source of terms to describe the entry with Bioimaging related vocabulary. ->In BISE, a software entry describes a bioimage analysis tool, which can be classified as a _component_, a _collection_ or a _workflow_. A _component_ is an implementation of certain image processing / analysis algorithms. Each component alone does not solve a Bioimage Analysis problem. These problems can be addressed by combining such components into workflows. On the orhter hand, a _workflow_ is a set of components assembled in some specific order to process bioimages and estimate some numerical parameters relevant to the biological system under study. Workflows take image data as input and output either processed images or other type of data (usually numeric values). Workflows can be a combination of components from the same or different software packages. Finally, a _collection_ is a software that encapsulate a set of bioimage components and/or workflows, e.g. libraries such as **imglib2** and **scikit-image** or general purpose software such as **Fiji**, **Icy**. +In BISE, a software entry describes a bioimage analysis tool, which can be classified as a _component_, a _collection_ or a _workflow_. A _component_ is an implementation of certain image processing / analysis algorithms. Each component alone does not solve a Bioimage Analysis problem. These problems can be addressed by combining such components into workflows. On the other hand, a _workflow_ is a set of components assembled in some specific order to process bioimages and estimate some numerical parameters relevant to the biological system under study. Workflows take image data as input and output either processed images or other type of data (usually numeric values). Workflows can be a combination of components from the same or different software packages. Finally, a _collection_ is a software that encapsulate a set of bioimage components and/or workflows, e.g. libraries such as [**imglib2**](http://biii.eu/imglib2) and [**scikit-image**](http://biii.eu/scikit-image) or general purpose software such as [**Fiji**](http://biii.eu/fiji), [**Icy**](http://biii.eu/icy). OBSERVATION: These curation guidelines were inspired by [biotoolsDocs](https://github.com/bio-tools/biotoolsDocs/blob/master/github_projects.rst) documentation. Part of it has been adapted or used as is from the original **biotoolsDocs**. Thanks to Jon Ison for referencing biotools documentation efforts. -If you wish to suggest changes or additions to this documentation, please raise an issue to begin the discussion. +If you wish to suggest changes or additions to this documentation, please raise [an issue](https://github.com/NeuBIAS/bise-documents/issues) to begin a discussion. # How and what to curate? -When you add a new content, you will notice that a similar named tools exist. Please check if it is the same tool(s) you wanted to tag, if not, name it differently (example: Erosion (Icy) vs Erosion (MorpholibJ)). The purpose is to have a unique title for each entry. Whenever possible, try to add both the _collection_ and an entry by _component_(s): e.g. MorpholibJ is an ImageJ plugin, and an entry by function (erosion in MorpholibJ, watershed in MorpholibJ etc... are all components inside MorpholibJ). The purpose is then to help analysts to find the component they need when constructing a bio image analysis workflow. - -Try to fill as many fields as possible. If one field definition is unclear, report in the [BIII.eu forum](http://biii.eu/forum) or raise an issue in github [bise documents repository](https://github.com/NeuBIAS/bise-documents). +Try to fill as many fields as possible. If one field definition is unclear, report in the [BIII.eu forum](http://biii.eu/forum) or raise [an issue](https://github.com/NeuBIAS/bise-documents/issues) in Github [bise documents repository](https://github.com/NeuBIAS/bise-documents). Also mind that there is an [Entry Information Standard documentation](https://github.com/Leandroscholz/bise-documents/blob/master/Entry-information-standard/Entry-info-standard.md) for BISE, where you can check whether your entry will be classified from 'sparse' to 'comprehensive'. >The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt>): @@ -30,25 +28,27 @@ Try to fill as many fields as possible. If one field definition is unclear, repo # General guidelines ## Before you start +When you add a new content, you will notice if a similar named tools exist. Please check if it is the same tool(s) you wanted to tag, if not, name it differently (example: Erosion (Icy) vs Erosion (MorpholibJ)). The purpose is to have a unique title for each entry. Whenever possible, try to add both the _collection_ and an entry by _component_(s): e.g. MorpholibJ is an ImageJ plugin, and an entry by function (erosion in MorpholibJ, watershed in MorpholibJ etc.. are all components inside MorpholibJ). The purpose is then to help analysts to find the component they need when constructing a bioimage analysis workflow. + Consider the following *before* adding a software entry in BIII.eu 1. **Are one or more entries required to describe the software?** - - Software with multiple implementations often require multiple entries. Example: SOAX - has 2 different ways of downloading it: One is the windows standalone executable and the second is the source code, which will require one to compile it in any OS (requiring ITK, VTK and Boost C++ libraries). In that case, the best way is to create two entries: one by location of download since it is actually two different software then, and evrey entry should have only one dowload page (has location). In one entry there is only windows as the supported platform, while in the other, any OS. + - Software with multiple implementations often require multiple entries. Example: SOAX - has 2 different ways of downloading it: One is the windows standalone executable and the second is the source code, which will require one to compile it in any OS (requiring ITK, VTK and Boost C++ libraries). In that case, the best way is to create two entries: one by location of download since it is actually two different software, and each entry should have only one dowload page (has location). In addition one entry would only have Windows as the supported platform, while in the other, any OS. - Collections also often require multiple entries. Example: Simple Neurite Tracer (existing entry) is an ImageJ-Fiji plugin which has three workflow options available: 2 semi-automated and 1 fully automated. In this case, one would create one entry for Simple Neurite Tracer (the plugin) as a _Collection_, then one entry by example workflow, and specify the difference in the title. You will have one plugin, and 3 workflows requiring the plugin Simple Neurite Tracer. - tools with multiple interfaces (not described in bise-core-ontology) **SHOULD** be described by a single entry **unless** these interfaces provide fundamental functional differences. - if in doubt, post in BIII.eu forum or contact confirmed taggers or admin. 2. **What if the software is already registered?** -- if you are the rightful owner of the entry (*i.e.* the tool developer or provider of an online service) and you are a confirmed tagger, change the field _entry curator_ to your username. In case you are not a confirmed tagger, ask for modification in the BIII.eu forum. +- if you are the rightful owner of the entry (*i.e.* the tool developer or provider of an online service) and you are a confirmed tagger, change the field _entry curator_ to your username. In case you are not a confirmed tagger, ask for modification of your user status in the BIII.eu in [this](http://biii.eu/node/1361) page. -- if you are a normal user but wishes to suggest modifications to an existing entry, post in the BIII.eu forum and describe your suggestions. +- if you are a normal user but wishes to suggest modifications to an existing entry, add a comment to the page of that entry and describe your suggestions. 3. **Are there version-specific considerations?** - - as a rule, a software entry in BIII.eu **SHOULD** describe the *latest version* available at the time of registration and **SHOULD** be updated, as required, for subsequent releases. - - if a new version has fundamental functional differences it **MAY** be registered as an entirely new entry. In such cases, follow carefully the guidelines for entry **name** and **version** (under construction). + - as a rule, a software entry in BIII.eu **SHOULD** describe the *latest version* available at the time of registration and **SHOULD** be updated, as required, for subsequent releases. Note that revision of your own entries is always available, so if you update to describe a specific version, please state so in the revision log. + - if a new version has fundamental functional differences it **MAY** be registered as an entirely new entry. In such cases, follow carefully the guidelines for entry **name** and **version** (see Name). 4. **Plan** how to describe the entry functions (under construction). 5. **Read** the general EDAM annotations guidelines (under construction). @@ -144,9 +144,10 @@ There are only 4 discrete values for this attribute: ``Commercial``, ``Free and - ``Free but not open source`` is used when the source code is not available (closed source) but the software is free to be used. - ``I do not know`` is used when the License/Openness is not know. This value **SHOULD** be avoided. -**1.** If an entry has two versions with different License/Openness values (*e.g.* a commercial and a free version with fewer features), it **SHOULD** have both values selected. +**1.** If an entry is a Shareware software with different License/Openness values (*e.g.* a commercial and a free version with fewer features), it **SHOULD** have both values selected. However, we discourage users to add entries of such type. ## Entry curator +The entry curator field links to a BIII.eu user who is either: (1) the user who added the entry, but who is not the rightful owner of the tool, (2) a confirmed tagger, who checked the entry and curated it or (3) the rightful owner of the entry (*i.e* the tool developer or provider of the online service). ## Download page @@ -166,3 +167,30 @@ There are only 4 discrete values for this attribute: ``Commercial``, ``Free and **3.** **SHOULD** preferably resolve to a publication where the tool was first introduced. +## Documentation + +A link to a source of information about the use, installation and applications of the software. Accepts more than one documentation attribute entry. +**1.** MUST resolve to a web page from which a can obtain information about how to use the software. For example, a link to a user’s manual (e.g. Neural Circuit Tracer main page, or the the link to the [User guide](http://www.northeastern.edu/neurogeometry/wp-content/uploads/User-Guide-V-4-0.pdf) itself), a wiki page (e.g. [Anamorf Wiki](https://bitbucket.org/djpbarry/anamorf/wiki/Home), or other link from which similar information can be obtained (example, Using Fiji page or a readme page with detailed information about the software). +**2.** From all the options above, it is RECOMMENDED that, if only one Documentation attribute is given, the URL to the documentation resolves to the most used and comprehensive source of information about the software, no matter its type (wiki, pdf file, webpage linking to other pages, etc..). +**3.** MAY receive more than one Documentation link (use Add another item button). + +## Has usage example +**1.** MAY link to an existing node in BIII.eu database (e.g. a workflow, a training material, a dataset…). +**2.** MAY receive more than one usage example link (use Add another item button). + +## Has comparison +## DOI link ** (DOI of the software) +## Has Training material +## Has function (EDAM-Bioimaging) +## Has Topic (EDAM-Bioimaging) +## Has biological terms +## Additional keywords +## Requires +## Execution platform +## Implementation type +## License + +Has programming language +is compatible with +Supported image dimension +Interaction level From ebd70fac02b5c79087cad7080c8d5bdda0fbe746 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Thu, 17 Jan 2019 10:45:03 -0200 Subject: [PATCH 02/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 45 +++++++++++++++++++++++----------- 1 file changed, 31 insertions(+), 14 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index c20197e..4cb4e6d 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -120,6 +120,7 @@ Textual description of the software, e.g. *"The neuTube is a collection of neuro **6.** **SHOULD NOT** include URLs ## Author +One or more strings that identify the author(s) of the tool. **1.** Each author item **MUST** correspond to a single individual. @@ -129,7 +130,6 @@ Textual description of the software, e.g. *"The neuTube is a collection of neuro **3.** **SHOULD** (if available) include the author's ORCID ID with the following template: ``LastName, FirstName (orcid.org/xxxx-xxxx-xxxx-xxxx)`` so they can be contacted more easily (to get the Orcid , google orcid + author name to get it. orcid.org/xxxx-xxxx-xxxx-xxxx). ## Illustrative image - An illustrative image that represents the main functionality of the software entry. **1.** It **SHOULD** represent the main software functionality or a screenshot of the UI in use. In cases where a single image cannot show the main functionality of the software entry (usually happens for general purpose software and libraries) the illustrative image **SHOULD** be the logo. @@ -137,7 +137,6 @@ An illustrative image that represents the main functionality of the software ent **NOTE:** The software entry will not be promoted on the front page without an illustrative image. ## License/Openness - There are only 4 discrete values for this attribute: ``Commercial``, ``Free and open source``, ``Free but not open source`` and ``I do not know``. - ``Commercial`` is used when the software needs to be purchased in order to be used. - ``Free and open source`` is selected when the source code is available and the software does not need to be purchased in order to be used`` @@ -147,10 +146,9 @@ There are only 4 discrete values for this attribute: ``Commercial``, ``Free and **1.** If an entry is a Shareware software with different License/Openness values (*e.g.* a commercial and a free version with fewer features), it **SHOULD** have both values selected. However, we discourage users to add entries of such type. ## Entry curator -The entry curator field links to a BIII.eu user who is either: (1) the user who added the entry, but who is not the rightful owner of the tool, (2) a confirmed tagger, who checked the entry and curated it or (3) the rightful owner of the entry (*i.e* the tool developer or provider of the online service). +A link to a BIII.eu user who is either: (1) the user who added the entry, but who is not the rightful owner of the tool, (2) a confirmed tagger, who checked the entry and curated it or (3) the rightful owner of the entry (*i.e* the tool developer or provider of the online service). ## Download page - *Homepage of the software, from which is possible to download the software or some URL that best serves this purpose, e.g. "http://icy.bioimageanalysis.org/"* **1.** **MUST** resolve to a web page from the developer / provider that most specifically provides a downloadable version of the software or has a link to its source code. @@ -160,6 +158,7 @@ The entry curator field links to a BIII.eu user who is either: (1) the user who **TIP:** In case a tool lacks its own website, a URL of its code repository is OK. Do not use a general URL such as an institutional homepage, unless nothing better is available. ## Reference publication +An url that links to a reference publication that presents the tool. **1.** **MUST** resolve to a web page of a journal article or web page of a preprint server that most specifically links to a reference publication. @@ -168,18 +167,37 @@ The entry curator field links to a BIII.eu user who is either: (1) the user who **3.** **SHOULD** preferably resolve to a publication where the tool was first introduced. ## Documentation +An URL that links to a source of information about the use, installation and applications of the software. Accepts more than one documentation attribute entry. + +**1.** **MUST** resolve to a web page from which a can obtain information about how to use the software. For example, a link to a user’s manual (e.g. Neural Circuit Tracer main page, or the the link to the [User guide](http://www.northeastern.edu/neurogeometry/wp-content/uploads/User-Guide-V-4-0.pdf) itself), a wiki page (e.g. [Anamorf Wiki](https://bitbucket.org/djpbarry/anamorf/wiki/Home), or other link from which similar information can be obtained (example, Using Fiji page or a readme page with detailed information about the software). + +**2.** From all the options above, it is **RECOMMENDED** that, if only one Documentation attribute is given, the URL to the documentation resolves to the most used and comprehensive source of information about the software, no matter its type (wiki, pdf file, web page linking to other pages, etc..). -A link to a source of information about the use, installation and applications of the software. Accepts more than one documentation attribute entry. -**1.** MUST resolve to a web page from which a can obtain information about how to use the software. For example, a link to a user’s manual (e.g. Neural Circuit Tracer main page, or the the link to the [User guide](http://www.northeastern.edu/neurogeometry/wp-content/uploads/User-Guide-V-4-0.pdf) itself), a wiki page (e.g. [Anamorf Wiki](https://bitbucket.org/djpbarry/anamorf/wiki/Home), or other link from which similar information can be obtained (example, Using Fiji page or a readme page with detailed information about the software). -**2.** From all the options above, it is RECOMMENDED that, if only one Documentation attribute is given, the URL to the documentation resolves to the most used and comprehensive source of information about the software, no matter its type (wiki, pdf file, webpage linking to other pages, etc..). **3.** MAY receive more than one Documentation link (use Add another item button). ## Has usage example -**1.** MAY link to an existing node in BIII.eu database (e.g. a workflow, a training material, a dataset…). -**2.** MAY receive more than one usage example link (use Add another item button). +A url that links to a usage example, sch as a case study document (pdf, web page, video or other types of media), training material (also of any type of media, but preferably existing in BIII.eu), a workflow in which the tool is used (for components). + +**1.** **MAY** link to an existing node in BIII.eu database (e.g. a workflow, a training material, a dataset). + +**2.** **MAY** receive more than one usage example link (use Add another item button). ## Has comparison +An url that links to a document, preferably in written media (pdf, slide deck), showing a comparison of the tool against other similar tools that perform the same job or very similar job. Examples: link to a research paper that benchmarks several tools, link to the web page of a Challenge in which the tool is included, reference to other web pages were the comparison is available. + +**1.** **MUST** resolve to a web page that shows results of a comparison of the tool against other similar tools. + +**2.** It is **RECOMMENDED** that the description (*Link text*) of the url indicates the part of the document (a figure, a page or a reference in that document) where the results of the comparison are. + +**2.** **MAY** link to an existing node in BIII.eu database (e.g. a training material). + +**3.** **MAY** receive more than one comparison link (use Add another item button). + ## DOI link ** (DOI of the software) +A DOI link to the software, related to the correct version of the tool described in the entry. There are many options out there (see [this](https://blog.datacite.org/doi-registrations-software/) blog post from Datacite), but the most commonly used is [Zenodo](https://zenodo.org/). + +**1.** **MUST** be a DOI link in the form ``https://doi.org/``+``DOI`` (*e.g.* ``https://doi.org/10.5281/zenodo.30769``). + ## Has Training material ## Has function (EDAM-Bioimaging) ## Has Topic (EDAM-Bioimaging) @@ -189,8 +207,7 @@ A link to a source of information about the use, installation and applications o ## Execution platform ## Implementation type ## License - -Has programming language -is compatible with -Supported image dimension -Interaction level +## Has programming language +## is compatible with +## Supported image dimension +## Interaction level From 247aae3fd6425983e08a3c5d520bbd37ebaaf484 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Thu, 17 Jan 2019 11:57:34 -0200 Subject: [PATCH 03/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 40 ++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 4cb4e6d..04637f4 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -194,20 +194,56 @@ An url that links to a document, preferably in written media (pdf, slide deck), **3.** **MAY** receive more than one comparison link (use Add another item button). ## DOI link ** (DOI of the software) -A DOI link to the software, related to the correct version of the tool described in the entry. There are many options out there (see [this](https://blog.datacite.org/doi-registrations-software/) blog post from Datacite), but the most commonly used is [Zenodo](https://zenodo.org/). +A single DOI link to the software, related to the correct version of the tool described in the entry. There are many options out there (see [this](https://blog.datacite.org/doi-registrations-software/) blog post from Datacite), but the most commonly used is [Zenodo](https://zenodo.org/). -**1.** **MUST** be a DOI link in the form ``https://doi.org/``+``DOI`` (*e.g.* ``https://doi.org/10.5281/zenodo.30769``). +**1.** **MUST** be a DOI link in the form ``https://doi.org/``+``DOI`` (*e.g.* ``https://doi.org/10.5281/zenodo.30769`` ![](https://zenodo.org/badge/DOI/10.5281/zenodo.30769.svg)). ## Has Training material +A link to an existing training material node in the BIII.eu database. + +**1.** **MUST** link to an existing training material node in BIII.eu database (*e.g* ``http://biii.eu/node/1366``). + +**2.** **MAY** receive more than one training material link (use Add another item button). + +# WARNING: the following entry attributes (Has function, Has Topic, Has biological terms ) may be considered the most important in BIII.eu. It is with them that the database will be able to connect bioimage analysts, developers and biologists. Bare this in mind. + ## Has function (EDAM-Bioimaging) + +**2.** **MAY** receive more than one Function. + ## Has Topic (EDAM-Bioimaging) + +**2.** **MAY** receive more than one Topic. + ## Has biological terms + +**2.** **MAY** receive more than one biological term (use Add another item button). + ## Additional keywords +A string in which the user may add keywords to the entry in case she/he did not find existing keywords in EDAM-Bioimaging functions or topics. This field is important to support further improvements and discussions on new versions of EDAM-Bioimaging. + +**1.** **MUST** be a concise keyword and comprise of the most commonly used keyword that relates to the intended theme/subject (to the best of the user's knowledge, for we do not expect the user to know the best term, which is also not always agreed upon by the scientific community). + +**2.** **MAY** receive more than one keyword (use Add another item button). + ## Requires +A link to an existing software node in BIII.eu to show the dependencies of the tool. + ## Execution platform +A discrete attribue that defines in which main execution platforms the tool can be used. There are only 4 values for this attribute: ``Linux``, ``Mac``, ``Windows``, ``Unsure``. + +**1.** + ## Implementation type +A discrete attribute that defines the type of implementation of the tool. A more detailed description on the discussion of implementation types is in ["Workflows and Components of Bioimage Analysis: The NEUBIAS Concept"](https://www.authorea.com/users/90123/articles/211121-workflows-and-components-of-bioimage-analysis-the-neubias-concept) ![](https://zenodo.org/badge/DOI/10.5281/zenodo.1042570.svg). The 4 values for this attribute are ``Collection``, ``Component``, ``Workflow`` and ``I do not know`` + ## License + ## Has programming language +Comprises both programming (coding) language used for the implementation of the entry and the programming languages supported by the entry. + ## is compatible with ## Supported image dimension +A discrete attribute value that defines with which image dimensions the tool can be used. The four discrete values are ``2D``, ``3D`` (), ``Multi-channel`` and `` time-series``. OBSERVATION: Note that some may understand there is an overlap with these values, for a 2D RGB image would also be a Multi-channel image and a 3D image could be a 2D + time-series image, etc. + ## Interaction level From e22ecefa758b6831ffa49c0fa9d12a99963f3c5c Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Thu, 17 Jan 2019 11:58:07 -0200 Subject: [PATCH 04/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 04637f4..263c4f5 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -244,6 +244,6 @@ Comprises both programming (coding) language used for the implementation of the ## is compatible with ## Supported image dimension -A discrete attribute value that defines with which image dimensions the tool can be used. The four discrete values are ``2D``, ``3D`` (), ``Multi-channel`` and `` time-series``. OBSERVATION: Note that some may understand there is an overlap with these values, for a 2D RGB image would also be a Multi-channel image and a 3D image could be a 2D + time-series image, etc. +A discrete attribute value that defines with which image dimensions the tool can be used. The four discrete values are ``2D``, ``3D``, ``Multi-channel`` and `` time-series``. OBSERVATION: Note that some may understand there is an overlap with these values, for a 2D RGB image would also be a Multi-channel image and a 3D image could be a 2D + time-series image, etc. ## Interaction level From 6915dbe02a72386781c02b7a4ef4e8e87f2e76f1 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Mon, 28 Jan 2019 17:33:41 -0200 Subject: [PATCH 05/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 27 ++++++++++++++------------- 1 file changed, 14 insertions(+), 13 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 263c4f5..b91eee4 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -1,12 +1,12 @@ # Guidelines to BIII.eu curators -BIII.eu is a web-based database that includes bioimage analysis tools, such as Software, Training material and Datasets. The guidelines here presented will help confirmed taggers add and curate _software_ entries into BIII.eu only. The software entry of the webtool include from simple _components_, such as a gaussian filter, to image processing libraries (_collections_ of components) and _workflows_ (e.g. single particle tracking workflows). +BIII.eu is a web-based database that includes bioimage analysis tools, such as Software, Training material and Datasets. The guidelines presented here will help confirmed taggers add and curate _software_ entries into BIII.eu only. The software entry of the webtool include from simple _components_ (e.g. gaussian filter), to image processing libraries, _collections_ of components, and _workflows_ (e.g. single particle tracking). The detailed description of the types of tools that can be included in BIII.eu webtool are still under discussion. However, we ask curators and taggers to include only tools that can be used (e.g we do not seek a publication without an implementation of the code publicly available. Commercial software can be accepted if specified as so) and relate to image analysis problems in biology (a.k.a bioimage analysis). The tools are described using two ontologies, [**BISE-core-ontology**](https://github.com/NeuBIAS/bise-core-ontology) and [**EDAM-Bioimaging**](https://github.com/edamontology/edam-bioimaging). **BISE-core-ontology** contains the structure of description of entries in BIII.eu, not only software, and includes entry properties such as author, reference publication, curator and so on. **EDAM-Bioimaging** is used as a source of terms to describe the entry with Bioimaging related vocabulary. -In BISE, a software entry describes a bioimage analysis tool, which can be classified as a _component_, a _collection_ or a _workflow_. A _component_ is an implementation of certain image processing / analysis algorithms. Each component alone does not solve a Bioimage Analysis problem. These problems can be addressed by combining such components into workflows. On the other hand, a _workflow_ is a set of components assembled in some specific order to process bioimages and estimate some numerical parameters relevant to the biological system under study. Workflows take image data as input and output either processed images or other type of data (usually numeric values). Workflows can be a combination of components from the same or different software packages. Finally, a _collection_ is a software that encapsulate a set of bioimage components and/or workflows, e.g. libraries such as [**imglib2**](http://biii.eu/imglib2) and [**scikit-image**](http://biii.eu/scikit-image) or general purpose software such as [**Fiji**](http://biii.eu/fiji), [**Icy**](http://biii.eu/icy). +In BISE, a software entry describes a bioimage analysis tool, which can be classified as a _component_, a _collection_ or a _workflow_. A _component_ is an implementation of certain image processing / analysis algorithms. Each component alone does not solve a Bioimage Analysis problem. These problems can be addressed by combining such components into workflows. On the other hand, a _workflow_ is a set of components assembled in some specific order to process bioimages and estimate some numerical parameters relevant to the biological system under study. Workflows take image data as input and output either processed images or other type of data (usually numeric values). Workflows can be a combination of components from the same or different software packages. Finally, a _collection_ is a software that encapsulates a set of bioimage components and/or workflows, e.g. libraries such as [**imglib2**](http://biii.eu/imglib2) and [**scikit-image**](http://biii.eu/scikit-image) or general purpose software such as [**Fiji**](http://biii.eu/fiji), [**Icy**](http://biii.eu/icy). OBSERVATION: These curation guidelines were inspired by [biotoolsDocs](https://github.com/bio-tools/biotoolsDocs/blob/master/github_projects.rst) documentation. Part of it has been adapted or used as is from the original **biotoolsDocs**. Thanks to Jon Ison for referencing biotools documentation efforts. @@ -34,7 +34,7 @@ Consider the following *before* adding a software entry in BIII.eu 1. **Are one or more entries required to describe the software?** - - Software with multiple implementations often require multiple entries. Example: SOAX - has 2 different ways of downloading it: One is the windows standalone executable and the second is the source code, which will require one to compile it in any OS (requiring ITK, VTK and Boost C++ libraries). In that case, the best way is to create two entries: one by location of download since it is actually two different software, and each entry should have only one dowload page (has location). In addition one entry would only have Windows as the supported platform, while in the other, any OS. + - Software with multiple implementations often require multiple entries. Example: SOAX - has 2 different ways of downloading it: One is the windows standalone executable and the second is the source code, which will require one to compile it in any OS. In that case, the best way is to create two entries: one by location of download since it is actually two different software, and each entry should have only one dowload page (has location). In addition one entry would only have Windows as the supported platform, while in the other, any OS. - Collections also often require multiple entries. Example: Simple Neurite Tracer (existing entry) is an ImageJ-Fiji plugin which has three workflow options available: 2 semi-automated and 1 fully automated. In this case, one would create one entry for Simple Neurite Tracer (the plugin) as a _Collection_, then one entry by example workflow, and specify the difference in the title. You will have one plugin, and 3 workflows requiring the plugin Simple Neurite Tracer. - tools with multiple interfaces (not described in bise-core-ontology) **SHOULD** be described by a single entry **unless** these interfaces provide fundamental functional differences. - if in doubt, post in BIII.eu forum or contact confirmed taggers or admin. @@ -102,7 +102,7 @@ Canonical software name assigned by the tagger, preferably the software develope >> - be wary of names that are very long (>25 characters). If shortening the name is necessary, don't truncate it in a way (*e.g.* within the middle of a word) that would render it meaningless or unintuitive ## Description -Textual description of the software, e.g. *"The neuTube is a collection of neuron reconstruction tools from fluorescence microscope images. It has an interactive system with a 3D viewer, which can be clicked in 3D and perform neuron tracing automatically and semi-automatically. It can automatically recognize branching points as junctions. Traced neurons can be exported to swc format, which could be imported by various software packages. neuTube has Win and Mac OS standalone executable builds and may also be installed by manual compilation. In addition, neuTube can be used as a plugin in Vaa3D."* +Textual description of the software, e.g. *"The neuTube is a collection of neuron reconstruction tools from fluorescence microscope images. It has an interactive system with a 3D viewer, which can be clicked in 3D and perform neuron tracing automatically and semi-automatically. It can automatically recognize branching points as junctions. Traced neurons can be exported to swc format, which could be imported by various software packages. neuTube has Win and Mac OS standalone executable builds and may also be installed by manual compilation."* *example 2: "All-path-pruning 2.0 (APP2) is neuron tracing (fully automated) component of Vaa3D. APP2 prunes an initial reconstruction tree of a neuron’s morphology using a long-segment-first hierarchical procedure instead of the original termini-first-search process in APP. APP2 computes the distance transform of all image voxels directly for a gray-scale image, without the need to binarize the image before invoking the conventional distance transform. APP2 uses a fast-marching algorithm to compute the initial reconstruction trees without pre-computing a large graph. This method allows to trace large images. This method can be used with default parameters or user-defined parameters."* @@ -112,7 +112,6 @@ Textual description of the software, e.g. *"The neuTube is a collection of neuro **4.** **SHOULD NOT** include any of the following, *unless* essential to distinguish the tool from other entries: -> - general or technical terms ("software", "application", "plugin" *etc.*) > - provenance information *e.g.* software provider, institute or person name **5.** **SHOULD NOT** describe how good the software is (mentions of applicability are OK) @@ -132,9 +131,7 @@ One or more strings that identify the author(s) of the tool. ## Illustrative image An illustrative image that represents the main functionality of the software entry. -**1.** It **SHOULD** represent the main software functionality or a screenshot of the UI in use. In cases where a single image cannot show the main functionality of the software entry (usually happens for general purpose software and libraries) the illustrative image **SHOULD** be the logo. - -**NOTE:** The software entry will not be promoted on the front page without an illustrative image. +**1.** It **SHOULD** represent the main software functionality or a screenshot of the UI in use. In cases where a single image cannot show the main functionality of the software entry (usually happens for general purpose software and libraries) the illustrative image **SHOULD** be the logo. The software entry will not be promoted on the front page without an illustrative image. ## License/Openness There are only 4 discrete values for this attribute: ``Commercial``, ``Free and open source``, ``Free but not open source`` and ``I do not know``. @@ -146,7 +143,7 @@ There are only 4 discrete values for this attribute: ``Commercial``, ``Free and **1.** If an entry is a Shareware software with different License/Openness values (*e.g.* a commercial and a free version with fewer features), it **SHOULD** have both values selected. However, we discourage users to add entries of such type. ## Entry curator -A link to a BIII.eu user who is either: (1) the user who added the entry, but who is not the rightful owner of the tool, (2) a confirmed tagger, who checked the entry and curated it or (3) the rightful owner of the entry (*i.e* the tool developer or provider of the online service). +A link to a BIII.eu user who is either: (1) the user who added the entry, but who is not the rightful owner of the tool (When the tool is first added), (2) a confirmed tagger, who checked the entry and curated it or (3) the rightful owner of the entry (*i.e* the tool developer or provider of the online service). When the tool added in BIII.eu, the value of Entry curator will change upon curation (either to the confirmed tagger who curated the tool or the rightful owner of the tool) ## Download page *Homepage of the software, from which is possible to download the software or some URL that best serves this purpose, e.g. "http://icy.bioimageanalysis.org/"* @@ -155,7 +152,7 @@ A link to a BIII.eu user who is either: (1) the user who added the entry, but wh **2.** **MUST** be restricted to ``http(s?)://[^\s/$.?#].[^\s]*`` -**TIP:** In case a tool lacks its own website, a URL of its code repository is OK. Do not use a general URL such as an institutional homepage, unless nothing better is available. +**TIP:** In case a tool lacks its own website, a URL of its code repository is OK. Do not use a general URL such as an institutional homepage. ## Reference publication An url that links to a reference publication that presents the tool. @@ -166,14 +163,18 @@ An url that links to a reference publication that presents the tool. **3.** **SHOULD** preferably resolve to a publication where the tool was first introduced. +**4.** **MAY** receive more than one Reference Publication (use Add another item button). + +**5.** The link to the reference publication **SHOULD** be remove old URL that does not work anymore, + ## Documentation An URL that links to a source of information about the use, installation and applications of the software. Accepts more than one documentation attribute entry. -**1.** **MUST** resolve to a web page from which a can obtain information about how to use the software. For example, a link to a user’s manual (e.g. Neural Circuit Tracer main page, or the the link to the [User guide](http://www.northeastern.edu/neurogeometry/wp-content/uploads/User-Guide-V-4-0.pdf) itself), a wiki page (e.g. [Anamorf Wiki](https://bitbucket.org/djpbarry/anamorf/wiki/Home), or other link from which similar information can be obtained (example, Using Fiji page or a readme page with detailed information about the software). +**1.** **MUST** resolve to a web page from which one can obtain information about how to use the software. For example, a link to a user’s manual (e.g. Neural Circuit Tracer main page, or the the link to the [User guide](http://www.northeastern.edu/neurogeometry/wp-content/uploads/User-Guide-V-4-0.pdf) itself), a wiki page (e.g. [Anamorf Wiki](https://bitbucket.org/djpbarry/anamorf/wiki/Home), or other link from which similar information can be obtained (example, Using Fiji page or a readme page with detailed information about the software). **2.** From all the options above, it is **RECOMMENDED** that, if only one Documentation attribute is given, the URL to the documentation resolves to the most used and comprehensive source of information about the software, no matter its type (wiki, pdf file, web page linking to other pages, etc..). -**3.** MAY receive more than one Documentation link (use Add another item button). +**3.** **MAY** receive more than one Documentation link (use Add another item button). ## Has usage example A url that links to a usage example, sch as a case study document (pdf, web page, video or other types of media), training material (also of any type of media, but preferably existing in BIII.eu), a workflow in which the tool is used (for components). @@ -205,7 +206,7 @@ A link to an existing training material node in the BIII.eu database. **2.** **MAY** receive more than one training material link (use Add another item button). -# WARNING: the following entry attributes (Has function, Has Topic, Has biological terms ) may be considered the most important in BIII.eu. It is with them that the database will be able to connect bioimage analysts, developers and biologists. Bare this in mind. +## WARNING: the following entry attributes (Has function, Has Topic, Has biological terms ) may be considered the most important in BIII.eu. It is with them that the database will be able to connect the tools and make them searchable by bioimage analysts, developers and biologists. ## Has function (EDAM-Bioimaging) From c2567c4afc5ba7b4ab57d6cd4b7ebbfa31872b78 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Mon, 28 Jan 2019 18:03:55 -0200 Subject: [PATCH 06/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index b91eee4..01fc2ca 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -151,6 +151,8 @@ A link to a BIII.eu user who is either: (1) the user who added the entry, but wh **1.** **MUST** resolve to a web page from the developer / provider that most specifically provides a downloadable version of the software or has a link to its source code. **2.** **MUST** be restricted to ``http(s?)://[^\s/$.?#].[^\s]*`` + +**3.** The link to a Download page that does not work anymore **SHOULD** be removed and replaced by a new, working link. **TIP:** In case a tool lacks its own website, a URL of its code repository is OK. Do not use a general URL such as an institutional homepage. @@ -165,7 +167,7 @@ An url that links to a reference publication that presents the tool. **4.** **MAY** receive more than one Reference Publication (use Add another item button). -**5.** The link to the reference publication **SHOULD** be remove old URL that does not work anymore, +**5.** The link to the reference publication that does not work anymore **SHOULD** be removed and replaced by a new, working link. ## Documentation An URL that links to a source of information about the use, installation and applications of the software. Accepts more than one documentation attribute entry. @@ -176,23 +178,29 @@ An URL that links to a source of information about the use, installation and app **3.** **MAY** receive more than one Documentation link (use Add another item button). +**4.** The link to a documentation page that does not work anymore **SHOULD** be removed and replaced by a new, working link. + ## Has usage example -A url that links to a usage example, sch as a case study document (pdf, web page, video or other types of media), training material (also of any type of media, but preferably existing in BIII.eu), a workflow in which the tool is used (for components). +An URL that links to a usage example, sch as a case study document (pdf, web page, video or other types of media), training material (also of any type of media, but preferably existing in BIII.eu), a workflow in which the tool is used (for components). **1.** **MAY** link to an existing node in BIII.eu database (e.g. a workflow, a training material, a dataset). **2.** **MAY** receive more than one usage example link (use Add another item button). +**3.** The link to a usage example that does not work anymore **SHOULD** be removed and replaced by a new, working link. + ## Has comparison -An url that links to a document, preferably in written media (pdf, slide deck), showing a comparison of the tool against other similar tools that perform the same job or very similar job. Examples: link to a research paper that benchmarks several tools, link to the web page of a Challenge in which the tool is included, reference to other web pages were the comparison is available. +An URL that links to a document, preferably in written media (pdf, slide deck), showing a comparison of the tool against other similar tools that perform the same job or very similar job. Examples: link to a research paper that benchmarks several tools, link to the web page of a Challenge in which the tool is included, reference to other web pages were the comparison is available. BIAFLOWS, the benchmarking webtool from Neubias WG5 could be a source of such attribute. However, we are still discussing how to interact with it. **1.** **MUST** resolve to a web page that shows results of a comparison of the tool against other similar tools. -**2.** It is **RECOMMENDED** that the description (*Link text*) of the url indicates the part of the document (a figure, a page or a reference in that document) where the results of the comparison are. +**2.** It is **RECOMMENDED** that the description (*Link text*) of the URL indicates the part of the document (a figure, a page or a reference in that document) where the results of the comparison are. -**2.** **MAY** link to an existing node in BIII.eu database (e.g. a training material). +**3.** **MAY** link to an existing node in BIII.eu database (e.g. a training material). -**3.** **MAY** receive more than one comparison link (use Add another item button). +**4.** **MAY** receive more than one comparison link (use Add another item button). + +**5.** The link to a comparison that does not work anymore **SHOULD** be removed and replaced by a new, working link. ## DOI link ** (DOI of the software) A single DOI link to the software, related to the correct version of the tool described in the entry. There are many options out there (see [this](https://blog.datacite.org/doi-registrations-software/) blog post from Datacite), but the most commonly used is [Zenodo](https://zenodo.org/). @@ -228,13 +236,11 @@ A string in which the user may add keywords to the entry in case she/he did not **2.** **MAY** receive more than one keyword (use Add another item button). ## Requires -A link to an existing software node in BIII.eu to show the dependencies of the tool. +A link to an existing software node in BIII.eu to show the dependencies of the tool. For example tool ``3D intensity profile`` requires ``ImageJ`` to be ran. ## Execution platform A discrete attribue that defines in which main execution platforms the tool can be used. There are only 4 values for this attribute: ``Linux``, ``Mac``, ``Windows``, ``Unsure``. -**1.** - ## Implementation type A discrete attribute that defines the type of implementation of the tool. A more detailed description on the discussion of implementation types is in ["Workflows and Components of Bioimage Analysis: The NEUBIAS Concept"](https://www.authorea.com/users/90123/articles/211121-workflows-and-components-of-bioimage-analysis-the-neubias-concept) ![](https://zenodo.org/badge/DOI/10.5281/zenodo.1042570.svg). The 4 values for this attribute are ``Collection``, ``Component``, ``Workflow`` and ``I do not know`` From 154e42582d45acc6c40c80e6b885e9c754ac424b Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Mon, 28 Jan 2019 18:33:32 -0200 Subject: [PATCH 07/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 01fc2ca..50a1d9e 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -217,12 +217,19 @@ A link to an existing training material node in the BIII.eu database. ## WARNING: the following entry attributes (Has function, Has Topic, Has biological terms ) may be considered the most important in BIII.eu. It is with them that the database will be able to connect the tools and make them searchable by bioimage analysts, developers and biologists. ## Has function (EDAM-Bioimaging) - -**2.** **MAY** receive more than one Function. +Details of a function the tool provides, expressed in concepts from the EDAM-Bioimaging _Operation_ ontology, e.g. _image classification_ and _model-based segmentation_. +**1.** **MUST** correctly specify operations performed by the tool, or (if version indicated), those specific version(s) of the tool. +**2.** **MAY** receive more than one Function, especially when the tool has multiple modes of operation. +**3.** **SHOULD** describe all the primary operation and **SHOULD NOT** describe secondary or minor operations. In case there are any questions, start discussion in BIII.eu forum. ## Has Topic (EDAM-Bioimaging) +General scientific domain the tool serves or other general category (EDAM Bioimaging Topic), e.g. _Tissue image analysis, Microscopy, Machine Learning_. + +**1.** **MUST** correctly specify Topics the tool relates to, or (if version indicated), those specific version(s) of the tool. -**2.** **MAY** receive more than one Topic. +**2.** **MAY** receive more than one Topic. We **RECOMMEND** to at least refer to the single most important scientific topic. + +**3.** **SHOULD NOT** exhaustively specify all the topics of secondary relevance. ## Has biological terms @@ -245,6 +252,22 @@ A discrete attribue that defines in which main execution platforms the tool can A discrete attribute that defines the type of implementation of the tool. A more detailed description on the discussion of implementation types is in ["Workflows and Components of Bioimage Analysis: The NEUBIAS Concept"](https://www.authorea.com/users/90123/articles/211121-workflows-and-components-of-bioimage-analysis-the-neubias-concept) ![](https://zenodo.org/badge/DOI/10.5281/zenodo.1042570.svg). The 4 values for this attribute are ``Collection``, ``Component``, ``Workflow`` and ``I do not know`` ## License +Software or data usage license, e.g. "GPL-3.0" + +**1. MUST** acurately describe the license used. +**2. SHOULD** use "Proprietary" in cases where the software is under license whereby it can be obtained from the provider (e.g. for money), and then owned, i.e. definitely not an open-source or free software license. +**3. SHOULD** use "Unlicensed" for software which is not licensed and is not "Proprietary". +**4. SHOULD** use "Other" if the software is available under an uncommon license not listed below and which is not "Proprietary". + a controlled vocabulary of valid terms is defined in biotoolsSchema. + see the syntax guidelines. +> **Licenses: +> Apache License 2.0 +> BSD 3-Clause "New" or "Revised" license +> BSD 2-Clause "Simplified" or "FreeBSD" license +> GNU General Public License (GPL) +> GNU Library or "Lesser" General Public License (LGPL) +> MIT license + ## Has programming language Comprises both programming (coding) language used for the implementation of the entry and the programming languages supported by the entry. From 57c1a3df092ef77cb39f7c86d6d9d3ac6806d7ea Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Wed, 30 Jan 2019 08:31:14 -0200 Subject: [PATCH 08/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 29 ++++++++++++++++++++++------- 1 file changed, 22 insertions(+), 7 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 50a1d9e..4eac412 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -106,7 +106,7 @@ Textual description of the software, e.g. *"The neuTube is a collection of neuro *example 2: "All-path-pruning 2.0 (APP2) is neuron tracing (fully automated) component of Vaa3D. APP2 prunes an initial reconstruction tree of a neuron’s morphology using a long-segment-first hierarchical procedure instead of the original termini-first-search process in APP. APP2 computes the distance transform of all image voxels directly for a gray-scale image, without the need to binarize the image before invoking the conventional distance transform. APP2 uses a fast-marching algorithm to compute the initial reconstruction trees without pre-computing a large graph. This method allows to trace large images. This method can be used with default parameters or user-defined parameters."* -**1.** **MUST** provide a concise summary of purpose / function of the tool +**1.** **MUST** provide a concise summary of purpose / function of the tool. we **RECOMMEND** the description bo te of 1-2 short paragraphs. **2.** **MUST** begin with a capital letter and end with a period ('.') @@ -218,32 +218,37 @@ A link to an existing training material node in the BIII.eu database. ## Has function (EDAM-Bioimaging) Details of a function the tool provides, expressed in concepts from the EDAM-Bioimaging _Operation_ ontology, e.g. _image classification_ and _model-based segmentation_. + **1.** **MUST** correctly specify operations performed by the tool, or (if version indicated), those specific version(s) of the tool. + **2.** **MAY** receive more than one Function, especially when the tool has multiple modes of operation. + **3.** **SHOULD** describe all the primary operation and **SHOULD NOT** describe secondary or minor operations. In case there are any questions, start discussion in BIII.eu forum. ## Has Topic (EDAM-Bioimaging) General scientific domain the tool serves or other general category (EDAM Bioimaging Topic), e.g. _Tissue image analysis, Microscopy, Machine Learning_. -**1.** **MUST** correctly specify Topics the tool relates to, or (if version indicated), those specific version(s) of the tool. +**1.** **MUST** specifiy the most important and relevant scientific topics, although we **RECOMMEND** to refer at least to the single most important scientific topic. + +**2.** **MUST** correctly specify Topics the tool relates to, or (if version indicated), those specific version(s) of the tool. -**2.** **MAY** receive more than one Topic. We **RECOMMEND** to at least refer to the single most important scientific topic. +**3.** **MAY** receive more than one Topic. -**3.** **SHOULD NOT** exhaustively specify all the topics of secondary relevance. +**4.** **SHOULD NOT** exhaustively specify all the topics of secondary relevance. ## Has biological terms **2.** **MAY** receive more than one biological term (use Add another item button). ## Additional keywords -A string in which the user may add keywords to the entry in case she/he did not find existing keywords in EDAM-Bioimaging functions or topics. This field is important to support further improvements and discussions on new versions of EDAM-Bioimaging. +A string in which the user may add keywords to the entry in case she/he did not find existing keywords in EDAM-Bioimaging functions or topics. This field is important to support further improvements and discussions on new versions of EDAM-Bioimaging or modifications in BIII.eu. **1.** **MUST** be a concise keyword and comprise of the most commonly used keyword that relates to the intended theme/subject (to the best of the user's knowledge, for we do not expect the user to know the best term, which is also not always agreed upon by the scientific community). **2.** **MAY** receive more than one keyword (use Add another item button). ## Requires -A link to an existing software node in BIII.eu to show the dependencies of the tool. For example tool ``3D intensity profile`` requires ``ImageJ`` to be ran. +A link to an existing software node in BIII.eu to show either in which platform it can be run or the dependencies of the tool. For example tool ``3D intensity profile`` requires ``ImageJ`` to be run. ## Execution platform A discrete attribue that defines in which main execution platforms the tool can be used. There are only 4 values for this attribute: ``Linux``, ``Mac``, ``Windows``, ``Unsure``. @@ -255,17 +260,27 @@ A discrete attribute that defines the type of implementation of the tool. A more Software or data usage license, e.g. "GPL-3.0" **1. MUST** acurately describe the license used. + **2. SHOULD** use "Proprietary" in cases where the software is under license whereby it can be obtained from the provider (e.g. for money), and then owned, i.e. definitely not an open-source or free software license. + **3. SHOULD** use "Unlicensed" for software which is not licensed and is not "Proprietary". + **4. SHOULD** use "Other" if the software is available under an uncommon license not listed below and which is not "Proprietary". a controlled vocabulary of valid terms is defined in biotoolsSchema. see the syntax guidelines. -> **Licenses: + +> **Licenses:** + > Apache License 2.0 + > BSD 3-Clause "New" or "Revised" license + > BSD 2-Clause "Simplified" or "FreeBSD" license + > GNU General Public License (GPL) + > GNU Library or "Lesser" General Public License (LGPL) + > MIT license From cd972867c5238786ad60abe7faad678b57cf8a88 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Wed, 30 Jan 2019 10:13:07 -0200 Subject: [PATCH 09/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 35 +++++++++++++++++++++------------- 1 file changed, 22 insertions(+), 13 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 4eac412..3cbb846 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -223,22 +223,23 @@ Details of a function the tool provides, expressed in concepts from the EDAM-Bio **2.** **MAY** receive more than one Function, especially when the tool has multiple modes of operation. -**3.** **SHOULD** describe all the primary operation and **SHOULD NOT** describe secondary or minor operations. In case there are any questions, start discussion in BIII.eu forum. +**3.** **SHOULD** describe all the primary operations and **SHOULD NOT** describe secondary or minor operations. In case there are any questions, start discussion in BIII.eu forum. ## Has Topic (EDAM-Bioimaging) General scientific domain the tool serves or other general category (EDAM Bioimaging Topic), e.g. _Tissue image analysis, Microscopy, Machine Learning_. -**1.** **MUST** specifiy the most important and relevant scientific topics, although we **RECOMMEND** to refer at least to the single most important scientific topic. +**1.** **MUST** specifiy the **MOST IMPORTANT** and relevant scientific topics, although we **RECOMMEND** to refer at least to the single most important scientific topic. **2.** **MUST** correctly specify Topics the tool relates to, or (if version indicated), those specific version(s) of the tool. -**3.** **MAY** receive more than one Topic. +**3.** **MAY** receive more than one Topic. (use _Add another item_ button) -**4.** **SHOULD NOT** exhaustively specify all the topics of secondary relevance. +**4.** **SHOULD NOT** exhaustively specify all the topics of **secondary relevance**. Include Topic(s) that include the tool into the pool related tools (with the same Topic). And, if applicable, include one or more Topics that distinguish the tool from the others in the pool. (see discussion in [EDAM-Bioimaging](https://github.com/edamontology/edam-bioimaging/issues/12). ## Has biological terms +**1.** **MUST** specify the most important and relevant biological terms. -**2.** **MAY** receive more than one biological term (use Add another item button). +**2.** **MAY** receive more than one biological term (use _Add another item_ button). ## Additional keywords A string in which the user may add keywords to the entry in case she/he did not find existing keywords in EDAM-Bioimaging functions or topics. This field is important to support further improvements and discussions on new versions of EDAM-Bioimaging or modifications in BIII.eu. @@ -248,7 +249,7 @@ A string in which the user may add keywords to the entry in case she/he did not **2.** **MAY** receive more than one keyword (use Add another item button). ## Requires -A link to an existing software node in BIII.eu to show either in which platform it can be run or the dependencies of the tool. For example tool ``3D intensity profile`` requires ``ImageJ`` to be run. +A link to an existing software node in BIII.eu to show either in which platform it can be run or the dependencies of the tool. For example tool ``3D intensity profile`` requires ``ImageJ`` to be run, whereas ## Execution platform A discrete attribue that defines in which main execution platforms the tool can be used. There are only 4 values for this attribute: ``Linux``, ``Mac``, ``Windows``, ``Unsure``. @@ -265,11 +266,9 @@ Software or data usage license, e.g. "GPL-3.0" **3. SHOULD** use "Unlicensed" for software which is not licensed and is not "Proprietary". -**4. SHOULD** use "Other" if the software is available under an uncommon license not listed below and which is not "Proprietary". - a controlled vocabulary of valid terms is defined in biotoolsSchema. - see the syntax guidelines. +**4. SHOULD** either use "Other" or the License name (if known) if the software is available under an uncommon license not listed below and which is not "Proprietary". -> **Licenses:** +> **Most Common Licenses (if you know of an important one to add feel free to suggest):** > Apache License 2.0 @@ -283,12 +282,22 @@ Software or data usage license, e.g. "GPL-3.0" > MIT license - ## Has programming language -Comprises both programming (coding) language used for the implementation of the entry and the programming languages supported by the entry. +Comprises both programming (coding) language used for the implementation of the entry and the programming languages supported by the entry. We still do not have a controlled vocabulary, so if you type a new language, which wasn't previously in BIII.eu, it will create a new node with that name. ## is compatible with +A link to an existing software node in BIII.eu for which the tool was not originally developed, but that can be called from. + ## Supported image dimension -A discrete attribute value that defines with which image dimensions the tool can be used. The four discrete values are ``2D``, ``3D``, ``Multi-channel`` and `` time-series``. OBSERVATION: Note that some may understand there is an overlap with these values, for a 2D RGB image would also be a Multi-channel image and a 3D image could be a 2D + time-series image, etc. +A discrete attribute value that defines with which image dimensions the tool can be used. The four discrete values are ``2D``, ``3D``, ``Multi-channel`` and `` time-series``. OBSERVATION: Some may understand there is an overlap with these values, for a 2D RGB image would also be a Multi-channel image and a 3D image could be a 2D + time-series image, etc. ## Interaction level +A discrete attribute value that defines the interaction level between user and the tool. There are four discrete values, which are: + +``Automated`` a tool that returns the output with a single command call (selection in a GUI) that may oy mayu not accept definition of parameters. + +``Manual`` + +``Semi-automated``a tool that requires multiple calls or user interactions in order to deliver the output. For example, tracing filaments individually until all filaments of an image are traced or identifying central points of cells in order to segment them. The interaction may occur prior to the execution of the tool or several times while the tool is being used (e.g. [Simple Neurite Tracer](http://biii.eu/simple-neurite-tracer)) + +``I do not know`` From a5b366080546de183346789927aaae3a86806c2b Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Wed, 30 Jan 2019 10:15:18 -0200 Subject: [PATCH 10/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 3cbb846..914c785 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -17,13 +17,17 @@ If you wish to suggest changes or additions to this documentation, please raise Try to fill as many fields as possible. If one field definition is unclear, report in the [BIII.eu forum](http://biii.eu/forum) or raise [an issue](https://github.com/NeuBIAS/bise-documents/issues) in Github [bise documents repository](https://github.com/NeuBIAS/bise-documents). Also mind that there is an [Entry Information Standard documentation](https://github.com/Leandroscholz/bise-documents/blob/master/Entry-information-standard/Entry-info-standard.md) for BISE, where you can check whether your entry will be classified from 'sparse' to 'comprehensive'. ->The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt>): +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt>): ->- **"MUST"**, **"REQUIRED"** or **"SHALL"** mean that the guideline is an absolute requirement of the specification. ->- **"MUST NOT"** or **"SHALL NOT"** mean that the guideline is an absolute prohibition of the specification. ->- **"SHOULD"** or **"RECOMMENDED"** mean that there may exist valid reasons in particular circumstances to ignore a particular guideline, but the full implications must be understood and carefully weighed before doing so. ->- **"SHOULD NOT"** or the phrase **"NOT RECOMMENDED"** mean that there may exist valid reasons in particular circumstances when acting contrary to the geuideline is acceptable or even useful, but the full implications should be understood and the case carefully weighed before doing so. ->- **"MAY** or **"OPTIONAL"** mean that the guideline is truly optional; you can choose to follow it or not. +* **"MUST"**, **"REQUIRED"** or **"SHALL"** mean that the guideline is an absolute requirement of the specification. + +* **"MUST NOT"** or **"SHALL NOT"** mean that the guideline is an absolute prohibition of the specification. + +* **"SHOULD"** or **"RECOMMENDED"** mean that there may exist valid reasons in particular circumstances to ignore a particular guideline, but the full implications must be understood and carefully weighed before doing so. + +* **"SHOULD NOT"** or the phrase **"NOT RECOMMENDED"** mean that there may exist valid reasons in particular circumstances when acting contrary to the geuideline is acceptable or even useful, but the full implications should be understood and the case carefully weighed before doing so. + +* **"MAY** or **"OPTIONAL"** mean that the guideline is truly optional; you can choose to follow it or not. # General guidelines ## Before you start @@ -268,19 +272,19 @@ Software or data usage license, e.g. "GPL-3.0" **4. SHOULD** either use "Other" or the License name (if known) if the software is available under an uncommon license not listed below and which is not "Proprietary". -> **Most Common Licenses (if you know of an important one to add feel free to suggest):** +**Most Common Licenses (if you know of an important one to add feel free to suggest):** -> Apache License 2.0 +* Apache License 2.0 -> BSD 3-Clause "New" or "Revised" license +* BSD 3-Clause "New" or "Revised" license -> BSD 2-Clause "Simplified" or "FreeBSD" license +* BSD 2-Clause "Simplified" or "FreeBSD" license -> GNU General Public License (GPL) +* GNU General Public License (GPL) -> GNU Library or "Lesser" General Public License (LGPL) +* GNU Library or "Lesser" General Public License (LGPL) -> MIT license +* MIT license ## Has programming language Comprises both programming (coding) language used for the implementation of the entry and the programming languages supported by the entry. We still do not have a controlled vocabulary, so if you type a new language, which wasn't previously in BIII.eu, it will create a new node with that name. From 511d3a1d4938949d684a5cd37914118a912fd916 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Wed, 30 Jan 2019 13:10:00 -0200 Subject: [PATCH 11/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index 914c785..a474491 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -1,3 +1,11 @@ +# Roles + +**Newbie tagger** When you create an account, you become a _newbie tagger_. _Newbie taggers_ can create new content, and only edit their own content. If _newbie taggers_ wish to edit an existing entry, not created by themselves, they can ask to become a confirmed tagger. + +**Confirmed tagger** can revert revisions, delete content, edit any content, and publish comments submitted to publication. To parse submitted comments and publish it for confirmed taggers, go to shortcut, validate/edit comments. + +**ALL:** Please use the forum to give us feedback on additional features, report problems in user experience, suggest use cases... + # Guidelines to BIII.eu curators BIII.eu is a web-based database that includes bioimage analysis tools, such as Software, Training material and Datasets. The guidelines presented here will help confirmed taggers add and curate _software_ entries into BIII.eu only. The software entry of the webtool include from simple _components_ (e.g. gaussian filter), to image processing libraries, _collections_ of components, and _workflows_ (e.g. single particle tracking). From 06b51cc2976e17d1d8dc3df3f16c605dcc873194 Mon Sep 17 00:00:00 2001 From: Leandro Scholz Date: Wed, 30 Jan 2019 13:14:50 -0200 Subject: [PATCH 12/12] Update how-to-curate.md --- How-to-curate/how-to-curate.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/How-to-curate/how-to-curate.md b/How-to-curate/how-to-curate.md index a474491..848a477 100644 --- a/How-to-curate/how-to-curate.md +++ b/How-to-curate/how-to-curate.md @@ -88,30 +88,30 @@ Canonical software name assigned by the tagger, preferably the software develope **7.** **SHOULD** follow the naming patterns (see below) -> ## Naming Patterns -> For components that are part of a collection, use the pattern -> ``{collectionName} toolName`` -> For tools that simply wrap or provide an interface to some other tool (**NOTE: this is still uncommon in bioimage analysis and was a particular situation in biotools. It needs more discussion)**, use the pattern +## Naming Patterns + For components that are part of a collection, use the pattern + ``{collectionName} toolName`` + For tools that simply wrap or provide an interface to some other tool (**NOTE: this is still uncommon in bioimage analysis and was a particular situation in biotools. It needs more discussion)**, use the pattern >``{collectionName} toolName {API|WS}{(providerName)}`` *e.g.* ``EMBOSS water API (ebi)`` -> where: + where: -> * ``collectionName`` is the name of library, main software in which the component is present natively or other collection the underlying tool is from (if applicable). -> * ``toolName`` is the canonical name of the underlying tool -> * use ``API`` for Web APIs or ``WS`` for Web services -> * ``providerName`` is the name of the institute providing the online service (if applicable) + * ``collectionName`` is the name of library, main software in which the component is present natively or other collection the underlying tool is from (if applicable). + * ``toolName`` is the canonical name of the underlying tool + * use ``API`` for Web APIs or ``WS`` for Web services + * ``providerName`` is the name of the institute providing the online service (if applicable) -> If in exceptional cases (*i.e.* when registering, as separate entries, versions of a tool with fundamental differences, substitute for ``toolName`` in the pattern above: + If in exceptional cases (*i.e.* when registering, as separate entries, versions of a tool with fundamental differences, substitute for ``toolName`` in the pattern above: > ``toolname versionID`` *e.g.* ``ilastik 0.5`` where ``versionID`` is the version number. ->> ** Tip: ** ->> - in case of mulitple related entries be consistent, *e.g.* ``Open PHACTS`` and ``Open PHACTS API`` ->> - be wary of names that are very long (>25 characters). If shortening the name is necessary, don't truncate it in a way (*e.g.* within the middle of a word) that would render it meaningless or unintuitive +**Tip:** +* in case of mulitple related entries be consistent, *e.g.* ``Open PHACTS`` and ``Open PHACTS API`` +* be wary of names that are very long (>25 characters). If shortening the name is necessary, don't truncate it in a way (*e.g.* within the middle of a word) that would render it meaningless or unintuitive ## Description Textual description of the software, e.g. *"The neuTube is a collection of neuron reconstruction tools from fluorescence microscope images. It has an interactive system with a 3D viewer, which can be clicked in 3D and perform neuron tracing automatically and semi-automatically. It can automatically recognize branching points as junctions. Traced neurons can be exported to swc format, which could be imported by various software packages. neuTube has Win and Mac OS standalone executable builds and may also be installed by manual compilation."*