STEPSTools

Rounding: Get Rounded Doses For Medication By Frequency

Table of Contents

Description

Calculates one or more exact ingredient doses based on the received patient weight, received dosing formula, and common frequencies for the specified medication known by STEPSTools. For each of these doses, the service compiles and scores a list of recommended formulations and rounded doses. The highest score reflects the rounded dose most recommended by STEPSTools for that frequency and calculated exact dose.

Example HTTP GET Message

Request

GET http://dev.pedstep.org/Rounding/GetRoundedDosesForMedByFrequency.aspx?_
  authToken=0c849415-5f3d-4005-af0e-fa631b893804&
  weightInKg=10.23&_
  ageInMonths=15&_
  dosingFormula=40%20mg/kg/day&_
  vocab=NDDF&_
  vocabId=003675&_
  medicationString=Amoxicillin HTTP/1.1
Host: www.pedstep.org

• Notice "%20" inserted in the value for the dosingFormula parameter. This is the HTTP equivalent of a space and is the required way to express a space when calling the service. If you send a request that contains some other encoding for a space, you may receive a "400 Bad Request" error from the web server. Optionally, you can omit the space entirely (ie. "40mg/kg/day") and the service should parse the dosingFormula correctly.
• Underscores in the above example are not actual characters which should be used in a real web service request. These are included only to indicate continuation of a single line.
• During development, you will use the STEPSTools test platform at dev.pedstep.org as shown above. When you are ready to go live, you will need to request that you account be upgraded to production level and use our production domain at www.pedstep.org. The test domain is designated for both STEPSTools and vendor testing so as to minimally affect production users. The production domain is reserved for production users and a more stable platform with less-frequent, managed changes to the STEPSTools codebase.
• Explanations of the input parameters and output values of the service are detailed in the following sections.

Response

Input Parameters

Output XML

If the service is able to take the provided input and run the STEPSTools rounding algorithm, it will return four sections of xml: Inputs, Log Information, Version Information, and Recommendations. The Recommendations section will contain a recommendation for each common frequency for the medication. Each recommendation is broken into three sections of XML: Givens, Ranges and Possible Doses. All of the above listed sections and sub-sections are described in more detail below. If the service encounters a problem, it will return an error message. For explanation of STEPSTools error messaging, please see our Error Messages documentation.

Inputs

The inputs section contains those values which were received by STEPSTools from your system or were assumed as inputs by the STEPSTools rounding algorithm. This is provided as feedback to help developers who are troubleshooting calls to the service. The xml is a series of "ServiceInput" nodes, one for each input that is either received or assumed. Each "ServiceInput" node has the following child nodes:

Log Information

STEPSTools includes the date, time, and unique identifier for each recommendation made by the rounding service.  This information will be critically important for both troubleshooting and analysis of usage data for the study. Tags in this section are as follows:

Version Information

STEPSTools includes the current version number and release date for troubleshooting purposes in the event that a certain release introduces problems for users of the service.  When reporting a problem to the STEPSTools technical team, it may be helpful to have this information.  Registered users of the service can view details of each release here.  Tags in this section are as follows:

Recommendations

The Recommendations section is the largest and most complex part of the STEPSTools Rounding service response. It is a collection of one or more recommendations corresponding to one or more commonly-used frequencies when administering the specified medication. Within each recommendation, there are three sub-sections: Givens, Ranges and Possible Doses.

Givens

STEPSTools takes the values provided to the service as inputs and derives one or more frequencies and calculated doses. These frequencies and calculated, exact doses are the basis for the rest of the recommendation. In other words, the rounded doses in the Possible Doses section are recommended as reflected by their scores GIVEN that the they will be administered at the frequency in this section.

Ranges

The Ranges section contains 4 sets of ranges. These are also provided as feedback for developers to make transparent how STEPSTools determined appropriate doses for the medication, patient weight and patient age which were specified.

Ranges: Absolute Range

STEPSTools uses recommendations in the pediatric literature to detemine an absolute range that a reasonable dose would fall within. The literature expresses most of these recommendations based on patient weight, age and, in many cases, frequency, so STEPSTools uses those inputs to help determine the absolute range for the patient weight, age and frequency specified. The absolute range section contains the following child nodes and values.

Ranges: Rounding Range

STEPSTools uses a body of research in our knowledge base to determine an appropriate rounding range for the medication specified. This is different than the absolute range. In some cases, it may be within the absolute range or overlap it. The rounding range section contains the following child nodes and values.

Ranges: Working Range

STEPSTools takes the absolute and rounding ranges to create a single range to work with for determining appropriate doses. The working range section contains the following child nodes and values.

Ranges: Possible Ranges List

STEPSTools takes the Working range and known formulations of the specified medication to calculate lay dose ranges for each formulation. For example, if STEPSTools determines that an individual calculated dose of 200 mg of Amoxicillin can be rounded up or down between 170 mg and 230 mg, for a 250 mg/5 mL formulation, STEPSTools will calculate a possible range of between 3.4 mL (equal to 170 mg) and 4.6 mL (equal to 230 mg). These ranges are uses to determine the possible doses in the final section.

Possible Doses

The answer from the system is contained in the Possible Doses section. Possible ranges from the previous section are used to determine reasonable formulations and doses. These doses are then scored to rank the best choices based on STEPSTools rounding algorithm. The Possible Doses section contains a message indicating whether the service was able to round the dose followed by a "PossibleDosesList" node containing the series of "PossibleLayDoseRange" nodes with the following values:

Practice Tool