view release on metacpan or  search on metacpan

lib/Bio/SDRS.pm  view on Meta::CPAN

  $sdrs->calculate;

=head1 DESCRIPTION

Bio::SDRS implements the Sigmoidal Dose Response Search of assay responses
described in the paper by

Rui-Ru Ji, Nathan O. Siemers, Lei Ming, Liang Schweizer, and Robert E
Bruccoleri.

The module is implemented using a simple object oriented paradigm
where the object stores all the information needed for a calculation
along with a state variable, C<STATE>. The state variable has three
possible values, C<'setup'>, C<'calculating'> and C<'calculated'>. The
value of C<'setup'> indicates that the object is being setup with
data, and any results in the object are inconsistent with the data.
The value of C<'calculating'> indicates the object's computations are
in progress and tells the code not to delete intermediate files. This
object runs in parallel, and the object destruction code gets called
when each thread exits. Intermediate files must be protected at that
time.  The value of C<'calculated'> indicates that the object's
computational results are consistent with the data, and may be
returned to a calling program.

The C<'calculate'> method is used to update all the calculated values
from the input data. It checks the state variable first, and only does
the calculation if the state is C<'setup'>. Once the calculations are
complete, then the state variable is set to C<'calculated'>. Thus, the
C<calculate> method can be called whenever a calculated value is
needed, and there is no performance penalty.

The module initializes the C<Bio::SDRS> object with a state of
C<'setup'>. Any data input sets the state to C<'setup'>. Any requests
for calculated data, calls C<'calculate'>, which updates the state
variable so futures requests for calculated data return quickly.

B<N.B.> This module uses parallel programming via a fork call to get
high performance.  I<You must close all database connections prior to
calling the C<calculate> method, and reopen them afterwards. In
addition, you must ensure that any automated DESTROY methods take in
account their execution when the child processes terminated.>

=head1 METHODS

The following methods are provided:

=over 4

=cut


=item C<new()>

Creates a new Bio::SDRS object.

=cut

sub new {
    my $pkg;
    my $class = shift;
    eval {($pkg) = caller(0);};
    if ($class ne $pkg) {
	unshift @_, $class;
    }
    my $self = {};
    bless $self;
    $self->_init_data;
    $self->{MULTIPLE} = 1.18;
    $self->{LDOSE} = 0.17;
    $self->{HDOSE} = 30000;
    $self->{STEP} = 60;
    $self->{MAXPROC} = 2;
    $self->{TRIM} = 0.0;
    $self->{SIGNIFICANCE} = 0.05;
    $self->{DEBUG} = 0;
    $self->_init_tmp;
    
    return $self;
}

sub _init_data {
    my $self = shift;
    $self->{STATE} = "setup";
    $self->{DOSES} = [];
    $self->{RESPONSES} = {};
}

sub _init_tmp {
    my $self = shift;
    my $tmp = exists($ENV{TMPDIR}) ? $ENV{TMPDIR} : "/tmp";
    $tmp .= "/sdrs";
    if (exists($ENV{USER})) {
	$tmp .= "." . $ENV{USER};
    }
    $tmp .= "." . $$;
    $self->{TMPDIR} = $tmp;
    $self->{TMP_CREATED} = 0;
}

sub DESTROY {
    
    # There's an important multiprocessing issue to keep in mind here.
    # When this process forks, this method will be invoked for all the subprocesses.
    # Thus, we need to prevent the deletion of the temporary array until the
    # calculation is completed. That is why there is a check on the STATE.
    
    my $self = shift;
    if (not $self->{DEBUG} and
        $self->{TMP_CREATED} and
        $self->{STATE} eq 'calculated') {
	&_system_with_check("rm -rf " . $self->{TMPDIR},
			    $self->{DEBUG});
    }
}

# documentation for autoloaded methods goes here.

=item C<multiple([$multiple_value])>

Retrieves the current setting for the C<multiple> value, 
and optionally sets it. This value specifies the multiplicity factor