Tutorials: Difference between revisions

From BCOeditor Wiki
Jump to navigation Jump to search
(Updated documentation based on new portal changes in May 2023)
No edit summary
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
== Register for a portal account ==
{{DISPLAYTITLE:<span style="position: absolute; clip: rect(1px 1px 1px 1px); clip: rect(1px, 1px, 1px, 1px);">{{FULLPAGENAME}}</span>}}
__NOTOC__
<!-- BANNER ACROSS TOP OF PAGE -->
<!-- BANNER ACROSS TOP OF PAGE -->
<div id="ggw-topbanner" style="clear:both; position:relative; box-sizing:border-box; width:100%; margin:1.2em 0 6px; min-width:47em; border:1px solid #ddd; background-color:#f9f9f9; color:#000;">
    <div style="margin:0.4em; text-align:center;">
        <div style="font-size:160%; padding:.1em;">Welcome to BioCompute Tutorial,</div>
        <div style="font-size:100%;">This page provides information regarding the BioCompute portal. It has several sections on different topics that will help you to navigate through most of the functions on the BioCOmpute Portal.
    </div>
</div>
<div style="clear: both;"></div>


Before building a BioCompute Object (BCO), please register an account first by following the listed steps:
<div id="ggw_row2" style="display: flex; flex-flow: row wrap; justify-content: space-between; padding: 0; margin: 0 -5px 0 -5px;">
# Go to '''Log in''' on the header:[[File:May 2023 Homepage.png|center|thumb|804x804px]]
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
#For first-time users, please click on “'''Don’t have an account? Sign up'''”, fill out the required information and click '''SUBMIT'''. [[File:May 2023 Account Register.png|thumb|center]]Google authentication is also enabled on BioCompute. Users can register a BCO account from click on '''Create BCO Portal account with Google.''' [[File:May 2023 Account Register2.png|center|thumb|559x559px]]
        <h3>[[Account registration|Account]]</h3>
#An activation email from object.biocompute@gmail.com should be sent to your entered email address for account activation.
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
#Log in to the Portal account using your registered username and password or sign in with a Google account or ORCID account.
BioCompute Team recommends all users to create an account before editing or creating a BCO. By creating an account, users can add multiple databases, edit groups/permissions, change passwords, and more.
        </div>
    </div>
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
        <h3>[[Prefix registration|Prefix and Permission]]</h3>
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
BioCompute portal enables users to create prefix for personal or public usage. Then, owner of the prefix can modify personnel permissions inside the group. For example, the owner can grant certain people draft only permissions and other people publish only permissions. 
</div>
    </div>
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
        <h3>[[Buildbcos|Build a BCO]]</h3>
<div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
The portal allows users to build a BCO using a user-friendly interface where the BCO is divided into different domain. In addition, the JSON format is also available for edit and view. By following this tutorial, users can easily build a BCO.  
        </div>
    </div>
</div>


==Account information==
<div id="ggw_row3" style="display: flex; flex-flow: row wrap; justify-content: space-between; padding: 0; margin: 0 -5px 0 -5px;">
 
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
Under Account, personal/account information can be modified. In addition, the users are able to change passwords, add servers, and edit Groups and Permissions.
        <h3>[[Search|Search BCOs]]</h3>
#After logging in, click on your name on the top right corner of the page to go to the account:[[File:May 2023 Account.png|center|thumb|800x800px]]
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
# On the Account page, account details can be changed. For example, names, email address, affiliation, ORCID. Click on '''UPDATE PROFILE''' to finalize the changes.
Users can search for an existing BCO, either publish or draft through the portal. Search can be based on keywords, prefix, owned-BCO and more.  
#The BCO databases that the account has access to are shown under '''BCO databases'''. By click on '''GROUPS/PERMISSIONS''', users can view permissions and groups associated with the account.
</div>
===Prefix Registration/Permission changes for account===
    </div>
*For detail information, please see [[Prefix registration|here]]
     <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
==Search for a draft or Published BCO==
        <h3>[[Swagger Usage]]</h3>
#Click on '''BioCompute Object DB''' icon on the navigation bar:[[File:May 2023 BCODB icon.png|center|thumb|800x800px]]
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
#On '''BioCompute Object DB''' page, 2 types of searches are available.
Users and developers can use the swagger site to interact with the BioCompute APIs to create and publish drafts.  
#*'''Simple Search''': simply enter a keyword of the BCO content in the box and click on '''SUBMIT'''. Related results should show up on the bottom of the page.[[File:May 2023 BCODB search.png|center|thumb|800x800px]]
</div>
#*'''Advanced Search:'''
    </div>
