NAME

Decision::Markov::State - Markov state object for Decision::Markov

SYNOPSIS

  use Decision::Markov::State;
  $state = new Decision::Markov::State("Name",<utility>);
  $state->Reset();
  $state->Name("Name");
  $name = $state->Name;
  $state->NumPatients(100);
  $num = $state->NumPatients;
  $utility = $state->Utility($cycle);
  $error = $state->AddTransition($newstate,$prob);
  $prob = $state->TransitionProb($newstate[,$cycle]);
  $total = $state->SumProbs([$cycle]);
  $boolean = $state->FinalState;
  $newstate = $state->NextState($cycle);
  $state->DistributeCohort($cycle);
  $state->UpdateCohort();

DESCRIPTION

This module implements a Markov state object used by Decision::Markov. It's not really intended to be used directly, but for completeness, its public methods are documented here.

METHODS

new

Creates a new Markov state object, given a name for the state and its utility. The utility may be specified either as a number or as a reference to a subroutine which will be called with the current model cycle as its only argument.

Reset

Resets the state, clearing temporary information that is stored in the state during model evaluations.

Name

With no argument, returns the name of the state. With an argument, sets the name of the state.

NumPatients

With no argument, returns the number of patients in the state. With an argument, sets the number of patients in the state.

Utility

Given the current model cycle, computes and returns the utility of being in the state during that cycle.

AddTransition

Given a second Markov state, and a transition probability, adds a transition from the first state to the second that will occur with probability equal to the transition probability at the model cycle. Probability can be specified as a number or a reference to a subroutine which will be called with the current model cycle as its only argument.

Returns undef if successful or an error message if unsuccessful (e.g., there's already a transition between those states.)

TransitionProb

Given a second Markov state, return the probability of transitioning from the first state to the second. May return either a number or a reference to a subroutine that can be called with the current model cycle to get the numerical probability. If TransitionProb is given a cycle number as its optional second argument, it will always return the probability during that cycle. If a state doesn't have a transition to the new state, this function returns 0.

SumProbs

Return the sum of all the transition probabilities from the state. If any of the probabilities are subroutine references, they are evaluated at the cycle given as an argument to SumProbs or at cycle 3 if SumProbs is called without arguments. This function is used to check that probabilities sum to 1.

FinalState

Returns 1 if the state is a final state: a state with no transitions to states other than itself. Otherwise, returns 0.

NextState

Given the model cycle, randomly determine and return the next state that a patient in this state will move to, based on the transition probabilities. Used in Monte Carlo evaluations.

DistributeCohort

Given the model cycle, distribute all of the patients in the state to other states in proportion to their transition probabilities. Note that a state usually transitions to itself as well, so some of the patients are distributed back to the same state. Distributed patients are held in a temporary attribute of the object so that all states can be distributed before calling UpdateCohort to actually set the new number of patients for each state. Used in cohort simulations.

UpdateCohort

Update the number of patients in this state from the temporary attribute created by DistributeCohort.

COPYRIGHT

Copyright (c) 1998 Alan Schwartz <alansz@uic.edu>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

REVISION HISTORY

0.01

March 1988 - Initial concept.