ezfit:solutions_guide:xml_format_and_parameters [Audina Documentation]

This is an old revision of the document!

Solutions Guide: XML Format and Parameters

The Fitting Guide file (data\fittingguide.xml) provides an automated way to adjust parameters based on proven adjustment settings, thus saving a lot of time, and getting consistent results. These settings are stored in an XML format, so that it can be easily adjusted or edited if necessary. Each file can contain several products (circuits) and their respective settings. Following are the different formats to express the different settings providing the information that the software uses for fitting hearing instruments.

Basic Structure

Sample File Structure: <table border="1" cellpadding="1" cellspacing="0" width="700" class="inline"> <tbody><tr> <th>Sample File Structure</th> </tr> <tr> <td><?xml version="1.0" encoding="UTF-8"?> <PROJECT>    <CIRCUIT Code="circuitcode" Title="Instrument Model: intrument model">       <ISSUES Title="Subtitle 1">         <ISSUE Title="Subtitle A of Subtitle 1 ">            <ADJUSTMENTS Code="circuitcode Adjustments Set I">              <ADJUSTMENT Row="0" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>         <ISSUE Title="Subtitle B of Subtitle 1 ">            <ADJUSTMENTS Code="circuitcode Adjustments Set II">              <ADJUSTMENT Row="1" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>       <ISSUES Title="Subtitle 2">         <ISSUE Title="Subtitle A of Subtitle 2">            <ADJUSTMENTS Code="circuitcode Adjustments Set III">              <ADJUSTMENT Row="0" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>    </CIRCUIT> </PROJECT></td> </tr> </tbody></table>

Element Descriptions and Attributes

