Difference between revisions of "Best practices"

From Earth Science Information Partners (ESIP)
Line 7: Line 7:
  
  
−
==Discovery==
+
==Search==
 
Recommendations for discovering software in the IMCR.
 
Recommendations for discovering software in the IMCR.
 
===IMCR===
 
===IMCR===
Line 14: Line 14:
 
* '''Author''' supports search across software authors, including individuals, organizations and initiatives. Separate multiple terms with commas. An auto-complete drop down field lists software authors found in the IMCR.
 
* '''Author''' supports search across software authors, including individuals, organizations and initiatives. Separate multiple terms with commas. An auto-complete drop down field lists software authors found in the IMCR.
 
* '''Keywords''' supports search across keywords tagged to each software item of the IMCR. Browse the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] for a list of keywords and definitions.
 
* '''Keywords''' supports search across keywords tagged to each software item of the IMCR. Browse the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] for a list of keywords and definitions.
−
* '''Language'''
+
* '''Language''' supports search by implementation language.
−
* '''License'''  
+
* '''License''' supports search by the license under which the software was released.
−
* '''Operating System'''  
+
* '''Operating System''' supports search by operating system the software can run on.
 
* '''Publisher''' supports search across software publishers. The content of "Publisher" is often times equivalent to content listed under "Author"
 
* '''Publisher''' supports search across software publishers. The content of "Publisher" is often times equivalent to content listed under "Author"
  
Line 23: Line 23:
 
===IMCR===
 
===IMCR===
 
Publishing software in the IMCR is easy. Create a user account and begin publishing your software. The metadata wizard guides you through the process of describing important attributes of your software, however some additional guidance is offered below to help optimize discovery and understanding of your software.
 
Publishing software in the IMCR is easy. Create a user account and begin publishing your software. The metadata wizard guides you through the process of describing important attributes of your software, however some additional guidance is offered below to help optimize discovery and understanding of your software.
−
 
−
====Identify====
 
−
* '''What are general categories (keywords, labels) for this software?''' - Use the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] to select keywords for your software. Keywords are the primary mechanism by which users find software in the IMCR. Add both broad terms and narrower terms and be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to IMCR chairs.
 
−
 
−
====Understand====
 
−
* '''Who created this software?''' - Add the project, organization, person, and/or initiative that helped create this software. Be careful to spell names correctly! NOTE: This field auto-completes to software creators already listed in the IMCR. This field is searchable by the "Filter Software List" "Author" field.
 
−
* '''Are there any additional contributors of note for this software?''' - Add major contributors to the software. These entities can be of the same types listed under "Who created this software?" (i.e. project, organization, person, etc.). The content of this field is searchable by the "Filter Software List" "Author" field.
 
−
* '''(Optional) Who is the publisher of this software if not the author?''' - Add the project, organization, person, or initiative who published this software. Duplicate entries are encouraged from the "Who created this software?" field. The content of this field is searchable by the "Filter Software List" "Publisher" field. Separate multiple entries with commas.
 
−
* '''What are domain specific keywords for this software? (e.g. hydrology, climate)''' - List science domain specific keywords to this field and to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the [https://vocab.lternet.edu/vocab/vocab/index.php LTER Controlled Vocabulary "disciplines" category] to keyword your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.
 
−
 
−
====Execute====
 
−
* '''What license is the code released under?''' - A list of common licenses are recognized and available through the auto-complete feature of this field.
 
−
* '''What language(s) is the software written in? ''' - A list of languages already listed in the IMCR are provided by the auto-complete feature of this field. If the language is not available in the drop down list, then add it.
 
−
* '''What operating system can the software run on?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FIAO_0000025&jump_to_nav=true the Software Ontology "programming language" category] to keyword this field.
 
−
* '''What other software does the software require to be installed?''' - ''DO NOT USE THIS FIELD!'' OntoSoft automatically adds entries in this field to the master list of registered software in the IMCR. We don't want the IMCR populated with these items.
 
−
 
−
====Do Research====
 
−
* '''What input files does the software require?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fedamontology.org%2Fformat_1915&jump_to_nav=true the Software Ontology "Format" category] to keyword this field.
 