#**First choose a BCODB from the drop down if logged in. If not logged in, only '''Public BCODB''' is available. If logged, '''BCO Server''' will also show up in the dropdown.
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
#**Second, choose a '''Search Type'''. If not logged in, only '''BCO IDs''' can be selected, this returns all available BCOs that are saved under the '''Public BCODB''' server. If logged in, the other two options would become available. '''My BCOs''' option returns all the BCOs created and owned by the user. Or choose '''Prefixes''' and enter the prefix in the search box below.
        <h3>[[BCODB Sandbox]]</h3>
#**Click on '''SUBMIT SEARCH''' to return desired search results.
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
 
The BCODB sandbox is an isolated testing environment that allows developers to interact with BCO APIs without affecting the system, database, and portal. To add the BCODB sandbox to your account, please contact BioCompute Admins first.  
 
</div>
==Build a BCO==
    </div>
#Click on '''BCO Builder''' icon on the Navigation Bar:[[File:May 2023 Buider icon.png|center|thumb|800x800px]]
</div>
#Before creating a BCO, an eTag needs to be generated. To do so, click on the expand arrow in '''Object Information''' section, then click '''GENERATE ETAG'''. Do not worry about '''Object ID''', it will auto-generate when saving the BCO draft.[[File:Builder2 22.09.png|800px|thumb|center]]
    <div style="flex: 1; margin: 5px; min-width: 210px; border: 1px solid #CCC; padding: 0 10px 10px 10px; box-shadow: 0 2px 2px rgba(0,0,0,0.1); background: #f5faff;">
#To begin filling out the BCO, click on '''Provenance Domain''' to expand the section. Fill out the information as needed. Red boxes are required fields, yellow boxes are recommended fields, and plain boxes are optional fields.[[File:Builder3 22.09.png|800px|thumb|center]]
        <h3>[[Faq|FAQs]]</h3>
#For information to fill out each domain, please go to [[Provenance-domain|Provenance Domain]], [[Usability-domain|Usability Domain]], [[Extension-domain|Extension Domain]], [[Description-domain|Description Domain]], [[Execution-domain|Execution Domain]], [[Iodomain|I/O Domain]], [[Parametric-domain|Parametric Domain]], and [[Error-domain|Error Domain]]. Or, click on the question mark icon on each domain for more information.
        <div style="border-top: 1px solid #CCC; padding-top: 0.5em;">
#User can also view/edit the BCO in JSON by clicking on either '''TREE VIEW JSON''' or '''RAW JSON VIEW'''.[[File:Builder4 22.09.png|800px|thumb|center]][[File:Builder5 treeview.png|800px|thumb|center]][[File:Builder6 JSON.png|800px|thumb|center]]
For common issues and question, refer to this page. If you need more assistance, please click on Contact Us or Bug Report.  
#A BCO draft can be saved at any time of editing. In order to save a draft, go to the top of the page, and click on '''SAVING AND PUBLISHING'''.[[File:SAVE1 22.09.png|800px|thumb|center]]
</div>
#To save the draft properly, first choose a server to save the draft. [[File:SAVE2 22.09.png|800px|thumb|center]]
    </div>
#After choosing the proper server, the BCO prefix field will show up. Enter a specific prefix (e.g. BCO, ARGOS, etc.) based on user groups and permissions. The default prefix is '''BCO''', which can be used by all users.[[File:SAVE3 22.09.png|800px|thumb|center|Enter a prefix in the BCO Prefix field]]
</div>
#Click on '''CREATE NEW DRAFT'''. If the entered prefix is not correct, an error message will pop up saying “Create Draft Failed” with a specific reason. Otherwise, the message will say “Create Draft Success”. Click OK on the message to return to the builder page.[[File:SAVE4 22.09.png|800px|thumb|center|Click on CREATE NEW DRAFT to save the draft]]
#Once the new draft is created, the Builder page will refresh and generate an Object ID, which will show in the Object Information section. Continue to edit the BCO as needed.
#Once finish editing or need to save the draft again, go back to the top of the page, click on '''SAVING AND PUBLISHING''', then click '''SAVE CURRENT DRAFT'''. A pop-up window will show up and indicate the draft is saved successfully.
#Before publishing the draft, users need to validate the draft first. To do this, click on '''SAVING AND PUBLISHING'''. Choose '''Display Validation''', then '''VALIDATE DRAFT'''. A new window will pop up with validation results.Please see this [[Common_errors|page]] for common errors and possible solutions. [[File:Validate1 22.09.png|800px|thumb|center]]
# If validation results show ‘“number_of_errors”: 0’, this means the draft has passed validation and it’s ready to publish.  Go back to the Builder screen, and now the '''PUBLISH DRAFT''' button should show up, click on it to publish the draft. [[File:Publish.png|800px|thumb|center]]
#If any errors were detected during validation, then correct those errors based on the validation results. Revalidation is needed before publishing.
#Other options on the Builder page include DOWNLOAD DRAFT in JSON format and DELETE DRAFT permanently.
 
