Documentation and How-Tos

A workflow encompasses a wide spectrum of processes, scripts, software, or pipelines designed for the examination of biomedical data across various computational settings.

Typical categories of workflows include:

1. Reproducible multi-step workflows: These utilize specialized workflow languages such as Nextflow and are considered "workflows" in the strictest sense.

2. Scripts for data analysis and figure generation: Often used in the context of preparing research publications.

3. Protocols for systematic data analysis: Developed to facilitate the methodical examination of specific data types.

4. Tutorials: These provide guidance on the usage of particular tools or the execution of analyses for specific data types.

5. Commercial workflows: Examples include cloud-based workflows offered by companies like Illumina through platforms like BaseSpace.

In general, any type of document that aids in the analysis of biomedical data can be uploaded (and potentially sold) as a workflow.

We serve as both a registry for external workflows and a repository for on-site workflows.

In addition to basic metadata such as title and description, workflows can incorporate optional elements like a main document, banner images, and supplementary attachments. Workflows with a "main document" stored on BioWorkflows.com are termed "on-site workflows," whereas those that direct users to external webpages are known as "external workflows."

Unlike other freelancing platforms like Upwork, where sellers can offer a wide range of arbitrary services, BioWorkflows distinguishes itself by anchoring services to specific workflows. These services primarily revolve around technical support for deploying and customizing existing workflows. In essence, prospective service providers are required to showcase their expertise by publishing or co-publishing (as a maintainer) an exemplary workflow. This demonstration usually include details about the type of data, operations involved, and sample output, effectively highlighting the provider's skill set. The workflows, whether free or premium, can be housed under users' or others' accounts, even as public workflows, with the service provider being the author or maintainer of these workflows.

While BioWorkflows emphasizes workflow-related services, the negotiation of exact terms between sellers and buyers provides some flexibility. This allows services to extend beyond specific workflows, offering a dynamic range of possibilities tailored to the unique needs of each service request.

BioWorkflows.com is meticulously crafted to facilitate the seamless exploration of workflows for your specific needs. We offer a spectrum of features designed to enhance your workflow exploration experience:

1. Browse Published Workflows: Peruse an extensive list of workflows that have been published and are readily available for your use.
2. Discover Public Drafts: Uncover public drafts—workflows contributed by anonymous users. These workflows are in draft status and open for your valuable input to improve them before publication (c.f., become a maintainer).
3. Search workflows: Utilize our search functionality to locate workflows based on keywords, titles, descriptions, full-text searches, and even filter them by their support status, providing you with a powerful tool to find precisely what you need.
4. Bookmark and Explore: Bookmark workflows of interest and revisit them conveniently whenever you need.
5. Explore via Keywords: Navigate through related workflows by utilizing keywords that are linked to similar themes, operations, and tools. A simple click on any keyword from the information panel leads you to the related workflows.
6. Engage Through Comments: Share your experiences and insights with the workflow community by leaving comments and feedback.
7. Rate with Comments: Express your evaluation of workflows you've purchased by assigning ratings and providing comments to help others make informed choices.

With these features, BioWorkflows.com empowers you to explore, collaborate, and make the most of the workflows tailored to your unique requirements.

• Workflow Tagging: Workflows are tagged with a diverse array of keywords, providing a nuanced description of various facets within the workflows.
• Code Snippets Tagging: Code snippets are associated with tags corresponding to the tools utilized in the code, allowing snippets to be organized by tools used.
• Forum Topic and Question Tagging: Questions and topics in our discussion forums are tagged with diverse keywords, enabling visitors to comprehend the essence of the discussions at a glance.
• User Expertise Tagging: Users can showcase their expertise by listing multiple keywords in their profiles, presenting a comprehensive snapshot of their skill set.

Keywords provide an efficient way for users to locate specific content related to their interests. To check how a tag has been used, simply click a keyword and then the  (workflows) ,  (code snippets),  (discussion topics), and   (user expertise) icons on the bottom. In addition, expertise for users allow them to be notified with the publication of relevant workflows and discussions. They also allow sellers to be idenfiied through their expertise.

At BioWorkflows.com, we maintain an extensive collection of tags, and users have the flexibility to add new tags. This can be done through the Explore Expertise page in the Service section, or when entering keywords for workflows or topics. This collaborative approach enhances the richness and diversity of content on our platform.

