Relative Standard Error - Data Control

The Relative Standard Error (RSE) plugin allows you to show RSE figures in SuperWEB2 for weighted datasets.

Relative Standard Error Module

SuperSERVER is supplied with a Data Control plugin called rsecalculationmodule. This plugin calculates RSE values for display in SuperWEB2.

The RSE calculation is performed only on non empty cells that have associated Main and Replicate weights.

Module Properties

The rsecalculationmodule plugin has a number of properties you can configure.

PropertyDescription
Formula

The formula used to calculate the RSE:

FormulaDescription
jackknife

The jackknife variance estimator is given by:

Where G is the total number of replicate weights and repg=gth

This is the default formula.

bootstrap

The bootstrap variance estimator is given by:

The following formula is used to obtain the value of the bootstrap estimate, given the jackknife:

 RSE values are supposed to be in the range of 0 and 1. However, these formulas do not guarantee that calculated RSE values are always in the range of 0 and 1. Calculated values may be greater than 1 in some cases.

UnreliableRseThreshold

The RSE calculation module calculates the table reliability based on the portion of unreliable cells exceeding a defined threshold.

Use this property to set the unreliable RSE threshold. Any cell with an RSE value greater than or equal to this threshold is considered unreliable.

The table reliability calculation always excludes empty cells (cells with no contributors).

UnreliableTableThreshold

A percentage value.

When the percentage of unreliable cells and total non-empty cells is greater than or equal to this percentage, the table results are considered unreliable.

Message
A configurable message that will be displayed to the user in the client when the table results are considered unreliable. The message is a warning only (end users can still view numeric results).

Apply the Plugin to a Dataset

  1. Login to SuperADMIN and create a new mandatory method (the ID and display name can be whatever you choose; in this example the method is called "rse"):

    > method addmethod rse mandatory rse
  2. Add the Data Control plugin to the method:

    > method rse adddcplugin rsecalculationmodule rsecalculationmodule 1
  3. Set the plugin properties. For example:

    > method rse rsecalculationmodule addproperty Message "Table is not reliable"
    > method rse rsecalculationmodule addproperty UnreliableRseThreshold "0.25"
    > method rse rsecalculationmodule addproperty UnreliableTableThreshold "2%"
    > method rse rsecalculationmodule addproperty Formula "jackknife"

    In this case we have set the thresholds to 0.25 and 2% and selected the jackknife formula. The message "Table is not reliable" will be displayed if the table fails the reliability tests.

  4. Assign the method to a dataset (in this example we are assigning the method to a dataset with the ID weightedsurvey2013:

    > cat weightedsurvey2013 addmethod rse

    You can review the method details using the command cat <dataset_id> methods details <method_id>:

    > cat weightedsurvey2013 methods details rse
    [ Method : rse (id:rse) (type:mandatory) ]
        [ Common ]
        [ DCPlugin : rsecalculationmodule (id:rsecalculationmodule) (priority:1) ]
            [ Message : Table is not reliable ]
            [ UnreliableRseThreshold : 0.25 ]
            [ UnreliableTableThreshold : 2% ]
            [ Formula : jackknife ]

RSE Annotation Module

SuperSERVER is also supplied with a Data Control plugin called rseannotationmodule. This plugin provides annotations for RSE values.

There are several components/factors that SuperSERVER uses to work out which annotations to display:

  • The absolute RSE value of the cell.
  • A lookup table, which defines a series of RSE values and the corresponding annotations.
  • A lookup operator, which defines how to select from the set of annotations in the lookup table.
  • The static annotation repository, which defines the text that will be displayed in the annotation footnote.

The Lookup Table and Module Properties

The rseannotationmodule plugin has two properties that you must configure.

PropertyDescription
LookupTableA text file on disk that defines a lookup table containing a list of values and corresponding annotations.
LookupOperator

One of the following operators to indicate how to select an annotation from the lookup table: >>=<, or <=

For example, suppose the lookup table contains the following values:

1.00 ****
0.75 ***
0.50 **
0.25 *

The annotations will be applied as follows:

If the Lookup Operator is...If the RSE Value is..The Annotation will be...
>
Greater than 1.00****
Greater than 0.75***
Greater than 0.50**
Greater than 0.25*
>=
Greater than or equal to 1.00****
Greater than or equal to 0.75***
Greater than or equal to 0.50**
Greater than or equal to 0.25*
<
Less than 1.00****
Less than 0.75***
Less than 0.50**
Less than 0.25*
<=
Less than or equal to 1.00****
Less than or equal to 0.75***
Less than or equal to 0.50**
Less than or equal to 0.25*

Static Annotation Repository

In addition to creating the lookup table you must also create a static annotation repository that contains the text for each annotation. See Annotations - SuperSERVER for full details on creating an annotation repository.

Static annotations are stored in a SQLite database file. This must be saved to the same directory as the SXV4 file it relates to, with the filename <database_filename>.sxv4.sqlite.db.

The annotation repository must contain an entry in the AnnotationDetails table for each AnnotationSymbol that is specified in the lookup table, with the corresponding annotation text in the AnnotationDetails column (in the above example, the symbols are ******, and ****).

Apply the Plugin to a Dataset

Once you have created your lookup table and static annotation repository, you can apply the RSE annotation module to your dataset:

  1. Login to SuperADMIN and create a new method:

    > method addmethod rse-annotation
  2. Add the Data Control plugin to the method:

    > method rse-annotation adddcplugin rse-annotation-module rseannotationmodule 1
  3. Set the plugin properties:

    > method rse-annotation rse-annotation-module addproperty LookupTable "lookup_table.txt"
    > method rse-annotation rse-annotation-module addproperty LookupOperator ">"

    You can specify the lookup table file name using either an absolute path or a path relative to the location of the plugin. You must escape any Windows style directory separators (\) in the path with a backslash.

    For example:

    > method rse-annotation rse-annotation-module addproperty LookupTable "C:\\database\\config\\lookup_table.txt"
  4. Assign the method to a dataset (in this example we are assigning the method to a dataset with the ID weightedsurvey2013:

    > cat weightedsurvey2013 addmethod rse-annotation

    You can review the method details using the command cat <dataset_id> methods details <method_id>:

    > cat weightedsurvey2013 methods details rse-annotation
    [ Method : rse-annotation (id:rse-annotation) (type:mandatory) ]
        [ Common ]
        [ DCPlugin : rseannotationmodule (id:rse-annotation-module) (priority:1) ]
            [ LookupTable : lookup_table.txt ]
            [ LookupOperator : > ]

Make sure that you have saved the lookup table to the appropriate location and that your annotations file is in the same location as the SXV4.