<table width="100%" border="1" cellpadding="1" cellspacing="0" class="inline"> <tr> <th width="24%">Element</th> <th width="21%">Attribute</th> <th width="55%">Description</th> </tr> <tr valign="top"> <td><PROJECT>...</PROJECT></td> <td> </td> <td>Container for all circuits. It is the main file definition, the parent container for all elements.</td> </tr> <tr valign="top"> <td><CIRCUIT>...</CIRCUIT></td> <td> </td> <td>Container for a circuit definition, the parent container for <ISSUES> and/or <ISSUE> elements. </td> </tr> <tr valign="top"> <td> </td> <td>Code="CircuitCode" </td> <td>Code of circuit. This identifies and differentiates adjustments that might have the same name.</td> </tr> <tr valign="top"> <td> </td> <td>Title="InstrumentModel"</td> <td>Name or title (to be displayed) for the circuit </td> </tr> <tr valign="top"> <td><ISSUES>...</ISSUES></td> <td> Title="subtitle"</td> <td>Container for several issues. Required only if defining 2 or more issues. For a single issue, simply use element <ISSUE> directly, without defining it within <ISSUES>...</ISSUES> elements.</td> </tr> <tr valign="top"> <td><ISSUE>...</ISSUE></td> <td> Title="subtitle"</td> <td>Container for a single issue, which contains one or more adjustments. Title displays a description of the issue.</td> </tr> <tr valign="top"> <td><ADJUSTMENTS>...</ADJUSTMENTS> </td> <td>Code="CircuitCode AdjName"</td> <td>Container for serveral adjustments. CircuitCode must the the same code defined in <CIRCUIT>. AjdName can be any string that best describes the adjustment.</td> </tr> <tr valign="top"> <td><ADJUSTMENT>... </ADJUSTMENT> </td> <td> </td> <td>Container for a single adjustment, which could contains zero or more <STEP> elements. </td> </tr> <tr valign="top"> <td> </td> <td> Row="RowNumber" </td> <td>Row (order) where to display it. Row numbering starts with 0. Eg: Row="0"</td> </tr> <tr valign="top"> <td> </td> <td>Action="val" </td> <td>val can be one of these: <table width="85%" border="1" align="center" cellpadding="1" cellspacing="0"> <tr valign="top" bgcolor="#FFFFFF"> <td width="8%">Y</td> <td width="92%">Take action. Eg: <ADJUSTMENT Row="1" Action="Y" Title="Set Gain">..</ADJUSTMENT></td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>N</td> <td>Take No action. Use this to simply display the specified title (with no action associated with it). Eg: <ADJUSTMENT Row="3" Action="N" Title="TIPS"/></td> </tr> </table> </td> </tr> <tr valign="top"> <td> </td> <td>Title="Action Description" </td> <td>Title to display in row.</td> </tr> <tr valign="top"> <td> <STEP/> </td> <td>  </td> <td>Container for a single step in an adjustment.</td> </tr> <tr valign="top"> <td> </td> <td>Action="val"</td> <td>val can be one of these: <table width="85%" border="1" align="center" cellpadding="1" cellspacing="0"> <tr valign="top" bgcolor="#FFFFFF"> <td width="8%">I</td> <td width="92%">Increase.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>D</td> <td>Decrease.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>EI</td> <td>Equation Increase.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>ED</td> <td>Equation Decrease.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>S</td> <td>Set a single value. Use with Value parameter.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>RI</td> <td> Range Increase.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>RD</td> <td> Range Decrease.</td> </tr> <tr valign="top" bgcolor="#FFFFFF"> <td>RS</td> <td> Range Set. Use with SetValues parameter.</td> </tr> </table></td> </tr> <tr valign="top"> <td> </td> <td> IncBy="numval"</td> <td>numval can be a positive or negative integer.</td> </tr> <tr valign="top"> <td> </td> <td>SetValues="[x1,x2,x3,...,xN]"</td> <td>Set Range values. Use with Action="RS". Eg: SetValues="[5600,4500,4000]"</td> </tr> <tr valign="top"> <td> </td> <td>Value="val"</td> <td>Set a single value. Use with Action="S". Eg: Value="Dynamic"</td> </tr> <tr valign="top"> <td> </td> <td>GT="param2"</td> <td>Greater Than. If param1 > param2, perform Action. param1 would be the value of parameter ParamName specified in attribute Param. Use in conjunction with EQU attribute. Eg: <STEP Action="ED" IncBy="-2" GT="LTH4" EQU="UTH4[GTE]LTH4" Param="UTH4"/></td> </tr> <tr valign="top"> <td> </td> <td>LT="param2"</td> <td>Lesser Than. If param1 < param2, perform Action. param1 would be the value of parameter ParamName specified in attribute Param. Use in conjunction with EQU attribute. Eg: <STEP Action="ED" IncBy="-2" LT="max" EQU="min[LT]max" Param="min"/></td> </tr> <tr valign="top"> <td> </td> <td>EQ="param2"</td> <td>Equal To. If param1 >= param2, perform Action. param1 would be the value of parameter ParamName specified in attribute Param. Use in conjunction with EQU attribute.</td> </tr> <tr valign="top"> <td> </td> <td>GTE="param2"</td> <td>Greater Than or Equal To. If param1 >= param2, perform Action. param1 would be the value of parameter ParamName specified in attribute Param. Use in conjunction with EQU attribute. Eg: <STEP Action="ED" IncBy="-2" GTE="LTH4" EQU="UTH4[GTE]LTH4" Param="UTH4"/></td> </tr> <tr valign="top"> <td> </td> <td>LTE="param2"</td> <td>Less Than or Equal To. If param1 <= param2, perform Action. param1 would be the value of parameter ParamName specified in attribute Param. Use in conjunction with EQU attribute. Eg: <STEP Action="ED" IncBy="-2" LTE="max" EQU="min[LTE]max" Param="min"/> </td> </tr> <tr valign="top"> <td> </td> <td>PEQU="ProposedEquation"</td> <td> Proposed Equation. The Proposed value uses the new value of the current parameter Param to calculate the equation. In other words, perform Action, evaluate equation, and if it is True, permanently store the results of performed Action. Eg: <STEP Action="EI" IncBy="1" PEQU="SquelchTh[LT]50" Param="SquelchTh"/></td> </tr> <tr valign="top"> <td> </td> <td>EQU="equation"</td> <td>Equation. Perform Action if equation is True. Eg: EQU="UTH3-LTH3[GT]LLGAIN3-HLGAIN3" Comparison Operators inside of defined equations: [GTE]=Greater Than and Equal To [LTE]=Lesser Than and Equal To [EQ]=Equal To [GT]=Greater Than [LT]=Lesser Than </td> </tr> <tr valign="top"> <td> </td> <td> Param="ParamName"</td> <td>ParamName is a parameter name supported by the circuit. Eg: HFC, LFC, TK </td> </tr> </table>

How to Define Sections

Element Name: <CIRCUIT …>…</CIRCUIT>

Parameters to be used:

Code: Name (code) of the product.
Title: Title (full name) of the product.

Requirements:

Must contain at least one Issue.

Example file fittingguide.xml:

<table border="1" cellpadding="1" cellspacing="0" width="700" class="inline"> <tbody><tr> <th>fittingguide.xml</th> </tr> <tr> <td><tt><CIRCUIT Code="FOUNDATION" Title="FOUNDATION">   <ISSUE Title="FEEDBACK">     <ADJUSTMENTS Code="FOUNDATION FEEDBACK (Constant)">     <ADJUSTMENT Row="0" Action="Y" Title="Set Notch Center to 3000 Hz." >       <STEP Action="S" Value="3000" Param="NotchCenter"></STEP>     </ADJUSTMENT>     <ADJUSTMENT Row="1" Action="Y" Title="Move High Cut to the left." >       <STEP Action="D" IncBy="-2" Param="HighCut"></STEP>     </ADJUSTMENT>   </ISSUE> </CIRCUIT</tt><tt>></tt><tt> </tt> </td> </tr> </tbody></table>

Define an Issue

Element Name: <ISSUES …><ISSUE…>…</ISSUE></ISSUES>

Use <ISSUES>…</ISSUES> when there are several issues (or sub-issues) under the same issue. Otherwise, it is not used, and <ISSUE>..</ISSUE> is used directly.

Parameters to be used:

Title: Title (full name) of the issues category to display.

Requirements:

Must belong to a Circuit.
Must contain at least one Adjustment.

Example fittingguide.xml file: <table border="1" cellpadding="1" cellspacing="0" width="700" class="inline"> <tbody><tr> <th>fittingguide.xml</th> </tr> <tr> <td><tt><CIRCUIT Code="FOUNDATION" Title="FOUNDATION"> </tt><tt>  <ISSUES Title="Feedback">     <ISSUE Title="Feedback (Constant)">       <ADJUSTMENTS Code="FOUNDATION Feedback (Constant)">         <ADJUSTMENT Row="0" Action="Y" Title="Set Notch Center to 3000 Hz." >           <STEP Action="S" Value="3000" Param="NotchCenter"></STEP>         </ADJUSTMENT>         <ADJUSTMENT Row="1" Action="Y" Title="Move High Cut to the left." >           <STEP Action="D" IncBy="-2" Param="HighCut"></STEP>         </ADJUSTMENT> </tt><tt></tt><tt>      </ADJUSTMENTS> </tt><tt>    </ISSUE>   </ISSUES> </CIRCUIT></tt> </td> </tr> </tbody></table>

Define an Adjustment

Element Name: <ADJUSTMENTS…><ADJUSTMENT…>…</ADJUSTMENT></ADJUSTMENTS>

Parameters to be used:

ADJUSTMENTS (plural) Code: Code string for a category of Adjustments, rather than a single adjustment. It cannot have other adjustment parameters. Note: This code string is composed of CircuitCode + IssueTitle, and it is case sensitive. For example: if the Circuit Code is “P2” (case sensitive), and the Issue Title is “Feedback” (case sensitive), then the Adjustments Code would be “P2 Feedback”. See the code:<table border="1" cellpadding="1" cellspacing="0" width="600" class="inline"> <tbody><tr> <td><tt><CIRCUIT Code="P2" Title="Paragon 2"> <ISSUE Title="Feedback"> <ADJUSTMENTS Code="P2 Feedback"> ...some adjustments here... </ADJUSTMENTS> </ISSUE> </CIRCUIT></tt></td> </tr> </tbody></table>
ADJUSTMENT (singular) Row: row number in which it will be displayed. Each adjustment must start with row 0.
ADJUSTMENT (singular) Action: One of the following:
- Y: Yes, it performs an action. If Action=Y, then the adjustment must contain at least one Step.
- N: No, it does not perform an action. If Action=N, then there are no Steps included with the adjustment, since there is no action to perform.
ADJUSTMENT (singular) Title: Title or name to display for the adjustement.

Requirements:

Must belong to an Issue, or in the case of a sub-Adjustment, must belong to an Adjustment.
May contain none, one or many Steps, depending on the parameters.
In the case of a super-adjustment, it must contain at least one sub-Adjustment.