Code snippets are excerpts of source code extracted from workflows. They serve as valuable tools for showcasing the techniques employed by the workflows and the utilization of specific tools within these workflow processes. Most code snippets are linked to tags associated with these tools, creating a valuable resource for illustrating the practical application of these tools in real-world scenarios.

To access all code snippets from various workflows, you can select code snippets. You have the option to filter these code snippets by workflow languages or search for snippets containing specific keywords.

For a comprehensive list of code snippets associated with a particular tag, simply click on the tag of interest and then the   (code snippets) icon.

While you can search for workflows using keywords, topics, descriptions, and more, you may still find cases where you don't exactly locate what you need. In such situations, you have several options:

1. Identify users with relevant expertise and review the workflows they support. You can then post a question within the context of one of these workflows. The seller may assist you in finding the right workflows or even customizing one to suit your requirements.
2. If you have a more general question or are unsure about whom to contact, consider posting a question on our discussion forum, To maximize the quality of responses:
   • Provide detailed information about your question, including specific data types, running environments, requirements, and other relevant details. This helps other users understand your needs and provide more accurate assistance.
   • Ensure to tag your topic with appropriate tags. This practice helps us route your query to users with expertise in the related field, enhancing the likelihood of receiving valuable insights.
   • You can also opt to set up a bounty for your topic. Offering a bounty provides an incentive for other users to contribute answers to your question, increasing the chances of obtaining helpful solutions.

We provide a hassle-free 30-day full-refund policy for all premium workflows, no questions asked. However, please keep in mind that if you surpass a specific limit on returned workflows, you may face a temporary restriction on purchasing new workflows for a brief period.

BioWorkflows currently supports the following file formats as the main document for on-site workflows:

1. Jupyter Notebook (*.ipynb): It is recommended to use Jupyter notebooks that contain both markdown and code cells. Our system will automatically generate an HTML preview of the notebooks from the notebook file. Folded cells are ignored, and any embedded images will be extracted to serve as banner images for the workflow. Please note that for premium workflows, the source code is masked so users who have not purchased the workflows will not be able to see the complete source codes.
2. Rmarkdown (*.rmd): Rmarkdown files are supported and will be converted to HTML format for preview. However, due to the limitations of the format, there is no special handling for source code in this file format for premium workflows.

Workflows in alternative formats can be hosted on third-party services and registered as external workflows with BioWorkflows.

A workflow within our system can exist in one of the following modes:

• Draft: The workflow is actively being developed and can be modified. They are not viewable by others unless they are explicitly shared, or are public workflows.
• Pending: The workflow has been submitted for review and is awaiting evaluation.
• Published: The workflow is officially published and accessible to anyone. While the core contents are fixed, modifications to metadata (e.g. tags) are still possible.
• Archived: The workflow is archived and is not listed. It can be seen by its maintainers, and by users who have purchased the workflow. A draft workflow can be directly archived. No modification is allowed for archived workflows.

Published and achived workflows can be updated by forking the workflow and creating a new version.

For a visual representation of the workflow states and their transitions, please refer to the diagram below:

If you're aware of a workflow that could enhance our repository, you can assist in adding it in two ways:

1. Propose the Workflow Anonymously:

   • Click on Workflows then select Suggest a Workflow.
   • Enter the URL of the workflow, submit, and let us handle the rest.

   The workflow will undergo screening and become available as a "Public Draft." Any user can volunteer to update it by requesting maintainer status for the workflow. The workflow will eventually be published.

1. Upload the Workflow as a Registered User:

   • Log in to your account or create an account if you haven't already.
   • Click on Workflows then select Add a Workflow.
   • Adjust title, description, keywords, references etc, 
   • Submit the workflow for review, but select "publish as a public workflow during this process.

   The workflow will appear as a public workflow and you will remain a maintainer of it unless you choose to opt out of the maintainer status.

You have the option to enhance any workflow by

• Suggesting the addition or removal of keywords. To do this, navigate to the workflow's information panel, click the    button, update the keyword list, and submit your changes. The modifications will be implemented after the workflow's author reviews and approves the suggestions.
• Report problems and suggest revisions: If you notice something wrong with the workflow, you can report the issue by clicking the   dropdown menu and select Report. The report will be sent to workflow maintainers and our support team (or only our support team if you prefer).

If you wish to make more extensive alterations to the workflow, you can

