Skip to content
GitLab
Commit 06e48646 authored by Floreal Cabanettes's avatar Floreal Cabanettes
Browse files

Update jflow documentation

parent 3e532c9d
Hide whitespace changes
Inline Side-by-side
docs/jflow_core_component.html
View file @ 06e48646
......@@ -441,7 +441,115 @@ class MyComponent (Component):
<p>This method takes the same arguments as <code>add_input_file()</code>. However, adding this parameter,
the component can take a list file files and the object attribut <code>self.parameter_name</code> will be
settled as a Python list.</p>
settled as a Python list.</p>
<h3>add_input_directory</h3>
<p>Input directories are similar to files.</p>
<h4>Example</h4>
<p>In the following example, an input directory named <code>reference</code> is added to the workflow. The
provided directory is required.</p>
<div>
<pre class="pre-hl "><code class="python">self.add_input_directory("reference",
"Folder containing the reference genome",
required=True)</code></pre>
</div>
<h4>Options</h4>
<p>There are two positional argument : <code>name</code> and <code>help</code>. All other options are keyword options. </p>
<div class="table-responsive">
<table class="table table-bordered table-striped">
<thead>
<tr style="white-space:nowrap">
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>string</td>
<td>true</td>
<td>None</td>
<td>The name of the parameter. The parameter value is accessible
within the workflow object through the attribute named <code>self.parameter_name</code>.</td>
</tr>
<tr>
<td>help</td>
<td>string</td>
<td>true</td>
<td>None</td>
<td>The parameter help message.</td>
</tr>
<tr>
<td>default</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>The default path value.</td>
</tr>
<tr>
<td>required</td>
<td>boolean</td>
<td>false</td>
<td>false</td>
<td>Wether or not the parameter can be ommitted.</td>
</tr>
<tr>
<td>flag</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>The command line flag (if the value is None, the flag will be <code>--name</code>).</td>
</tr>
<tr>
<td>group</td>
<td>string</td>
<td>false</td>
<td>"default"</td>
<td>The value is used to group a list of parameters in sections. The group is used in both command line and GUI.</td>
</tr>
<tr>
<td>display_name</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>The parameter name that should be displayed on the final form.</td>
</tr>
<tr>
<td>cmd_format</td>
<td>string</td>
<td>false</td>
<td>""</td>
<td>The command format is the parameter skeleton required to build the final command line.</td>
</tr>
<tr>
<td>argpos</td>
<td>integer</td>
<td>false</td>
<td>-1</td>
<td>The parameter position in the command line.</td>
</tr>
</tbody>
</table>
</div>
</div>
......
docs/jflow_core_workflow.html
View file @ 06e48646
......@@ -88,6 +88,13 @@
<li><a href="#get_resource">Get resource</a></li>
</ul>
</li>
<li><a href="#your-rules">Custom rules</a>
<ul class="nav nav-stacked">
<li><a href="#simple-rules">Simple rules</a></li>
<li><a href="#link-rules">Link rules</a></li>
<li><a href="#conditional-link-rules">Conditional link rules</a></li>
</ul>
</li>
</ul>
</nav>
......@@ -293,6 +300,28 @@ class MyWorkflow (Workflow):
<td>If this parameter is part of a multiple parameter, <code>add_to</code> allows to define to which "parent" parameter it should be
linked to.</td>
</tr>
<tr>
<td>rules</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>Define custom rules on the parameter. Rules are separated by a ";"<br/>
Available rules:<br/>
<ul>
<li><strong>Exclude:</strong> exclude parameters. If one is given, the other must be not given.<br/>
<em>Syntax: Exclude=param1,param2,...</em></li>
<li><strong>ExcludeIf:</strong> exclude parameters if condition is raised. If the parameter has one certain value, the other must be not given.<br/>
<em>Syntax: ExcludeIf?[value1,value2]=param1,param2,...</em> (value1 OR value2)</li>
<li><strong>ToBeRequired:</strong> require other parameters if parameter is given.<br/>
<em>Syntax: ToBeRequired=param1,param2,...</em></li>
<li><strong>ToBeRequiredIf:</strong> require other parameters if parameter is given and has a certain value.<br/>
<em>Syntax: ToBeRequiredIf?[value1,value2]=param1,param2,...</em> (value1 OR value2)</li>
<li><strong>ActivateIf:</strong> only if the parameter has a certain value, other parameters should be given.<br/>
<em>Syntax: ActivateIf?[value1,value2]=param1,param2,...</em> (value1 OR value2)</li>
</ul>
</td>
</tr>
</tbody>
</table>
......@@ -440,6 +469,25 @@ class MyWorkflow (Workflow):
also provides the file size units between "bytes", "Kb", "Mb", "Gb", "Tb", "Pb", "Eb" and "Zb". A value of 10Mb will
restrict the user to upload a file of 10 Mega Bytes.</td>
</tr>
<tr>
<td>rules</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>Define custom rules on the parameter. Rules are separated by a ";"<br/>
Available rules:<br/>
<ul>
<li><strong>Exclude:</strong> exclude parameters. If one is given, the other must be not given.<br/>
<em>Syntax: Exclude=param1,param2,...</em></li>
<li><strong>ToBeRequired:</strong> require other parameters if parameter is given.<br/>
<em>Syntax: ToBeRequired=param1,param2,...</em></li>
<li><strong>UniqueAll:</strong> the file given for this parameter must be not given for another one</li>
<em>Syntax: Unique</em>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
......@@ -449,6 +497,8 @@ class MyWorkflow (Workflow):
<p>This method takes the same arguments as <code>add_input_file()</code>. However, adding this parameter,
the final user will be allowed to provide multiple files and the object attribut <code>self.parameter_name</code> will be
settled as a Python list.</p>
<p>The <code>rules</code> argument has a rule available only on input files list: Unique. If this rule is given, a same file must be unique on the list.</p>
<h3>add_input_directory()</h3>
<p>
......@@ -568,6 +618,22 @@ class MyWorkflow(Workflow):
<td>None</td>
<td>The parameter name that should be displayed on the final form.</td>
</tr>
<tr>
<td>rules</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>Define custom rules on the parameter. Rules are separated by a ";"<br/>
Available rules:<br/>
<ul>
<li><strong>Exclude:</strong> exclude parameters. If one is given, the other must be not given.<br/>
<em>Syntax: Exclude=param1,param2,...</em></li>
<li><strong>ToBeRequired:</strong> require other parameters if parameter is given.<br/>
<em>Syntax: ToBeRequired=param1,param2,...</em></li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
......@@ -664,6 +730,22 @@ self.add_parameter("sequencer", "The sequencer type.", choices=["HiSeq2000",
<td>None</td>
<td>The parameter name that should be displayed on the final form.</td>
</tr>
<tr>
<td>rules</td>
<td>string</td>
<td>false</td>
<td>None</td>
<td>Define custom rules on the parameter. Rules are separated by a ";"<br/>
Available rules:<br/>
<ul>
<li><strong>Exclude:</strong> exclude parameters. If one is given, the other must be not given.<br/>
<em>Syntax: Exclude=param1,param2,...</em></li>
<li><strong>ToBeRequired:</strong> require other parameters if parameter is given.<br/>
<em>Syntax: ToBeRequired=param1,param2,...</em></li>
</ul>
</td>
</tr>
</tbody>
</table>
......@@ -675,47 +757,6 @@ self.add_parameter("sequencer", "The sequencer type.", choices=["HiSeq2000",
settled as a Python list of Python dictionary.</p>
</div>
<div id="exclusion_rules" class="subgroup">
<h2>Exclusion rules</h2>
<p>Jflow offers the possibility to exclude some rules from each otehrs. To do so, the method <code>add_exclusion_rule()</code> is available. </p>
<h3>add_exclution_rule()</h3>
<h4>Example</h4>
<p>In the following example, the final user will not be allowed to provide both <code>fasta_file</code> and <code>fastq_file</code> parameters.</p>
<div>
<pre class="pre-hl "><code class="python">self.add_input_file("fasta_file", "Path to the fasta file.", format="fasta")
self.add_input_file("fastq_file", "Path to the fastq file.", format="fastq")
self.add_exclution_rule("fasta_file", "fastq_file")</code></pre>
</div>
<h4>Options</h4>
<p>The method accept the following options</p>
<div class="table-responsive">
<table class="table table-bordered table-striped">
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Required</th>
<th>Default value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>*args2exclude</td>
<td>string</td>
<td>true</td>
<td>None</td>
<td>The name of the parameter to exclude.</td>
</tr>
</tbody>
</table>
</div>
</div>
</section>
......@@ -923,6 +964,174 @@ bwamem = self.add_component("BWAmem", [bwaindex.databank, self.reads])</code></p
</div>
</div>
</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>
</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-link-rules" class="subgroup">
<h2>Conditional link rules</h2>
<p>These rules are like link 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>[&lt;list_of_possible_values&gt;]=&lt;targets&gt;</code>.<br/>
Example : <code>ExcludeIf?[value1,value2]=target1,target2</code>.</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 (ConditionalLinkRule):
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 ConditionalLinkRule class, it has the same attributes a Link 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>
</section>
</div>
</div>
......
Supports Markdown
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