added docs and fixed arg error in create_metawfr, ff_key was missing

Author: Michele Berselli

_version.py

@@ -1,4 +1,4 @@
 """Version information."""
 
 # The following line *must* be the last in the module, exactly as formatted:
-__version__ = "0.2.2"
+__version__ = "0.2.3"

docs/ff_functions.rst

@@ -2,34 +2,154 @@
 FF_functions
 ============
 
+create_metawfr
+**************
+
+Function to create a meta-workflow-run json structure for case from case metadata.
+Return json structure for the meta-workflow-run.
+Can automatically post the meta-workflow-run as *MetaWorkflowRun* object on the portal and patch ``meta_workflow_run`` key for case with the new uuid.
+
+``create_metawfr_from_case(metawf_uuid<str>, case_uuid<str>, type<str>, ff_key<key>, post=False, patch_case=False, verbose=False)``
+
+.. code-block:: python
+
+    from magma_ff import create_metawfr
+
+    # UUIDs
+    metawf_uuid = '' # uuid for meta-workflow
+    case_uuid = '' # uuid for the case
+
+    # Post | Patch
+    #   post=True to automatically post a new MetaWorkflowRun object on the portal
+    #   patch_case=True to update meta_workflow_run for case with uuid for new meta-workflow-run
+
+    # type
+    #   'WGS trio', 'WGS proband', 'WGS cram proband'
+    type = 'WGS trio'
+
+    # ff_key
+    #   -> key generated by ff_utils to authenticate on the portal
+
+    metawfr_json = create_metawfr.create_metawfr_from_case(metawf_uuid, case_uuid, type, ff_key, post=False, patch_case=False, verbose=False)
+
+
 run_metawfr
 ***********
 
 Function to run workflow-runs in meta-workflow-run.
 Calculates which workflow-runs are ready to run, starts the run with tibanna and patch the metadata.
 
-``run_metawfr(metawfr_uuid<str>, ff_key<key>, verbose=False, sfn='tibanna_zebra', env='fourfront-cgap')``
+``run_metawfr(metawfr_uuid<str>, ff_key<key>, verbose=False, sfn='tibanna_zebra', env='fourfront-cgap', maxcount=None)``
 
 .. code-block:: python
 
+    from magma_ff import run_metawfr
+
+    # UUIDs
+    metawfr_uuid = '' # uuid for meta-workflow-run
+
+    # ff_key
+    #   -> key generated by ff_utils to authenticate on the portal
+
+    # env
+    #   environment to use to access metadata
+    env = 'fourfront-cgap'
+
+    # sfn
+    #   step function to use for tibanna
+    sfn = 'tibanna_zebra'
+
+    run_metawfr.run_metawfr(metawfr_uuid, ff_key, verbose=False, sfn='tibanna_zebra', env='fourfront-cgap', maxcount=None)
 
 
 status_metawfr
 **************
 
 Function to check and patch status for workflow-runs in meta-workflow-run that are running.
+Update the status to ``completed`` or ``failed`` for finished runs.
 
 ``status_metawfr(metawfr_uuid<str>, ff_key<key>, verbose=False, env='fourfront-cgap')``
 
 .. code-block:: python
 
+    from magma_ff import status_metawfr
+
+    # UUIDs
+    metawfr_uuid = '' # uuid for meta-workflow-run
+
+    # ff_key
+    #   -> key generated by ff_utils to authenticate on the portal
+
+    # env
+    #   environment to use to access metadata
+    env = 'fourfront-cgap'
+
+    status_metawfr.status_metawfr(metawfr_uuid, ff_key, verbose=False, env=env)
 
 
 import_metawfr
 **************
 
-Function to import metadata for meta-workflow-run from a different meta-workflow-run.
+Creates a new meta-workflow-run json structure for case using specified ``create_metawfr`` function.
+Imports information from different meta-workflow-run specified as ``metawfr_uuid`` for steps that are listed in ``steps_name``.
+Return json structure for the new meta-workflow-run.
+Can automatically post the new meta-workflow-run as *MetaWorkflowRun* object on the portal.
 
-``import_metawfr(metawf_uuid<str>, metawfr_uuid<str>, case_uuid<str>, steps_name<str list>, create_metawfr<function>, ff_key<key>, post=False, verbose=False)``
+``import_metawfr(metawf_uuid<str>, metawfr_uuid<str>, case_uuid<str>, steps_name<str list>, create_metawfr<function>, type<str>, ff_key<key>, post=False, verbose=False)``
 
 .. code-block:: python