Example fittingguide.xml file: <table border="1" cellpadding="1" cellspacing="0" width="100%" class="inline"> <tbody><tr> <th>fittingguide.xml</th> </tr> <tr> <td><tt><CIRCUIT Code="P2" Title="Paragon 2"> <ISSUE Title="Loud Sounds Uncomfortable">   <ADJUSTMENTS Code="P2 Loud Sounds Uncomfortable">     <ADJUSTMENT Row="0" Action="Y" Title="Reduce overall MPO">       <STEP Action="D" IncBy="-2" Param="AGCO"></STEP>     </ADJUSTMENT>     <ADJUSTMENT Row="1" Action="Y" Title="Reduce Loud TK,Increase Soft TK in all Channels" >       <STEP Action="ED" IncBy="-2" GTE="LTH1" EQU="UTH1-LTH1[GT]LLGAIN1-HLGAIN1" Param="UTH1"></STEP>       <STEP Action="ED" IncBy="-2" GTE="LTH2" EQU="UTH2-LTH2[GT]LLGAIN2-HLGAIN2" Param="UTH2"></STEP>       <STEP Action="EI" IncBy="1" LTE="UTH1" EQU="UTH1-LTH1[GT]LLGAIN1-HLGAIN1" Param="LTH1"></STEP>       <STEP Action="EI" IncBy="1" LTE="UTH2" EQU="UTH2-LTH2[GT]LLGAIN2-HLGAIN2" Param="LTH2"></STEP>     </ADJUSTMENT>     <ADJUSTMENT Row="2" Action="N" Title=""></ADJUSTMENT>     <ADJUSTMENT Row="3" Action="N" Title="TIPS"></ADJUSTMENT>     <ADJUSTMENT Row="4" Action="N" Title="These solutions apply only to loud sounds."></ADJUSTMENT>     <ADJUSTMENT Row="5" Action="N" Title="Please see solutions for (overall too loud) if necessary."></ADJUSTMENT>   </ADJUSTMENTS> </ISSUE> </CIRCUIT> </tt></td> </tr> </tbody></table>

Define a Step

Element Name: <STEP…>…</STEP>

Parameters to be used:

Action:
- I: Increase
- D: Decrease
- S: Set
- EI: Equation Increase
- ED: Equation Decrease
- RI: Range Increase
- RD: Range Decrease
- RS: Range Set

EQU: Equation to use. Used in conjunction with Action=EI or ED. Example:

      <STEP Action="EI" IncBy="1" LTE="UTH1" EQU="UTH1-LTH1[GT]LLGAIN1-HLGAIN1" Param="LTH1"></STEP>

GTE: “Grater Than or Equal To” the “Param” value in instrument. Example:

      <STEP Action="ED" IncBy="-2" GTE="LTH2" EQU="UTH2-LTH2[GT]LLGAIN2-HLGAIN2" Param="UTH2"></STEP>

LTE: “Less Than or Equal To” the “Param” value in instrument. Example:

      <STEP Action="EI" IncBy="1" LTE="UTH1" EQU="UTH1-LTH1[GT]LLGAIN1-HLGAIN1" Param="LTH1"></STEP>

IncBy: a positive integer to denote increase, a negative integeer to denote decrease. Used in conjunction with Action=I or D. Example:

      <STEP Action="D" IncBy="-2" Param="band9"></STEP>
      <STEP Action="I" IncBy="2" Param="ExternalVC,WidebandGain;VC"></STEP>

SetValues: set multiple values. Used in conjunction with Action=RS. Example:

      <STEP Action="RS" SetValues="[5600,4500,4000]" Param="HighCut"></STEP>

PEQU: Proposed equation setting. Use in conjunction with Action=EI. Example:

      <STEP Action="EI" IncBy="1" PEQU="SquelchTh[LT]50" Param="SquelchTh"></STEP>

Value: a value to set in the specified parameter. Used in conjunction with Action=S.

Param: instrument parameter to be affected. Note: this is case sensitive. Example:

      <STEP Action="I" IncBy="2" Param="ExternalVC,WidebandGain;VC"></STEP>

Example fittingguide.xml file: Example: <table border="1" cellpadding="1" cellspacing="0" width="100%" class="inline"> <tbody><tr> <th>fittingguide.xml</th> </tr> <tr> <td><tt><ISSUE Title="OVERALL TOO LOUD">   <ADJUSTMENTS Code="P2 OVERALL TOO LOUD">     <ADJUSTMENT Row="0" Action="Y" Title="Reduce overall gain/volume control" >       <STEP Action="D" IncBy="-1" Param="ExternalVC,WidebandGain;VC"></STEP>     </ADJUSTMENT>     <ADJUSTMENT Row="1" Action="Y" Title="Reduce Loud Gain in all channels">       <STEP Action="ED" IncBy="-2" EQU="UTH1-LTH1[GT]LLGAIN1-HLGAIN1" Param="HLGAIN1"></STEP>       <STEP Action="ED" IncBy="-2" EQU="UTH2-LTH2[GT]LLGAIN2-HLGAIN2" Param="HLGAIN2"></STEP>     </ADJUSTMENT>   </ADJUSTMENTS> </ISSUE> </tt></td> </tr> </tbody></table>

