FoldLeft_conf.pm

Go to the documentation of this file.

=pod
 
=head1 NAME
 
Bio::EnsEMBL::Hive::Examples::Factories::PipeConfig::FoldLeft_conf
 
=head1 SYNOPSIS
 
    # Initialize the pipeline
    init_pipeline.pl Bio::EnsEMBL::Hive::Examples::Factories::PipeConfig::FoldLeft_conf -pipeline_url $EHIVE_URL
 
    # Run all the jobs except the final one
    runWorker.pl -url $EHIVE_URL -can_respecialize -analyses_pattern '%-report'
 
    # Run it in debug mode to see its parameters and find the values that have been folded
    runWorker.pl -url $EHIVE_URL -analyses_pattern 'report' -debug
 
    # The job input_ids only contain the various states of "input_id_list"
    db_cmd.pl -url $EHIVE_URL -sql 'SELECT job_id, prev_job_id , analysis_id, input_id FROM job'
 
    # whilst the computed data is in the "accu" table
    db_cmd.pl -url $EHIVE_URL -sql 'SELECT * FROM accu'
 
=head1 DESCRIPTION
 
    eHive implementation of tail-recursion of "fold-left".
    In general terms, we have a list $l (each element is of type 'a), a function $f from ('b, 'a) to 'b, and an initial value $ini of type 'b.
    Left-folding is a recursion on $l where we first compute $f($ini, $l[1]) and use this value as $ini on the sub-list that starts from the
    second element. Overall, the formula is $f($f( ... $f($f($ini, $l[1]), $l[2]) ... , $l[n-1]), $l[n])  [1-based arrays]
    This recursion mode is also called "tail-recursion" because once we've consumed the first element, we can loop with a new $ini and a new $l.
 
    In this example, each element of the list (each input_id) has two parameters: an integer "val" and a string "str". We have a "fold" analysis
    that folds the list in three ways: integer addition, string concatenation, and total sum length (to show we can accumulate a different type
    from the elements)
 
=head1 LICENSE
 
    See the NOTICE file distributed with this work for additional information
    regarding copyright ownership.
 
    Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
    You may obtain a copy of the License at
 
         http://www.apache.org/licenses/LICENSE-2.0
 
    Unless required by applicable law or agreed to in writing, software distributed under the License
    is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and limitations under the License.
 
=head1 CONTACT
 
    Please subscribe to the Hive mailing list:  http://listserver.ebi.ac.uk/mailman/listinfo/ehive-users
    to discuss Hive-related questions or to be notified of our updates
 
=cut
 
 
package Bio::EnsEMBL::Hive::Examples::Factories::PipeConfig::FoldLeft_conf;
 
use strict;
use warnings;
 
use Bio::EnsEMBL::Hive::PipeConfig::HiveGeneric_conf;
use base ('Bio::EnsEMBL::Hive::PipeConfig::HiveGeneric_conf');  # All Hive databases configuration files should inherit from HiveGeneric, directly or indirectly
 
 
sub pipeline_analyses {
    my ($self) = @_;
    return [
 
        # The default parameter of GrabN is to take 1 hash at a time from the left
        {   -logic_name => 'consume_list',
            -module     => 'Bio::EnsEMBL::Hive::Examples::Factories::RunnableDB::GrabN',
            -input_ids => [{
                'input_id_list' => [map { {val => $_, str => "x$_"} } (1, 6, 3, 8)],
            }],
            -flow_into => {
                # To "fold", the fan requires access to its parent's parameters, via either INPUT_PLUS or the parameter stack
                '2->A' => { 'fold' => INPUT_PLUS },
                'A->1' => WHEN( '#_list_exhausted#' => [ 'report' ], ELSE [ 'consume_list' ] ),
            },
        },
 
        {   -logic_name    => 'fold',
            -module        => 'Bio::EnsEMBL::Hive::RunnableDB::Dummy',
            -parameters    => {
                # default value to initialise the recursion
                'sum'           => 100,
                'concat'        => 'START:',
                'length'        => 0,
                # Note that the expressions refer to the parameters defined above. The first job will
                # use those default values stored at the analysis level, but the next jobs will use the
                # value accumulated by the accu below, and propagated with INPUT_PLUS
                'new_sum'       => '#expr( #sum# + #val# )expr#',
                'new_concat'    => '#expr( #concat# . #str# )expr#',
                'new_length'    => '#expr( #length# + length(#str#) )expr#',
            },
            -flow_into     => {
                1 => [
                    # accu_name must be the name of a parameter that has a default value above
                    # accu_input_variable must be generated by the runnable
                    '?accu_name=sum&accu_input_variable=new_sum',
                    '?accu_name=concat&accu_input_variable=new_concat',
                    '?accu_name=length&accu_input_variable=new_length',
                ],
            }
        },
 
        # This analysis will have 1 job with sum=118, concat="START:x1x6x3x8" and length=8
        {   -logic_name    => 'report',
            -module        => 'Bio::EnsEMBL::Hive::RunnableDB::Dummy',
        },
    ];
}
 
1;