# NAME

DoseMe::Algorithms - Some Abstract

# VERSION

version 0.0.1

# CONTENTS

## Plasma Concentration Plot

### adaptive_concentration_plot

#### Arguments

* $dm - the drug model
* $params - optional, hash with parameters

#### Parameters

parameter | default | description
---|---|---
t_start | 0 hours | start time to plot, defaults to beginning of course
t_end | t_{last_dose} + 24 hours | end time to plot, defaults to time of last non-zero dose + 24 hours
min_step | 1 minute | minimum time step
max_step | 6 hours | maximum time max_step
gamma | 0.8 | constant of gamma transfer function from slope to plot rate<br> values < 1 will results in less points in shallower parts of curve
relax | sqrt(2) | relaxation rate - instead of instantly switching from a high sampling rate to low sampling rate, value of 1.44 will make the next sampling step period at most 1.44 the previous sampling rate period, so that every two steps at most double the period (halve the rate)
aspect_ratio | 2 | intended plot aspect ratio, default of 2 is X:Y of 2:1, good for most plots in DoseMe
trim | _undef_ | set this to enable collinear point trimming
trim_threshold | 1e-3 | consider three points collinear if norms to two lines defined by these three points differ by at most *trim_threshold* value, in which case the innermost point is redundant and can be discarded
seekpeak | 1 | actively seek peak values even if they don't fall on a sampling point, peak of last plotted dose is always optimised
seekpeak_type | domain | _domain_ (time) or _range_ (concentration). Classical golden section search convergence criterion is to stop when section step is smaller than a specified threshold (see *seekpeak_precision*). Implemented version of golden section search also allows to specify convergence criterion that specifies desired precision on range (concentration) instead. Note that when _range_ is specified, convergence criterion is applied to both domain and range to ensure the algorithm converges.
seekpeak_precision | 1/3600 (1 second) | zero in on time of peak to within one second by default.
noseek_ndose_threshold | _undef_ | if defined, and number of doses being plotted is above this threshold, do not actively seek peak values (except for the last plotted dose). This helps speed things up when plotting a very large number of doses.
auto_scale_rates | _undef_ | if defined, then the algorithm will attempt to automatically set *max_step* and *min_step* depending on length of time being plotted and number of doses being plotted. supplied *min_step* and *max_step* will be ignored.

#### Returns

A hashref containing the following fields

field | description
---|---
graph | arrayref with pairs of x and y values that make up the graph
peaks | arrayref with pairs of c and t values that represend the peaks
troughs | arrayref with pairs of c and t values that represent the troughs
p | if debug level is set above 0 this contains a hashref with parameters used by the graphing algorithm
final_state | if debug level is set above 1 this contains a hashref with the final state of the graphing algorithm

#### Example

    my $retval = adaptive_concentration_plot($dm);

    my $graph = $retval->{graph};
    print "x\ty\n";
    for my $row (@{$graph}) {
      print $row->{x} . "\t" . $row->{y} . "\n";
    }

    print "peaks\n";
    print "xp\typ\n";
    for my $row (@{$retval->{peaks}}) {
      print $row->{t} . "\t" . $row->{c} . "\n";
    }

    print "troughs\n";
    print "xt\tyt\n";
    for my $row (@{$retval->{troughs}}) {
      print $row->{t} . "\t" . $row->{c} . "\n";
    }

## Golden Section Peak Search

### goldensectionpeak

#### Arguments

* $fn - function (taking a single variable and returning a scalar) to plots
* $min - left hand side of the interval to perform a peak search in
* $max - right hand side of the interval to perform a peak search in
* $params - optional, a hash with parameters

Golden section peak search makes several assumptions about the function over the search interval. They are:
* function is continuous over the interval
* function has at most one peak within the interval

#### Parameters

parameter | default | description
---|---|---
type | domain | _domain_ (time) or _range_ (concentration). Classical golden section search convergence criterion is to stop when section step is smaller than a specified threshold (see *seekpeak_precision*). Implemented version of golden section search also allows to specify convergence criterion that specifies desired precision on range (concentration) instead. Note that when _range_ is specified, convergence criterion is applied to both domain and range to ensure the algorithm converges.
precision | 1e-3 | If type of _domain_ is used, the algorithm converges when section size is reduced to below this value. If type of _range_ is used, the algorithm converges when section size is reduced to at least this value **and** changes in function in successive iterations are below this value.
xvarname | x | specify the name of x variable to use in graph output
yvarname | y | specify the name of y variable to use in graph output

#### Returns

A hashref containing the following fields

field | description
---|---
peak | a hash containing x and y value of the found peak
leading | an arrayref containing x and y values of points evaluated during peak search that precede the peak, sorted by x value
trailing | an arrayref containig x and y values of points evaluated during peak search that follow the peak, sorted by x value
start | search interval start
end | search interval end
precision | precision used during search
type | type of convergence criterion used during search

## Debugging

`$DoseMe::Algorithms::PlasmaConcentrationPlot::debug_level = 1;`

Outputs includes a hash with parameters used by graphing algorithm.

`$DoseMe::Algorithms::PlasmaConcentrationPlot::debug_level = 2;`

Outputs also includes a hash with the final state of the graphing algorithm.

## Building

```bash
cpanm Dist::Zilla
cpanm --mirror=https://darkpan.doseme.io --mirror=https://cpan.metacpan.org/ --mirror-only -v Dist::Zilla::PluginBundle::DoseMe~0.0.5
./Build realclean
perl Build.pl
./Build build
./Build install
```

## Testing

```bash
prove -blv
```

## Releasing

```bash
./Build realclean
dzil clean
dzil build
dzil test
dzil release
```

# AUTHOR

Paul Sabourenkov <paul.sabourenkov@doseme.com.au>

# COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by DoseMe Pty Ltd.  No
license is granted to other entities.