+
+    from magma_ff import import_metawfr
+    from magma_ff import create_metawfr
+
+    # UUIDs
+    metawf_uuid = '' # uuid for meta-workflow
+    metawfr_uuid = '' # uuid for old meta-workflow-run to import
+    case_uuid = '' # uuid for the case
+
+    # Post
+    #   post=True to automatically post a new MetaWorkflowRun object on the portal
+
+    # ff_key
+    #   -> key generated by ff_utils to authenticate on the portal
+
+    # type
+    #   'WGS trio', 'WGS proband', 'WGS cram proband'
+    type = 'WGS trio'
+
+    # steps_name
+    steps_name = ['workflow_granite-mpileupCounts', 'workflow_gatk-ApplyBQSR-check']
+
+    # create_metawfr
+    #   function to use to create a new meta-workflow-run structure from case
+    #   e.g. create_metawfr.create_metawfr_from_case
+
+    metawfr_json = import_metawfr.import_metawfr(metawf_uuid, metawfr_uuid, case_uuid, steps_name, create_metawfr.create_metawfr_from_case, type, ff_key)
+
+
+reset_metawfr
+*************
+
+Re-set workflow-runs in meta-workflow-run that correspond to a step defined in ``step_name`` and with status in ``status``.
+
+``reset_status(metawfr_uuid<str>, status<str | str list>, step_name<str | str list>, ff_key<key>, verbose=False)``
+
+.. code-block:: python
+
+    from magma_ff import reset_metawfr
+
+    # UUIDs
+    metawfr_uuid = '' # uuid for meta-workflow-run
+
+    # ff_key
+    #   -> key generated by ff_utils to authenticate on the portal
+
+    # step_name
+    #   name or list of names for step-workflows that need to be reset
+    step_name = ['workflow_granite-mpileupCounts', 'workflow_gatk-ApplyBQSR-check']
+
+    # status
+    #   status or list of status to reset
+    status = 'failed' # running | completed | failed
+
+    reset_metawfr.reset_status(metawfr_uuid, status, step_name, ff_key, verbose=False)

magma_ff/create_metawfr.py

@@ -19,14 +19,14 @@ def create_metawfr_from_case(metawf_uuid, case_uuid, type, ff_key, post=False, p
 
     if type == 'WGS cram proband':
         pedigree = pedigree[0:1]
-        input = create_metawfr_input_from_pedigree_proband_only(pedigree)
+        input = create_metawfr_input_from_pedigree_proband_only(pedigree, ff_key)
     elif type == 'WGS proband':
         pedigree = pedigree[0:1]
-        input = create_metawfr_input_from_pedigree_proband_only(pedigree)
+        input = create_metawfr_input_from_pedigree_proband_only(pedigree, ff_key)
     elif type == 'WGS trio':
-        input = create_metawfr_input_from_pedigree_trio(pedigree)
+        input = create_metawfr_input_from_pedigree_trio(pedigree, ff_key)
 
-    metawfr = create_metawfr_from_input(input, metawf_uuid, case_meta)
+    metawfr = create_metawfr_from_input(input, metawf_uuid, case_meta, ff_key)
 
     # post meta-wfr
     if post:
@@ -40,10 +40,11 @@ def create_metawfr_from_case(metawf_uuid, case_uuid, type, ff_key, post=False, p
         res_patch = ff_utils.patch_metadata({'meta_workflow_run': metawfr['uuid']}, case_uuid, key=ff_key)
         if verbose:
             print(res_patch)
+
     return metawfr
 
 
-def create_metawfr_from_input(metawfr_input, metawf_uuid, case_meta):
+def create_metawfr_from_input(metawfr_input, metawf_uuid, case_meta, ff_key):
     metawf_meta = ff_utils.get_metadata(metawf_uuid, add_on='?frame=raw&datastore=database', key=ff_key)
     metawfr = {'meta_workflow': metawf_uuid,
                'input': metawfr_input,
@@ -71,7 +72,7 @@ def create_metawfr_from_input(metawfr_input, metawf_uuid, case_meta):
     return metawfr
 
 
-def create_metawfr_input_from_pedigree_cram_proband_only(pedigree):
+def create_metawfr_input_from_pedigree_cram_proband_only(pedigree, ff_key):
     sample = pedigree[0]
     sample_acc = sample['sample_accession']
     sample_meta = ff_utils.get_metadata(sample_acc, add_on='?frame=raw&datastore=database', key=ff_key)
@@ -97,7 +98,7 @@ def create_metawfr_input_from_pedigree_cram_proband_only(pedigree):
     return input
 
 
-def create_metawfr_input_from_pedigree_proband_only(pedigree):
+def create_metawfr_input_from_pedigree_proband_only(pedigree, ff_key):
     sample = pedigree[0]
     sample_acc = sample['sample_accession']
     sample_meta = ff_utils.get_metadata(sample_acc, add_on='?frame=raw&datastore=database', key=ff_key)
@@ -140,7 +141,7 @@ def create_metawfr_input_from_pedigree_proband_only(pedigree):
     return input
 
 
-def create_metawfr_input_from_pedigree_trio(pedigree):
+def create_metawfr_input_from_pedigree_trio(pedigree, ff_key):
     # prepare fastq input
     r1_uuids_fam = []
     r2_uuids_fam = []
@@ -195,6 +196,7 @@ def create_metawfr_input_from_pedigree_trio(pedigree):
 def sort_pedigree(pedigree):
     sorted_pedigree = sorted(pedigree, key=lambda x: x['relationship'] != 'proband') # make it proband-first
     sorted_pedigree[1:] = sorted(sorted_pedigree[1:], key=lambda x: x['relationship'] not in ['mother','father']) # parents next
+
     return sorted_pedigree
 
 
@@ -213,6 +215,7 @@ def pedigree_to_qc_pedigree(samples_pedigree):
             'sample_name': sample.get('sample_name', '')
             }
         qc_pedigree.append(member_qc_pedigree)
+
     return qc_pedigree
 
 
@@ -222,4 +225,5 @@ def remove_parents_without_sample(samples_pedigree):
         parents = a_member['parents']
         new_parents = [i for i in parents if i in individuals]
         a_member['parents'] = new_parents
+
     return samples_pedigree

magma_ff/import_metawfr.py

@@ -57,4 +57,6 @@ def import_metawfr(metawf_uuid, metawfr_uuid, case_uuid, steps_name, create_meta
             print(res_post)
         #end if
     #end if
+
+    return run_json_updated
 #end def