Conditional Values based on Immediate IF (aka. inline IF)

Param can contain a result derived from an immediate IF. This allows more flexibility in handling parameters.

Format: Param=“expression1, expression2; expression3”

If expression1 is true, then use value from expression2, else use value from expression3.

Example: <tt><STEP Action="D" IncBy="-1" Param="ExternalVC,WidebandGain;VC"></STEP></tt>

ezFIT 5.x Platform

Add support for localization. For example:

<table border="1" cellpadding="1" cellspacing="0" width="700" class="inline"> <tbody><tr> <th>Sample File Structure in ezFIT 5.x</th> </tr> <tr> <td><?xml version="1.0" encoding="UTF-8"?> <PROJECT>    <CIRCUIT Code="circuitcode" Title="Instrument Model: intrument model">       <ISSUES Title="Subtitle 1">         <ISSUE Title="Subtitle A of Subtitle 1 ">            <ADJUSTMENTS Code="circuitcode Adjustments Set I">              <ADJUSTMENT Row="0" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>         <ISSUE Title="Subtitle B of Subtitle 1 ">            <ADJUSTMENTS Code="circuitcode Adjustments Set II">              <ADJUSTMENT Row="1" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>       <ISSUES Title="Subtitle 2">         <ISSUE Title="Subtitle A of Subtitle 2">            <ADJUSTMENTS Code="circuitcode Adjustments Set III">              <ADJUSTMENT Row="0" Action="Y" Title="Action Description" >            </ADJUSTMENTS>         </ISSUE>       </ISSUES>    </CIRCUIT> </PROJECT></td> </tr> </tbody></table>

<table border="1" cellpadding="1" cellspacing="0" width="700" class="inline"> <tbody><tr> <th>Sample File Structure in ezFIT 5.x</th> </tr> <tr> <td> <pre> <code><?xml version="1.0" encoding="UTF-8"?> <PROJECT> <languages> <lang id="en" name="English (US)">English</lang> <lang id="fr" name="French">Français</lang> <lang id="pt" name="Portuguese">Português</lang> <lang id="es" name="Spanish">Español</lang> <lang id="da" name="Danish">Dansk</lang> <lang id="tr" name="Turkish">Türkçe</lang> <lang id="ru" name="Russian">??????</lang> <lang id="cn" name="Chinese (Mandarin)">??</lang> </languages> <CIRCUIT Code="circuitcode" Title="Instrument Model: intrument model"> <native>Instrument Model: intrument model</native> <lang id="es">Modelo de Audífono: Model de Audífono</lang> <ISSUES Title="Subtitle 1"> <native>Subtitle 1</native> <lang id="es">Subtítulo 1</lang> <ISSUE Title="Subtitle A of Subtitle 1"> <native>Subtitle A of Subtitle 1</native> <lang id="es">Subtítulo A de Subtítulo 1</lang> <ADJUSTMENTS Code="circuitcode Adjustments Set I"> <native>Adjustments Set I</native> <lang id="es">Ajuste Conjunto I</lang> <ADJUSTMENT Row="0" Action="Y" Title="Action Description" > <native>Action Description</native> <lang id="es">Descripción de Accción</lang> </ADJUSTMENTS> </ISSUE> </ISSUES> <ISSUE Title="Subtitle B of Subtitle 1 "> <ADJUSTMENTS Code="circuitcode Adjustments Set II"> <ADJUSTMENT Row="1" Action="Y" Title="Action Description" > </ADJUSTMENTS> </ISSUE> </ISSUES> <ISSUES Title="Subtitle 2"> <ISSUE Title="Subtitle A of Subtitle 2"> <ADJUSTMENTS Code="circuitcode Adjustments Set III"> <ADJUSTMENT Row="0" Action="Y" Title="Action Description" > </ADJUSTMENTS> </ISSUE> </ISSUES> </CIRCUIT> </PROJECT> </code></pre> </td></tr></table>

Modify behavior for Decrease (D) operator.