Tutorials

Register for a portal account

Before building a BioCompute Object (BCO), please register an account first by following the listed steps:

1. Go to Log in on the header:
   
2. For first-time users, please click on “Don’t have an account? Sign up”, fill out the required information and click SUBMIT.
   
   Google authentication is also enabled on BioCompute. Users can register a BCO account from click on Create BCO Portal account with Google.
   
3. An activation email from object.biocompute@gmail.com should be sent to your entered email address for account activation.
4. Log in to the Portal account using your registered username and password or sign in with a Google account or ORCID account.

Account information

Under Account, personal/account information can be modified. In addition, the users are able to change passwords, add servers, and edit Groups and Permissions.

1. After logging in, click on your name on the top right corner of the page to go to the account:
   
2. On the Account page, account details can be changed. For example, names, email address, affiliation, ORCID. Click on UPDATE PROFILE to finalize the changes.
3. 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.
4. BioCompute Team has set up a BCODB Sandbox server for developers. To add it, please contact BioCompute admin for information.

Prefix Registration/Permission changes for account

• For detail information, please see here

Search for a draft or Published BCO

1. Click on BioCompute Object DB icon on the navigation bar:
   
2. On BioCompute Object DB page, 2 types of searches are available.
   • 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.
     
   • Advanced Search:
     • 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.
     • 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.
     • Click on SUBMIT SEARCH to return desired search results.

Build a BCO

1. Click on BCO Builder icon on the Navigation Bar:
   
2. 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.
   
3. 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.
   
4. For information to fill out each domain, please go to Provenance Domain, Usability Domain, Extension Domain, Description Domain, Execution Domain, I/O Domain, Parametric Domain, and Error Domain. Or, click on the question mark icon on each domain for more information.
5. User can also view/edit the BCO in JSON by clicking on either TREE VIEW JSON or RAW JSON VIEW.
   
   
   
6. 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.
   
7. To save the draft properly, first choose a server to save the draft.
   
8. 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.
   

   Enter a prefix in the BCO Prefix field
9. 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.
   

   Click on CREATE NEW DRAFT to save the draft
10. 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.
11. 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.
12. 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 page for common errors and possible solutions.
    
13. 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.
    
14. If any errors were detected during validation, then correct those errors based on the validation results. Revalidation is needed before publishing.
15. Other options on the Builder page include DOWNLOAD DRAFT in JSON format and DELETE DRAFT permanently.

Submitting a BCO via Swagger

1. Navigate to https://biocomputeobject.org/api/docs/#/BCO%20Management/api_objects_drafts_create_create
2. Click on the lock in the top right of the picture below:
   
3. 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”.
   
4. Click on Edit Value
   
5. 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"}}}
   }
 ]

1. Hit the EXECUTE button to submit the request.
   • If successfully, should look like this:
     
   • If unsuccessful, will look like this:
     

BCODB Sandbox

1. To add BCODB Sandbox to your account, please contact BioCompute Team.
2. Once added, you should see BCODB Sandbox under your account page:
   
3. The first Copy button will copy your token to the clipboard.
4. Then go to https://sandbox.biocomputeobject.org/api/docs/, you can either authorize using the button at the top:
   
   Or, the lock icon next to the API to authorize:
   
5. In the popup window, enter the following: "Token <Your copied token>". Then click Authorize.
   
6. Click on Try it out, enter the BCO content in JSON format in the editable text box, then click Execute to finish. You will get a 401 The token provided does not have draft permissions for this prefix 'string' but you will see the CURL as well:

<curl -X POST "https://sandbox.biocomputeobject.org/api/objects/drafts/create/" -H "accept: application/json" -H "Authorization: Token ******************************" -H "Content-Type: application/json" -H "X-CSRFToken: heH4n52dPNFR4fLiYrL8MbyBS77Q0lEkV2KiwXuxpnMd0NspVfxrWTisMsS7DNdK" -d "{ \"POST_api_objects_draft_create\": [ { \"prefix\": \"string\", \"owner_group\": \"string\", \"object_id\": \"string\", \"schema\": \"string\", \"contents\": { \"additionalProp1\": {} } } ]}">

Converting a Galaxy Workflow and Validation

Please refer to this page for more details.