−
* '''What output files does the software produce?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fedamontology.org%2Fformat_1915&jump_to_nav=true the Software Ontology "Format" category] to keyword this field.
 
  
 
===IMCR (new)===
 
===IMCR (new)===
 
New methods for registering (and maintaining) software in the IMCR greatly reduce manual effort.
 
New methods for registering (and maintaining) software in the IMCR greatly reduce manual effort.
 +
 
====R Package in CRAN====
 
====R Package in CRAN====
 
To register a CRAN package:
 
To register a CRAN package:
Line 52: Line 34:
 
* Add the URL for the package source code copied from the CRAN Package landing page (e.g. https://cran.r-project.org/web/packages/antiword/index.html) under '''Execute > What is the URL for the code?'''
 
* Add the URL for the package source code copied from the CRAN Package landing page (e.g. https://cran.r-project.org/web/packages/antiword/index.html) under '''Execute > What is the URL for the code?'''
 
IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.
 
IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.
 +
 
====Any software in GitHub====
 
====Any software in GitHub====
 
Don't use this option if the software is archived in an official repository (e.g. CRAN, PyPI). To register a GitHub repository:
 
Don't use this option if the software is archived in an official repository (e.g. CRAN, PyPI). To register a GitHub repository:
Line 59: Line 42:
 
* Add the URL of the GitHub repository (e.g. https://github.com/EDIorg/EMLassemblyline) under '''Update > How is the software being developed or maintained?'''
 
* Add the URL of the GitHub repository (e.g. https://github.com/EDIorg/EMLassemblyline) under '''Update > How is the software being developed or maintained?'''
 
IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.
 
IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.
 +
 
====Python Package in PyPI====
 
====Python Package in PyPI====
 +
TBD
 +
 
====Repository content====
 
====Repository content====
−
Registering a repository, not a software library
+
Registering a repository, not a software library (e.g. https://github.com/bd-R)
−
Example: https://github.com/bd-R
+
Methods TBD. Contact chairs for more information.
 +
 
 
====Single scripts====
 
====Single scripts====
 
Registering single scripts in the IMCR.
 
Registering single scripts in the IMCR.
 +
 +
====Identify====
 +
* '''What are general categories (keywords, labels) for this software?''' - Use the [http://vocab.lternet.edu/vocab/registry/index.php IMCR Controlled Vocabulary] to select keywords for your software. Keywords are the primary mechanism by which users find software in the IMCR. Add both broad terms and narrower terms and be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to IMCR chairs.
 +
 +
====Understand====
 +
* '''Who created this software?''' - Add the project, organization, person, and/or initiative that helped create this software. Be careful to spell names correctly! NOTE: This field auto-completes to software creators already listed in the IMCR. This field is searchable by the "Filter Software List" "Author" field.
 +
* '''Are there any additional contributors of note for this software?''' - Add major contributors to the software. These entities can be of the same types listed under "Who created this software?" (i.e. project, organization, person, etc.). The content of this field is searchable by the "Filter Software List" "Author" field.
 +
* '''(Optional) Who is the publisher of this software if not the author?''' - Add the project, organization, person, or initiative who published this software. Duplicate entries are encouraged from the "Who created this software?" field. The content of this field is searchable by the "Filter Software List" "Publisher" field. Separate multiple entries with commas.
 +
* '''What are domain specific keywords for this software? (e.g. hydrology, climate)''' - List science domain specific keywords to this field and to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the [https://vocab.lternet.edu/vocab/vocab/index.php LTER Controlled Vocabulary "disciplines" category] to keyword your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.
 +
 +
====Execute====
 +
* '''What license is the code released under?''' - A list of common licenses are recognized and available through the auto-complete feature of this field.
 +
* '''What language(s) is the software written in? ''' - A list of languages already listed in the IMCR are provided by the auto-complete feature of this field. If the language is not available in the drop down list, then add it.
 +
* '''What operating system can the software run on?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fpurl.obolibrary.org%2Fobo%2FIAO_0000025&jump_to_nav=true the Software Ontology "programming language" category] to keyword this field.
 +
* '''What other software does the software require to be installed?''' - ''DO NOT USE THIS FIELD!'' OntoSoft automatically adds entries in this field to the master list of registered software in the IMCR. We don't want the IMCR populated with these items.
 +
 +
====Do Research====
 +
