Commit 7d08c769 authored by Floreal Cabanettes's avatar Floreal Cabanettes
Browse files

Update jflow doc

parent da99f69f
......@@ -972,200 +972,7 @@ bwamem = self.add_component("BWAmem", [bwaindex.databank, self.reads])</code></p
</section>
<section id="your-rules" class="group">
<h1 class="page-header">Create your own parameter rules</h1>
<p>You can create your own custom parameter rules. These rules must be declared into the file
<code>workflows/rules.py</code>. In this file, you define the rule checking protocol. Into the
parameter definition, the rule is set as a string describing the rule (see below).</p>
<p>Their are three types of rules : simple rules, link rules and conditional link rules.
</p>
<div id="simple-rules" class="subgroup">
<h2>Simple rules</h2>
<p>Simple rules are declared as a simple word in the rule definition of the parameter. Example: <code>Unique</code>.
This name is the name of the class declared below (case-sensitive).</p>
<p>To create a such rule, create a class that inherit from the SimpleRule class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (SimpleRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from SimpleRule class, it has some attributes already defined:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>user_args</td>
<td>Dict</td>
<td>Dictionary describing arguments given by the user: name of each parameter as key, associated
with their own values.</td>
</tr>
<tr>
<td>wf_instance</td>
<td>Workflow instance</td>
<td>The workflow instance object.</td>
</tr>
<tr>
<td>parameter_name</td>
<td>string</td>
<td>Name of the parameter containing the rule.</td>
</tr>
<tr>
<td>parameter_value</td>
<td>string</td>
<td>Value of the parameter containing the rule.</td>
</tr>
<tr>
<td>all_files</td>
<td>List</td>
<td>List of all files given by the user, in any parameter.</td>
</tr>
<tr>
<td>wf_parameter</td>
<td>Parameter instance</td>
<td>The parameter object containing the rule.</td>
</tr>
<tr>
<td>is_file_list</td>
<td>boolean</td>
<td>True if the parameter is an input file list.</td>
</tr>
<tr>
<td>is_a_file</td>
<td>boolean</td>
<td>True if the parameter is an input file.</td>
</tr>
<tr>
<td>is_file</td>
<td>boolean</td>
<td>True if the parameter is an input file or an input file list.</td>
</tr>
<tr>
<td>is_directory</td>
<td>boolean</td>
<td>True if the parameter is an input directory</td>
</tr>
<tr>
<td>is_file_or_directory</td>
<td>boolean</td>
<td>True if the parameter is an input file, an input file list or an input directory.</td>
</tr>
<tr>
<td>nb_rows</td>
<td>Dict</td>
<td>Number of rows for each MultipleParameterList. Example: {sample:3, data:2}, where
sample and data are the name of tow MultipleParameterList.
</td>
</tr>
</tbody>
</table>
</div>
<div id="link-rules" class="subgroup">
<h2>Link rules</h2>
<p>Link rules are rules defined on one parameter but having action on other parameters. The string of
the rule is composed of its name and the targets parameters the rule acts on. Example:
<code>Exclude=target1,target2</code>. In this example, "Exclude" is the name of the rule declared
below (case-sensitive).</p>
<p>To create the rule, create a class that inherit from the LinkRule class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (LinkRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from the LinkRule class, it has the same attributes a Simple rule have. But it has
also additional attributes:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>targets_args</td>
<td>List</td>
<td>List of arguments the rules acts on.</td>
</tr>
</tbody>
</table>
</div>
<div id="conditional-rules" class="subgroup">
<h2>Conditional rules</h2>
<p>These rules are like simple rules, but are enabled only if the parameter has one of given values.
The syntax of the rule string is:
<code>&lt;name_of_the_rule&gt;<b>?</b>(ALL|ANY)[&lt;conditions&gt;]</code>.<br/>
Example : <code>RequiredIf?ALL[param1=value1,param2!=value2]</code>.</p>
<p>ALL or ANY: if ALL is set, all conditions must be raised to activate the rule. If ANY is set, the
condition is raised if at least one condition is raised.</p>
<p>Conditions are written with this structure : &lt;parameter_name&gt;=&lt;parameter_value&gt;
(if parameter must be equal to value) or &lt;parameter_name&gt;!=&lt;parameter_value&gt;
(if parameter must be not equal to value. The parameter name is the name of a workflow
parameter. If the parameter is the one into the rule is defined, we can use the keyword
<em>self</em> instead of its name.<br/>Special values:
<ul>
<li>parameter_name=*: condition is raised if the parameter is given, regardless of its value</li>
<lI>parameter_name=None: condition is raised if the parameter is not given</lI>
</ul>
</p>
<p>To create the rule, create a class that inherit from the Conditional class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (ConditionalRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from the SimpleRule class, it has the same attributes a Simple rule have. But it has
also additional attributes:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>conditions</td>
<td>List</td>
<td>List of parameter values that enabled the rule.</td>
</tr>
<tr>
<td>condition_raised</td>
<td>string</td>
<td>Value that enables the parameter if any, else None</td>
</tr>
</tbody>
</table>
</div>
<div id="raise-error-warning" class="subgroup">
<h2>Raise an error or a warning in a rule</h2>
<p>Into the <code>check()</code> function of your rule, when the rule generate an error, use the
function <code>self.error()</code>.<br/>
Example: <code>self.error("Parameter " + self.parameter_name + " was not correct")</code>.</p>
<p>If the rule generate a warning, use the function <code>self.warning()</code> instead.<br/>
Example: <code>self.warning("Parameter " + self.parameter_name + " will be ignored")</code></p>
</div>
</section>
</div>
</div>
......
......@@ -4,7 +4,7 @@
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Jflow Types</title>
<title>Jflow Rules</title>
<!-- Bootstrap core CSS -->
<link href="css/bootstrap.min.css" rel="stylesheet">
......@@ -78,7 +78,13 @@
<li><a href="#raise-error-warning">Raise an error or a warning</a></li>
</ul>
</li>
<li><a href="#howuse" >How to use a new rule</a></li>
<li><a href="#howuse" >How to use a new rule</a>
<ul class="nav nav-stacked">
<li><a href="#use-simple-rules">Simple rules</a></li>
<li><a href="#use-link-rules">Link rules</a></li>
<li><a href="#use-conditional-rules">Conditional rules</a></li>
</ul>
</li>
</ul>
</nav>
......@@ -86,7 +92,7 @@
<section id="where" class="group">
<h1>Where to add a new rule</h1>
<p>In the <code>workflows/</code> directory, jflow provides a <code>types.py</code> file where new types can be added.</p>
<p>In the <code>workflows/</code> directory, jflow provides a <code>rules.py</code> file where new types can be added.</p>
<pre class="pre-hl"><code class="ini">jflow/
├── bin/
├── docs/
......@@ -96,46 +102,226 @@
│ ├── extparsers/
│ ├── __init__.py
│ ├── formats.py
│ └── types.py [ file where to add new jflow types ]
│ ├── rules.py [ file where to add new jflow rules ]
│ └── types.py
├── applications.properties
└── README</code></pre>
</section>
<section id="how" class="group">
<h1>How to add a new type</h1>
<p>In jflow a type is represented by a function named by the desired type name. The function should take only
one argument, whose value is given by the user. The function is in charge to check and/or modify
the given value. If an error occurred or if the value does not meet the expected criteria, an
<code>argparse.ArgumentTypeError</code> should be raised with the suitable error message. This message will
be used by jflow to inform the final user of the error.</p>
<p>In the following example, the <code>intBetween1and100</code> function checks if the input value is in between
1 and 100:</p>
<pre class="pre-hl "><code class="python">def intBetween1and100(myint):
# the input argument type is allways a string
try:
myint = int(myint)
except:
raise argparse.ArgumentTypeError("'"+str(myint)+"' is not a valid int!")
if myint <= 100 and myint >= 1:
return myint
else:
raise argparse.ArgumentTypeError("'"+str(myint)+"' is not between 1 and 100!")</code></pre>
<h1>How to add a new rule</h1>
<p>Their are three types of rules : simple rules, link rules and conditional link rules.
</p>
<div id="simple-rules" class="subgroup">
<h2>Simple rules</h2>
<p>To create a such rule, create a class that inherit from the SimpleRule class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (SimpleRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from SimpleRule class, it has some attributes already defined:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>user_args</td>
<td>Dict</td>
<td>Dictionary describing arguments given by the user: name of each parameter as key, associated
with their own values.</td>
</tr>
<tr>
<td>wf_instance</td>
<td>Workflow instance</td>
<td>The workflow instance object.</td>
</tr>
<tr>
<td>parameter_name</td>
<td>string</td>
<td>Name of the parameter containing the rule.</td>
</tr>
<tr>
<td>parameter_value</td>
<td>string</td>
<td>Value of the parameter containing the rule.</td>
</tr>
<tr>
<td>all_files</td>
<td>List</td>
<td>List of all files given by the user, in any parameter.</td>
</tr>
<tr>
<td>wf_parameter</td>
<td>Parameter instance</td>
<td>The parameter object containing the rule.</td>
</tr>
<tr>
<td>is_file_list</td>
<td>boolean</td>
<td>True if the parameter is an input file list.</td>
</tr>
<tr>
<td>is_a_file</td>
<td>boolean</td>
<td>True if the parameter is an input file.</td>
</tr>
<tr>
<td>is_file</td>
<td>boolean</td>
<td>True if the parameter is an input file or an input file list.</td>
</tr>
<tr>
<td>is_directory</td>
<td>boolean</td>
<td>True if the parameter is an input directory</td>
</tr>
<tr>
<td>is_file_or_directory</td>
<td>boolean</td>
<td>True if the parameter is an input file, an input file list or an input directory.</td>
</tr>
<tr>
<td>nb_rows</td>
<td>Dict</td>
<td>Number of rows for each MultipleParameterList. Example: {sample:3, data:2}, where
sample and data are the name of tow MultipleParameterList.
</td>
</tr>
</tbody>
</table>
</div>
<div id="link-rules" class="subgroup">
<h2>Link rules</h2>
<p>These rules are like simple rules, but acts not only for the parameter into the rule is defined</p>
<p>To create the rule, create a class that inherit from the LinkRule class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (LinkRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from the SimpleRule class, it has the same attributes a Simple rule have. But it has
also additional attributes:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>targets_args</td>
<td>List</td>
<td>List of arguments the rules acts on.</td>
</tr>
</tbody>
</table>
</div>
<div id="conditional-rules" class="subgroup">
<h2>Conditional rules</h2>
<p>These rules are like simple rules, but are enabled only if the parameter has one of given values.
<p>To create the rule, create a class that inherit from the Conditional class:</p>
<div>
<pre class="pre-hl "><code class="python">class YourRule (ConditionalRule):
def check():
# Your code</code></pre>
</div>
<p>Into the <code>check()</code> function, write how to check the rule.</p>
<p>As the rule inherit from the SimpleRule class, it has the same attributes a Simple rule have. But it has
also additional attributes:</p>
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>conditions</td>
<td>List</td>
<td>List of parameter values that enabled the rule.</td>
</tr>
<tr>
<td>condition_raised</td>
<td>string</td>
<td>Value that enables the parameter if any, else None</td>
</tr>
</tbody>
</table>
</div>
<div id="raise-error-warning" class="subgroup">
<h2>Raise an error or a warning in a rule</h2>
<p>Into the <code>check()</code> function of your rule, when the rule generate an error, use the
function <code>self.error()</code>.<br/>
Example: <code>self.error("Parameter " + self.parameter_name + " was not correct")</code>.</p>
<p>If the rule generate a warning, use the function <code>self.warning()</code> instead.<br/>
Example: <code>self.warning("Parameter " + self.parameter_name + " will be ignored")</code></p>
</div>
</section>
<section id="howuse" class="group">
<h1>How to use a new type</h1>
<h1>How to use a new rule</h1>
<p>The new created type can then be used in both <code>add_parameter</code> and <code>add_parameter_list</code> of the
class <code>jflow.workflow.Workflow</code> and <code>jflow.component.Component</code> as following:</p>
<pre class="pre-hl "><code class="python">[...]
def define_parameters(self, function="process"):
self.add_parameter("my_param", "A value in between 1 and 100", type="intBetween1and100")
[...]</code></pre>
<p>To add a rule on a parameter, define the argument "rule" on the <code>add_parameter</code>
function of the workflow. The rule is written as follow, depending of the type of rule. To use several
rules on the same parameter, join them by a ";".</p>
<p>Rules can also be added to inputs (files, files list, directories) and multiple parameters, on their
dedicated function.</p>
<div id="use-simple-rules" class="subgroup">
<h2>Simple rules</h2>
<p>Just write the name of the rule. Warning: this name is case-sensitive</p>
<p>Example: <code>Unique</code></p>
</div>
<div id="use-link-rules" class="subgroup">
<h2>Link rules</h2>
<p>Write the name of the rule, followed by a "=" and the list of the other parameters (targets) the
rule acts on.</p>
<p>Example: <code>Exclude=param_1,param_2</code></p>
</div>
<div id="use-conditional-rules" class="subgroup">
<h2>Conditional rules</h2>
<p>The syntax of this rule is like that: <code>&lt;name_of_the_rule&gt;<b>?</b>(ALL|ANY)[&lt;conditions&gt;]</code>.</p>
<p>ALL or ANY: if ALL is set, all conditions must be raised to activate the rule. If ANY is set, the
condition is raised if at least one condition is raised.</p>
<p>Conditions are written with this structure : &lt;parameter_name&gt;=&lt;parameter_value&gt;
(if parameter must be equal to value) or &lt;parameter_name&gt;!=&lt;parameter_value&gt;
(if parameter must be not equal to value. The parameter name is the name of a workflow
parameter. If the parameter is the one into the rule is defined, we can use the keyword
<em>self</em> instead of its name.<br/>Special values:
<ul>
<li>parameter_name=*: condition is raised if the parameter is given, regardless of its value</li>
<li>parameter_name=None: condition is raised if the parameter is not given</li>
</ul>
</p>
<p>Example : <code>RequiredIf?ALL[param_1=value_1,param_2!=value_2]</code>.</p>
</div>
</section>
</div>
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment