/ 
Bio-SDRS-0.11
River stage zero No dependents
/ Bio::SDRS

NAME

Bio::SDRS - Perl extension for Sigmoidal Dose Response Search, a tool for characterizing biological responses to compounds.

SYNOPSIS

  use Bio::SDRS;
  my $sdrs = new Bio::SDRS;

  $sdrs->doses(0.423377, 1.270132, 3.810395, 11.431184, 34.293553,
               102.880658, 308.641975, 925.925926, 2777.777778, 8333.333333,
               25000);
  $sdrs->set_assay('C8-BMS-208882',
	           1.885, 1.82, 2.2, 2.205, 2.78,
                   4.965, 9.21, 31.275, 74.445, 99.03,
                   100);
  $sdrs->calculate;
  foreach my $assay ($sdrs->assays) {
      print "$assay\n";
      foreach my $prop (('MAX', 'MIN', 'LOW', 'HIGH', 'EC50',
		         'PVALUE', 'EC50RANGE', 'PEAK', 'A', 'B',
		         'D', 'FOLD')) {
	  printf "  %s = %s\n", $prop, $sdrs->ec50data($assay, $prop);
      }
      print "\n";
  }

Constructor

$obj = new Bio::SDRS;

# You can also use $obj = Bio::SDRS->new();

Object Methods

Input Methods

$sdrs->multiple([$new_multiple]);
$sdrs->ldose([$new_ldose]);
$sdrs->hdose([$new_hdose]);
$sdrs->step([$new_step]);
$sdrs->maxproc([$new_maxproc]);
$sdrs->trim([$new_trim]);
$sdrs->significance([$new_significance]);
$sdrs->tmpdir([$new_tmpdir]);
$sdrs->debug([$new_debug]);
$sdrs->doses(doses...);
$sdrs->set_assay(assay, {response}...)

Output Methods

$sdrs->assays;
$sdrs->scandata;
$sdrs->score_doses;
$sdrs->sorted_assays_by_dose([$dose]);
$sdrs->pvalues_by_dose([$dose])
$sdrs->ec50data([$assay[, $property[, $precision]]]);

Other Methods

$sdrs->calculate;

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, STATE. The state variable has three possible values, 'setup', 'calculating' and 'calculated'. The value of 'setup' indicates that the object is being setup with data, and any results in the object are inconsistent with the data. The value of '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 'calculated' indicates that the object's computational results are consistent with the data, and may be returned to a calling program.

The '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 'setup'. Once the calculations are complete, then the state variable is set to 'calculated'. Thus, the calculate method can be called whenever a calculated value is needed, and there is no performance penalty.

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

N.B. This module uses parallel programming via a fork call to get high performance. You must close all database connections prior to calling the 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.

METHODS

The following methods are provided:

new()

Creates a new Bio::SDRS object.

multiple([$multiple_value])

Retrieves the current setting for the multiple value, and optionally sets it. This value specifies the multiplicity factor for increasing the dose in the search. It must be greater than one.

ldose([$ldose_value])

Retrieves the current setting for the ldose value, and optionally sets it. This value specifies the lowest dose in the search. It must be greater than zero.

hdose([$hdose_value])

Retrieves the current setting for the hdose value, and optionally sets it. This value specifies the highest dose in the search. It must be greater than the ldose value.

step([$step_value])

Retrieves the current setting for the step value, and optionally sets it. This value specifies the maximum change in doses in the search. In the search process, this module starts at the ldose value. It tries multiplying the current dose by the multiple value, but it will only increase the dose by no more than the step value specified here. It must be positive.

maxproc([$maxproc_value])

Retrieves the current setting for the maxproc value, and optionally sets it. This value specifies the maximum number of processes that can be used for the search. The upper limit is 64 and the lower limit is 1.

trim([$trim_value])

Retrieves the current setting for the trim value, and optionally sets it. This value specifies the trimming factor for the number of assays. If the trim is 0, then all assays will be used, and if 1, no assays will be used. It must be between 0 and 1.

significance([$significance_value])

Retrieves the current setting for the significance value, and optionally sets it. This value specifies the minimum permitted significance value for the F score cutoff. It must be between zero and 1.

tmpdir([$tmpdir_value])

Retrieves the current setting for the tmpdir value, and optionally sets it. This value specifies the temporary directory where scans of the dose calculation are written. The default is /tmp/sdrs.user.process_id.

debug([$debug_value])

Retrieves the current setting for the debug variable, and optionally sets it. This value specifies whether debugging information is printed and if the temporary directory (see above) is deleted after execution of this module.

doses($dose1, $dose2, ...)

Specify the list of compound doses used in the all the assays in the experiment. The doses must be in numerical order, from smallest to largest.

set_assay($assay_name, $response1, ...)

Adds an assay to the list to be searched over. Each response in the list corresponds to the doses specified in the doses method. The number must match, and they must be in numerical order, from smallest to largest.

assays()

Return the list of assay names;

calculate()

Perform the SDRS calculation.

scandata()

Return the complete list of scan data used in the SDRS calculation. This is just an array of lines containing the values of the EC50 calculations.

score_doses()

Return the list of doses used in the SDRS calculation that can be used as arguments for assays and pvalues.

sorted_assays_by_dose([$dose])

Return a list of assays for each dose in $dose sorted by F-score.

pvalues_by_dose([$dose])

Return a list of P values for the assays returned by sorted_assays_by_dose for each dose in $dose sorted by F-score.

ec50data([$assay[, $property[, $precision]]])

Returns EC50 data for the calculation. If no arguments are specified, then the internal hash for the EC50 calculation are returned. If just an $assay is specified, then the internal hash for all the EC50 values associated with that $assay is returned. If an $assay and $property are specified, then the property for that assay is returned. If the $precision operand is specified, then it controls how many digits of precision are returned for the value.

Here is the list of possible properties.

MAX         Maximum F score
MIN         Minimum F score. If this property is negative, then an error
            was encountered in the calculation of F scores. This is likely due
            insufficient range in the responses.
LOW         Lower bound of 95% confidence interval for the estimated EC50. 
HIGH        Upper bound of 95% confidence interval for the estimated EC50.
EC50        Estimated EC50.
PVALUE      P value of the best fitting model
EC50RANGE   range of 95% confidence interval for the estimated EC50.
PEAK        Number of peaks in the F scores at search doses across experimental dose range.
A           Estimated value for A in the best model.
B           Estimated value for B in the best model.
D           Estimated value for D in the best model.
FOLD        Ratio of B/A or 99999.0. If A == 0. Positive if D < 0, negative otherwise.

SEE ALSO

sdrs.pl

AUTHORS

Ruiru Ji <ruiruji@gmail.com>
Nathan O. Siemers <nathan.siemers@bms.com>
Lei Ming <lei.ming@bms.com>
Liang Schweizer <liang.schweizer@bms.com>
Robert Bruccoleri <bruc@acm.org>