NAME

Medical::Growth::Base - Base class for measurement system

SYNOPSIS

  package My::Growth::Charts::Base;

  use Moo::Lax;  # Plain Moo considered harmful
  extends 'Medical::Growth::Base';

DESCRIPTION

Medical::Growth::Base is designed as an (optional) base on which to build measurement systems. It provides a set of basic tools for constructing parameter tables and handling z scores and percentiles.

IMPLEMENTING A MEASUREMENT SYSTEM

Fundamentally, a Medical::Growth-compatible measurement system is simply a class or hierarchy of classes that provide useful information about clinical measurements (typically relationship to norms), and provides a measure_class_for that "measure_class_for" in Medical::Growth can delegate to in order to identify an actual measurement class.

The top-level class for a measurement system must be named Medical::Growth::Name. However, it need not be a subclass of Medical::Growth; it will be identified via Module::Pluggable.

This top-level class must contain at least one function:

measure_class_for(%criteria)

This function should evaluate the elements of %criteria and return a "handle" that the caller can use to call the data methods the measurement system provides. For example, if you're implementing a set of norms for weight gain, your measure_class_for function might look in %criteria to determine the patient's age and sex, and return the appropriate class for the caller to get a percentile value by calling a value_to_pct method.

Each measurement system is free to determine which keys in %criteria to inspect, though it's considered friendly to see what existing systems use, and make compatible choices where you can. As one example, if this function in your class was called by delegation from "measure_class_for" in Medical::Growth, %criteria will contain a system element with your name; it may be helpful to know by what name you were called.

It's considered polite for a measurement system's measure_class_for to accept %criteria as either a hash reference or a list of key-value pairs.

UTILITY METHODS

Medical::Growth::Base provides one method to simplify embedding data in a measurement class's file:

read_data([$file])

Reads a list of values from a table, typically used by a measure class to set up parameters needed to generate results.

If called with no arguments, reads the content of the DATA filehandle in the invoking class. If $file is an open file handle, will read from that instead. If $file is any other value, it will be used as a file name, and that file will be opened for reading (and closed when finished).

Lines will be read up to the end of the file or until an __END__ line is encountered. Lines consisting of whitespace only or beginning with # are discarded. Otherwise, the contents of the line are split on whitespace and stored in an array reference.

If the DATA file handle was read implicitly (i.e. because no $file was provided), it is repositioned to its starting point. This trick insures that that it doesn't appear as an active handle in any future error messages because it was read here.

Returns a reference to an array that in turn contains the array references for each line containing data.

In many cases, it may be simpler to just embed data that a measurement class needs in a statically initialized data structure. But if you want to defer the cost of parsing data tables until the information is needed, or use an external configuration file, this method allows you to store data separately from code.

EXPORT

None.

DIAGNOSTICS

Any message produced by an included package.

Can't read file (F)

You passed a file name to "read_data", and the file couldn't be opened.

No measure_class_for() method found (F)

This is the result of calling Medical::Growth::Base::measure_class_for; you should override this message in your measurement system's top-level class.

BUGS AND CAVEATS

Are there, for certain, but have yet to be cataloged.

VERSION

version 1.00

AUTHOR

Charles Bailey <cbail@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2012-2014 Charles Bailey.

This software may be used under the terms of the Artistic License or the GNU General Public License, as the user prefers.

ACKNOWLEDGMENT

The code incorporated into this package was originally written with United States federal funding as part of research work done by the author at the Children's Hospital of Philadelphia.