Restructure tags and questionnaires

[dleehr]

During some whiteboarding/discussion yesterday, @johnbradley and I documented some issues with the current workflow importer and some desired changes. See also https://github.com/Duke-GCB/bespin/issues/2.

Under discussion:

• The current structure depends on a workflow, workflow version, and questionnaire.
• Each of these levels can be identified by a tag, but the exact structure doesn't fit our mental model of workflows/versions/configurations or forward/backward compatibility
• Workflow version numbers are provided by the client at workflow loading time (see https://github.com/Duke-GCB/bespin-cwl/issues/62) but are not synchronized between dev/prod and aren't manifested externally (in the file name for example)
• The short names and descriptions need to be streamlined to match up with the tags and display text
• Separate the questionnaire into a parameter set and VM strategy object.
• Streamline the implementation of tags.
  • Worfklows should have a unique tag - e.g. 'wes' or possibly 'wes-gatk4', need feedback
  • Workflow versions should have an auto-generated unique tag - e.g. 'v4'
  • Questionnaires be reworked and called ParameterSets, and should have a unique tag identifiying the system-provided inputs - e.g. 'b37-human-xGen' or 'b37-human-SeqCapV3'

While the questionnaire logic is heavily integrated with the UI, created Jobs don't directly reference a questionnaire. The JobFactory is responsible for creating jobs based on a questionnaire and answerset. This can be updated in the API and CLI to address the CLI use case better.

[johnbradley]

I had the thought that a job could be made up of

• workflow version specified by a tag eg.wes-gatk4/v4
• multiple parameter sets specified by tags:
  • xGenCaptureKit
  • DecoyGenome
• user specified files and parameters

Command Line Changes

User lists workflows which defaults to the current versions of each workflow.

$ bespin workflows list
  Id  Name                     Version Tag
----  -----------------------  ----------------------------------
   1  Whole Exome Sequencing   whole-exome-sequencing/v4

The user can list parameter sets available for this workflow:

$ bespin paramsets list
  Id  Name                Tag
----  ------------------  --------------------
   1  x-gen Capture kit   xGenCaptureKit
   2  decoy Genome        DecoyGenome

The user can then create a job specifying the workflow version tag and any number of valid paramset tags:

bespin jobs init --workflow whole-exome-sequencing/v4 --paramset xGenCaptureKit --paramset DecoyGenome --outfile job1.yml

Then run the job could be created as normal.

[dleehr]

Thanks for kicking off the disucssion 😄. Some thoughts

• with a week of hindsight and now seeing your concrete examples, I think the term we came up with ParameterSet is too technically focused on how we thought Bespin should implement this functionality. Maybe calling them "profiles" or "configurations" better describes what the user is thinking when choosing a set of parameters.
• Requiring multiple of these parameter sets to compose a job is flexible and composable, but I think it will lead to surprises and unexpected errors. I'd propose we keep it at requiring exactly one parameter set, which corresponds to a single file (JSON containing the pre-filled input values) having the same name as the set. I think it's reasonable to maintain JSON documents with these different configurations, and keeping that simple will make it easier to collaborate on.
• Based on feedback, there was a lot of value in seeing the tag as one string with / delimiters. Adding --paramset prefixes to assemble or scan past will dilute that. I think it's similar to the feedback we received about replicating { "class": "File", "path": ... } structures.

I think the ideal CLI command would look something like this:

bespin job create wes-gatk4/v4/xgen-b37decoy > my-job.yml

thoughts?

[johnbradley]

I like "configurations". It seems natural to say: I ran workflow wes-gatk4 version 5 with the xgen-b37decoy configuration.Collaborating with users on a single "configuration" will be much easier. We should also get user feedback on naming the "configuration". I'm good with keeping the existing CLI functionality.