• Request to become a maintainer. To initiate this process, click the   button, provide a brief explanation of why you're interested in maintaining the workflow, and submit your request. You will assume the role of a maintainer once the workflow's author (or our site administrator, for public workflows) approves your request.
• In the case of a public workflow that is still in draft status, you can also request to become the author. This is particularly useful if you authored a workflow that was contributed by others as a public workflow to our website. The process for claiming authorship of a workflow is similar to requesting to become a maintainer; just select "Request Ownership of Workflow" when requesting maintainer status. Once you become the author of the workflow, you will have full management privileges.

Becoming a maintainer of a workflow offers the added benefit of enabling you to create service listings and provide (paid) support for the workflow.

To add a workflow to the BioWorkflows Repository, follow these steps:

1. Login or Create an Account: If you don't have an account, create one.

2. Add the Workflow:

   • If you're registering an external workflow, go to "Workflows" and select Add Workflow. Enter the URL and click submit.
   • If it's an on-site workflow, click "Upload an On-Site Workflow."

3. Modify Workflow Details: Adjust the name, keywords, descriptions, attachments. The system will flag any issues preventing you from publishing the workflow.

4. Submit for Publication: Submit the workflow for review. If you want it to be published as a public workflow, select "publish as a public workflow" before submitting for approval.

5. Approval Process: If your workflow doesn't contain sensitive information and doesn't have obvious copyright issues, it will be approved for publication.

Following these steps, you can contribute your workflow to the BioWorkflows Repository, optionally as a public workflow. The same process applies if you would like to upload a premium workflow, but you will need to first become a seller before you can set prices to your workflows.

If the source code of a workflow is available online (e.g. hosted on GitHub), it is easiest to use select snippet from attachments or external file to automatically extract code snippets from one or more source files. 

Here are some tips to help you import code snippets efficiently:

• Identify Popular Workflow Languages: If the workflow is written in popular workflow languages like Nextflow, CWL, or Snakemake, our bot can automatically identify and extract code snippets from submodules. For example, in Snakemake workflows, you often only need to add the URL for the Snakefile.
• Use Wildcard Characters: If the workflow consists of multiple files on GitHub, you can use wildcard characters to specify multiple files. For instance, you can add all R source files from a URL like this  https://github.com/user/repo/tree/master/dir/*.R 
• Review and Adjust Tags: Code snippets are automatically tagged with keywords based on matching signatures. You may need to change the signature of tags if they tag the wrong code snippets.. 
• Manual Review: The automatic snippet import process may include repetitive or uninteresting housekeeping steps. You can manually remove these snippets, although repetitive snippets (if sharing the same tags) and non-informative (non-tagged) snippets are not displayed by default.

By following these tips, you can efficiently import code snippets from online workflows, ensuring that the extracted snippets are relevant and well-tagged.

There are three ways to add new tags or edit existing tags:

1. When you're editing a tag list, for example, when revising the keyword list of a workflow, you can create a new tag instead of selecting an existing one. Please note that these new tags won't have descriptions and won't be available for use by others. To edit these tags, go to Services -> Explore Expertise, then select My Keywords from the dropdown box
2. Another way to add tag is to click the Propose a keyword button from the Explore Expertise page. You can enter the URL or name of a BioConda, Python package, etc., and select the type of keyword from the dropdown menu. Our system can automatically retrieve metadata for these tags. If your tag doesn't come from any of these known sources, you can enter the information directly by selecting "Enter Directly."
3. To edit an existing tag, click  , then   Suggest Change,  make appropriate changes and submit for review. 

All new keywords and updates to existing keywords will be reviewed by our staff before being published as site-wide keywords. 

Code snippets are automatically tagged by keywords with matching signature, which matches content of the code snippets through regular expression.

The signature of keywords are specified by one or more fields in their metadata:

1. library: This field specifies the name of a Python or R library, for example python:pandas or r:ggplot2. This signature will allow the tag to be matches to statements such as import pandas as pd and library(ggplot2).
2. signature: This field is suitable for commands or function calls from bioinformatic tools or libraries. It can consist of either a string (name of the command or function, e.g. fastqc) or multiple values separated by "|"  (e.g.  fastaclean|fasta2esd  for a tool that can be identified from one or the two identifiers).
3. regex_signature: This is the most generic form of regular expression that should follow POSIX regular expression for database query.  

To check or add signature of tags, go to the details page of a tag, click  , then   Suggest Change, add the corresponding fields to its metadata, and submit.

To avoid duplicated tagging while still keeping tags from different channels, some tags are assigned the metadata "alias_of=name_of_primary_tag," which designates them as aliases to corresponding primary tags. Only primary tags are used to tag workflows, topics, and code snippets, although the aliases can still be used to enter them.