* '''What input files does the software require?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fedamontology.org%2Fformat_1915&jump_to_nav=true the Software Ontology "Format" category] to keyword this field.
 +
* '''What output files does the software produce?''' - Use [https://bioportal.bioontology.org/ontologies/SWO/?p=classes&conceptid=http%3A%2F%2Fedamontology.org%2Fformat_1915&jump_to_nav=true the Software Ontology "Format" category] to keyword this field.

Revision as of 15:18, September 23, 2019

Return to IM Code Registry main page


Overview

Below are a set of best practice (BP) recommendations for the IMCR.


Search

Recommendations for discovering software in the IMCR.

IMCR

To find software, use the IMCR Controlled Vocabulary in combination with the "Filter Software List" located in the IMCR Portal. Terms in the controlled vocabulary are organized around the data life cycle, which is an intuitive way to think about the different categories of information management. Browse the controlled vocabulary to identify terms you'd like to search on, then add these terms to the "Filter Software List" search tool to find what you're looking for. Some notes on the search tool:

  • Search only supports search across software names. Free-text searching is not supported.
  • Author supports search across software authors, including individuals, organizations and initiatives. Separate multiple terms with commas. An auto-complete drop down field lists software authors found in the IMCR.
  • Keywords supports search across keywords tagged to each software item of the IMCR. Browse the IMCR Controlled Vocabulary for a list of keywords and definitions.
  • Language supports search by implementation language.
  • License supports search by the license under which the software was released.
  • Operating System supports search by operating system the software can run on.
  • Publisher supports search across software publishers. The content of "Publisher" is often times equivalent to content listed under "Author"

Registering

BPs for registering software in the IMCR

IMCR

Publishing software in the IMCR is easy. Create a user account and begin publishing your software. The metadata wizard guides you through the process of describing important attributes of your software, however some additional guidance is offered below to help optimize discovery and understanding of your software.

IMCR (new)

New methods for registering (and maintaining) software in the IMCR greatly reduce manual effort.

R Package in CRAN

To register a CRAN package:

  • Click Publish your software
  • Add the software name under Identify > What is the software called?
  • Add keywords from the IMCR Vocabulary under Identify > What are general categories (keywords, labels) for this software?
  • Add the URL for the package source code copied from the CRAN Package landing page (e.g. https://cran.r-project.org/web/packages/antiword/index.html) under Execute > What is the URL for the code?

IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.

Any software in GitHub

Don't use this option if the software is archived in an official repository (e.g. CRAN, PyPI). To register a GitHub repository:

  • Click Publish your software
  • Add the software name under Identify > What is the software called?
  • Add keywords from the IMCR Vocabulary under Identify > What are general categories (keywords, labels) for this software?
  • Add the URL of the GitHub repository (e.g. https://github.com/EDIorg/EMLassemblyline) under Update > How is the software being developed or maintained?

IMCR bots automate completion and maintenance of all the other metadata fields by using the supplied URL to extract metadata from the CRAN package DESCRIPTION file and any associated GitHub. Maintenance of keywords is conducted by IMCR admin humans.

Python Package in PyPI

TBD

Repository content

Registering a repository, not a software library (e.g. https://github.com/bd-R) Methods TBD. Contact chairs for more information.

Single scripts

Registering single scripts in the IMCR.

Identify

  • What are general categories (keywords, labels) for this software? - Use the IMCR Controlled Vocabulary to select keywords for your software. Keywords are the primary mechanism by which users find software in the IMCR. Add both broad terms and narrower terms and be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to IMCR chairs.

Understand

  • Who created this software? - Add the project, organization, person, and/or initiative that helped create this software. Be careful to spell names correctly! NOTE: This field auto-completes to software creators already listed in the IMCR. This field is searchable by the "Filter Software List" "Author" field.
  • Are there any additional contributors of note for this software? - Add major contributors to the software. These entities can be of the same types listed under "Who created this software?" (i.e. project, organization, person, etc.). The content of this field is searchable by the "Filter Software List" "Author" field.
  • (Optional) Who is the publisher of this software if not the author? - Add the project, organization, person, or initiative who published this software. Duplicate entries are encouraged from the "Who created this software?" field. The content of this field is searchable by the "Filter Software List" "Publisher" field. Separate multiple entries with commas.
  • What are domain specific keywords for this software? (e.g. hydrology, climate) - List science domain specific keywords to this field and to the field "What are general categories (keywords, labels) for this software?" located at /Locate/Important. Use the LTER Controlled Vocabulary "disciplines" category to keyword your software. Add broad terms and narrower terms to improve search and discovery. Be careful to spell the keywords correctly! If you can't find a suitable keyword in the controlled vocabulary, please suggest it and it's corresponding definition to the IMCR chairs.

Execute

  • What license is the code released under? - A list of common licenses are recognized and available through the auto-complete feature of this field.
  • What language(s) is the software written in? - A list of languages already listed in the IMCR are provided by the auto-complete feature of this field. If the language is not available in the drop down list, then add it.
  • What operating system can the software run on? - Use the Software Ontology "programming language" category to keyword this field.
  • What other software does the software require to be installed? - DO NOT USE THIS FIELD! OntoSoft automatically adds entries in this field to the master list of registered software in the IMCR. We don't want the IMCR populated with these items.

Do Research

Retrieved from "https://wiki.esipfed.org/w/index.php?title=Best_practices&oldid=66695"
GNU Free Documentation License 1.2
Powered by MediaWiki
Powered by Semantic MediaWiki