==Submitting a BCO via Swagger ==
#Navigate to https://biocomputeobject.org/api/docs/#/BCO%20Management/api_objects_drafts_create_create
#Click on the lock in the top right of the picture below:[[File:Screen Shot 2022-10-18 at 15.17.26.png|800px|thumb|center]]
#Fill in the authorization box with your token as pictured below [NOTE! You *MUST* type ‘Token’ in the box as well as putting in your token] and click “authorize”. [[File:Screen Shot 2022-10-18 at 15.18.57.png|800px|thumb|center]]
#Click on '''Edit Value'''[[File:Screen Shot 2022-10-18 at 15.20.08.png|800px|thumb|center]]
#Fill in the script:
#*Prefix: Required, BCO Prefix to use
#* Owner_group: Required, Group which owns the object and has permissions for it
#*Schema: Required, This should be ‘IEEE’
#*Contents: Required, BCO contents
#**Example:
  "POST_api_objects_draft_create": [
     {
      "prefix": "BCO",
      "owner_group": "bco_drafter",
      "schema": "IEEE",
      "contents": {"etag":"06DACE70679F35BA87A3DD6FFFED4ED24A4F5B8C2571264C37E5F1B3ADE04A31","spec_version":"https://w3id.org/ieee/ieee-2791-schema/2791object.json","provenance_domain":{"name":"TESTING HCV1a ledipasvir resistance SNP detection","version":"2.9","review":[{"status":"approved","reviewer_comment":"Approved by GW staff. Waiting for approval from FDA Reviewer","date":"2017-11-12T12:30:48-0400","reviewer":{"name":"Charles Hadley King","affiliation":"George Washington University","email":"hadley_king@gwu.edu","contribution":["curatedBy"],"orcid":"https://orcid.org/0000-0003-1409-4549"}},{"status":"approved","reviewer_comment":"The revised BCO looks fine","date":"2017-12-12T12:30:48-0400","reviewer":{"name":"Eric Donaldson","affiliation":"FDA","email":"Eric.Donaldson@fda.hhs.gov","contribution":["curatedBy"]}}],"obsolete_after":"2118-09-26T14:43:43-0400","embargo":{"start_time":"2000-09-26T14:43:43-0400","end_time":"2000-09-26T14:43:45-0400"},"created":"2017-01-24T09:40:17-0500","modified":"2018-09-21T14:06:14-0400","contributors":[{"name":"Charles Hadley King","affiliation":"George Washington University","email":"hadley_king@gwu.edu","contribution":["createdBy","curatedBy"],"orcid":"https://orcid.org/0000-0003-1409-4549"},{"name":"Eric Donaldson","affiliation":"FDA","email":"Eric.Donaldson@fda.hhs.gov","contribution":["authoredBy"]}],"license":"https://spdx.org/licenses/CC-BY-4.0.html"},"usability_domain":["Identify baseline single nucleotide polymorphisms (SNPs)[SO:0000694], (insertions)[SO:0000667], and (deletions)[SO:0000045] that correlate with reduced (ledipasvir)[pubchem.compound:67505836] antiviral drug efficacy in (Hepatitis C virus subtype 1)[taxonomy:31646]","Identify treatment emergent amino acid (substitutions)[SO:1000002] that correlate with antiviral drug treatment failure","Determine whether the treatment emergent amino acid (substitutions)[SO:1000002] identified correlate with treatment failure involving other drugs against the same virus","GitHub CWL example: https://github.com/mr-c/hive-cwl-examples/blob/master/workflow/hive-viral-mutation-detection.cwl#L20"],"extension_domain":[{"fhir_extension":[{"fhir_endpoint":"http://fhirtest.uhn.ca/baseDstu3","fhir_version":"3","fhir_resources":[{"fhir_resource":"Sequence","fhir_id":"21376"},{"fhir_resource":"DiagnosticReport","fhir_id":"6288583"},{"fhir_resource":"ProcedureRequest","fhir_id":"25544"},{"fhir_resource":"Observation","fhir_id":"92440"},{"fhir_resource":"FamilyMemberHistory","fhir_id":"4588936"}]}]},{"scm_extension":{"scm_repository":"https://github.com/example/repo1","scm_type":"git","scm_commit":"c9ffea0b60fa3bcf8e138af7c99ca141a6b8fb21","scm_path":"workflow/hive-viral-mutation-detection.cwl","scm_preview":"https://github.com/example/repo1/blob/c9ffea0b60fa3bcf8e138af7c99ca141a6b8fb21/workflow/hive-viral-mutation-detection.cwl"}}],"description_domain":{"keywords":["HCV1a","Ledipasvir","antiviral resistance","SNP","amino acid substitutions"],"xref":[{"namespace":"pubchem.compound","name":"PubChem-compound","ids":["67505836"],"access_time":"2018-13-02T10:15-05:00"},{"namespace":"pubmed","name":"PubMed","ids":["26508693"],"access_time":"2018-13-02T10:15-05:00"},{"namespace":"so","name":"Sequence Ontology","ids":["SO:000002","SO:0000694","SO:0000667","SO:0000045"],"access_time":"2018-13-02T10:15-05:00"},{"namespace":"taxonomy","name":"Taxonomy","ids":["31646"],"access_time":"2018-13-02T10:15-05:00"}],"platform":["HIVE"],"pipeline_steps":[{"step_number":1,"name":"HIVE-hexagon","description":"Alignment of reads to a set of references","version":"1.3","prerequisite":[{"name":"Hepatitis C virus genotype 1","uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/22129792","access_time":"2017-01-24T09:40:17-0500"}},{"name":"Hepatitis C virus type 1b complete genome","uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/5420376","access_time":"2017-01-24T09:40:17-0500"}},{"name":"Hepatitis C virus (isolate JFH-1) genomic RNA","uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/13122261","access_time":"2017-01-24T09:40:17-0500"}},{"name":"Hepatitis C virus clone J8CF, complete genome","uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/386646758","access_time":"2017-01-24T09:40:17-0500"}},{"name":"Hepatitis C virus S52 polyprotein gene","uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/295311559","access_time":"2017-01-24T09:40:17-0500"}}],"input_list":[{"uri":"http://example.com/dna.cgi?cmd=objFile&ids=514683","access_time":"2017-01-24T09:40:17-0500"},{"uri":"http://example.com/dna.cgi?cmd=objFile&ids=514682","access_time":"2017-01-24T09:40:17-0500"}],"output_list":[{"uri":"http://example.com/data/514769/allCount-aligned.csv","access_time":"2017-01-24T09:40:17-0500"}]},{"step_number":2,"name":"HIVE-heptagon","description":"variant calling","version":"1.3","input_list":[{"uri":"http://example.com/data/514769/dnaAccessionBased.csv","access_time":"2017-01-24T09:40:17-0500"}],"output_list":[{"uri":"http://example.com/data/514801/SNPProfile.csv","access_time":"2017-01-24T09:40:17-0500"},{"uri":"http://example.com/data/14769/allCount-aligned.csv","access_time":"2017-01-24T09:40:17-0500"}]}]},"execution_domain":{"script":[{"uri":{"uri":"https://example.com/workflows/antiviral_resistance_detection_hive.py"}}],"script_driver":"shell","software_prerequisites":[{"name":"HIVE-hexagon","version":"babajanian.1","uri":{"uri":"http://example.com/dna.cgi?cmd=dna-hexagon&cmdMode=-","access_time":"2017-01-24T09:40:17-0500","sha1_checksum":"d60f506cddac09e9e816531e7905ca1ca6641e3c"}},{"name":"HIVE-heptagon","version":"albinoni.2","uri":{"uri":"http://example.com/dna.cgi?cmd=dna-heptagon&cmdMode=-","access_time":"2017-01-24T09:40:17-0500"}}],"external_data_endpoints":[{"name":"HIVE","url":"http://example.com/dna.cgi?cmd=login"},{"name":"access to e-utils","url":"http://eutils.ncbi.nlm.nih.gov/entrez/eutils/"}],"environment_variables":{"HOSTTYPE":"x86_64-linux","EDITOR":"vim"}},"parametric_domain":[{"param":"seed","value":"14","step":"1"},{"param":"minimum_match_len","value":"66","step":"1"},{"param":"divergence_threshold_percent","value":"0.30","step":"1"},{"param":"minimum_coverage","value":"15","step":"2"},{"param":"freq_cutoff","value":"0.10","step":"2"}],"io_domain":{"input_subdomain":[{"uri":{"filename":"Hepatitis C virus genotype 1","uri":"http://www.ncbi.nlm.nih.gov/nuccore/22129792","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"filename":"Hepatitis C virus type 1b complete genome","uri":"http://www.ncbi.nlm.nih.gov/nuccore/5420376","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"filename":"Hepatitis C virus (isolate JFH-1) genomic RNA","uri":"http://www.ncbi.nlm.nih.gov/nuccore/13122261","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"uri":"http://www.ncbi.nlm.nih.gov/nuccore/386646758","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"filename":"Hepatitis C virus S52 polyprotein gene","uri":"http://www.ncbi.nlm.nih.gov/nuccore/295311559","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"filename":"HCV1a_drug_resistant_sample0001-01","uri":"http://example.com/nuc-read/514682","access_time":"2017-01-24T09:40:17-0500"}},{"uri":{"filename":"HCV1a_drug_resistant_sample0001-02","uri":"http://example.com/nuc-read/514683","access_time":"2017-01-24T09:40:17-0500"}}],"output_subdomain":[{"mediatype":"text/csv","uri":{"uri":"http://example.com/data/514769/dnaAccessionBased.csv","access_time":"2017-01-24T09:40:17-0500"}},{"mediatype":"text/csv","uri":{"uri":"http://example.com/data/514801/SNPProfile*.csv","access_time":"2017-01-24T09:40:17-0500"}}]},"error_domain":{"empirical_error":{"false_negative_alignment_hits":"<0.0010","false_discovery":"<0.05"},"algorithmic_error":{"false_positive_mutation_calls_discovery":"<0.00005","false_discovery":"0.005"}}}
    }
  ]
#Hit the '''EXECUTE''' button to submit the request.
#*If successfully, should look like this: [[File:Screen Shot 2022-10-18 at 15.49.15.png|800px|thumb|center]]
#*If unsuccessful, will look like this:[[File:Screen Shot 2022-10-18 at 15.54.04.png|800px|thumb|center]]
 
==Converting a Galaxy Workflow and Validation==
Please refer to this [[Galaxy workflow converter|page]] for more details.

Latest revision as of 21:11, 21 June 2023


Welcome to BioCompute Tutorial,
This page provides information regarding the BioCompute portal. It has several sections on different topics that will help you to navigate through most of the functions on the BioCOmpute Portal.

Account

BioCompute Team recommends all users to create an account before editing or creating a BCO. By creating an account, users can add multiple databases, edit groups/permissions, change passwords, and more.

Prefix and Permission

BioCompute portal enables users to create prefix for personal or public usage. Then, owner of the prefix can modify personnel permissions inside the group. For example, the owner can grant certain people draft only permissions and other people publish only permissions.

Build a BCO

The portal allows users to build a BCO using a user-friendly interface where the BCO is divided into different domain. In addition, the JSON format is also available for edit and view. By following this tutorial, users can easily build a BCO.

Search BCOs

Users can search for an existing BCO, either publish or draft through the portal. Search can be based on keywords, prefix, owned-BCO and more.

Swagger Usage

Users and developers can use the swagger site to interact with the BioCompute APIs to create and publish drafts.

BCODB Sandbox

The BCODB sandbox is an isolated testing environment that allows developers to interact with BCO APIs without affecting the system, database, and portal. To add the BCODB sandbox to your account, please contact BioCompute Admins first.

FAQs

For common issues and question, refer to this page. If you need more assistance, please click on Contact Us or Bug Report.

Retrieved from "https://wiki.biocomputeobject.org/index.php?title=Tutorials&oldid=350"