You can follow the procesure of adding or editing a tag to set the alias_of metadata for an existing tag. This helps maintain a clean and efficient tagging system while allowing users to find relevant content regardless of the source or channel.

The process of uploading a premium workflow is the same as uploading a regular workflow. However, you will need to become a seller before you can set the price of workflows and list them as premium workflows.

The content of workflows cannot be altered once they are published. You can however always fork a workflow to create a newer version.

• After you publish a forked workflow, the newer version will become the default version.
• The old version are still available from the workflow details page. In this way you can create a variations of the same workflow (e.g. one for mouse and one for human) and you even set the name of the variants to make them easier to remember.

If you have set up GitHub integration to the workflow, pushing to a published workflow will automatically create a new version of the workflow in draft mode.

• Integrate your account with GitHub. You can either sign in with your GitHub account, or link your GitHub account with your BioWorkflows account after signing in.
• Create and maintain your workflows in GitHub repositories
• When you upload your workflows to BioWorkflows, add the blob URL to "Auto-update from GitHub"

After the workflow is uploaded, pushing changes to your GitHub repositories will automatically update the workflows on BioWorkflows.com. More specifically,

• If your workflow is in draft mode, the content of the workflow will be replaced by the new version.
• If your workflow is already published, a new draft version will be created.

At BioWorkflows, showcasing your expertise in specific areas is a prerequisite before creating service listings related to a workflow. To initiate service provision, follow these steps:

1. Obtain seller satus.
   • Start by registering and creating an account.
   • Submit a request to become a seller, bearing in mind that seller status entails specific restrictions and responsibilities.
2. Publish a workflow
   • Publish a workflow in your areas of expertise, ensuring it includes clear background information, input details, operations, sample outputs, and a description of the running environment for which the workflow should be deployed.
   • Alternatively, request to become a maintainer for a public workflow or one from your team members. Revise workflows as needed, because many public workflows lack detailed descriptions.
3. Create a service listing
   • Detail your service by creating a listing, specifying the service particulars, expected rates, and delivery timeframes.
4. Accept and provide services
   • Stay vigilant with your email communications and promptly respond to user requests.
   • Engage in negotiations regarding service details and set realistic completion expectations.
   • Diligently work on the service request, making every effort to meet the agreed-upon timeframe.

By following these steps, you not only fulfill the prerequisites for creating service listings on BioWorkflows but also acknowledge the responsibilities that come with seller status. This ensures a transparent and well-informed engagement for all involved parties on the platform. If you have any inquiries or need support, feel free to reach out—we're here to assist you.

To access your available funds, you need to configure a withdrawal method via your seller settings page. It's important to be aware of our withdrawal policy, which includes the following key points:

1. Pending Sales Period:

   There's a grace period during which sales are considered as pending. During this time, users have the option to return your workflows without any questions asked.

2. Finalized Sales:

   After a period of 30 days, all sales become final. This means that you can only withdraw funds from workflows that were sold more than 30 days ago.

Badges are compact tiles containing links to various pages on BioWorkflows.com. They serve as quick access points to workflows featured on the website. There are three types of badges you can use:

• :  The generic "bioworkflows" badge, which links to a specific workflow.
• The "listed on bioworkflows" badge, indicating that the workflow is showcased on our website.
•  The "supported at bioworkflows" badge, signifying that the paid (or free) support is available through bioworkflows.

To incorporate any of these badges into your workflow, follow these steps:

1. Visit the information panel on the workflow details page.
2. Choose either the Markdown or HTML version.
3. Copy the provided code snippet.
4. Insert the snippet onto the homepage of your workflow.

The code snippet page associated with a keyword offers practical examples of how the tools can be utilized, effectively functioning as an alternative form of documentation for the tool itself. We provide a badge that includes a link that compiles all the code snippets related to a specific keyword, making it a valuable resource for users.

To embed this badge on your software tool's homepage, follow these steps:

1. Locate a tag that is relevant to your tool from either the workflow list or the details page.
2. Click the tag, look for the "</>" icon; click it to access the code snippet page associated with the tag.
3. Scroll to the end of the snippet listing page and select the "Add a badge to your website" link.
4. Depending on your website's development framework, choose either the HTML or Markdown version of the badge for seamless integration.
5. Copy the source code for the badge and insert it into the appropriate locations on your website's homepage.