*! version 1.3.74 29Apr2018
help mat2do (Stas Kolenikov's webpage)

Title

ipfraking_report -- Reports on raked weights

Syntax

ipfraking_report using report_file, raked_weight(weight_variable) [options]

matrices(matrix_list) list of control total matrices to provide summaries for

by(varlist) variables to break down summaries by

force list a variable more than once

replace overwrite the existing file(s)

xls export the resulting report to an Excel file, see export excel

Description

ipfraking_report produces a detailed report and summaries of raked weights
produced previously by ipfraking.
The results are placed into report_file.dta (and, if xls option is specified,
also to report_file.xls).

Along the way, ipfraking_report runs a regression of the log raking ratio
on the calibration variables. This regression is expected to have R^2 very close to 1,
and the regression coefficients provide insights regarding which categories received
greater vs. smaller adjustments.

Structure of the report

Each line of the report corresponds to one of the categories of a control total variable,
and would contain information on what that control total category is, unweighted counts,
totals, proportions; totals and proportions with the source and the raked weights;
and descriptive statistcs of source weights, raked weights, and raking ratios.
ipfraking_report picks up the weighting margins from meta-information stored
by the meta option of ipfraking command that was used
to generate raked weights; see ipfraking.

ipfraking_report produces the following variables.

Variable name Definition

Weight_Variable The name of the weight variable, generate()

C_Total_Margin_Variable_Name The name of the control margin,
rowname of the corresponding ctotal() matrix

C_Total_Margin_Variable_Label The label of the control margin variable

Variable_Class The role of the variable in the report:

Raking margin: a variable used as a calibration margin
(picked up automatically from the ctotal() matrix, provided meta option was specified)

Other known target: supplied with matrices() option of ipfraking_report

Auxiliary variable: additional variable supplied with by() option of ipfraking_report

C_Total_Arg_Variable_Name The name of the multiplier variable

C_Total_Arg_Variable_Label The label of the multiplier variable

C_Total_Margin_Category_Number Numeric value of the control total category

C_Total_Margin_Category_Label Label of the control total category

Category_Total_Target The control total to be calibrated to (the specific entry in the ctotal() matrix)

Category_Total_Prop Control total proportion
(the ratio of the specific entry in the ctotal()
matrix to the matrix total)

Unweighted_Count Number of sample observations in the category

Unweighted_Prop Unweighted proportion

Unweighted_Prop_Discrep Difference Unweighted_Prop - Category_Total_Prop

Category_Total_SRCWGT Weighted category total, with source weight

Category_Prop_SRCWGT Weighted category proportion, with source weight

Category_Total_Discrep_SRCWGT Difference Category_Total_SRCWGT
- Category_Total_Target

Category_Prop_Discrep_SRCWGT Difference Category_Prop_SRCWGT
- Category_Total_Prop

Category_RelDiff_SRCWGT reldif(Category_Total_SRCWGT,
Category_Total_Target)

Overall_Total_SRCWGT Sum of source weights

Category_Total_RKDWGT Weighted category total, with calibrated weight

Category_Prop_RKDWGT Weighted category proportion, with calibrated weight

Category_Total_Discrep_RKDWGT Difference Category_Total_RKDWGT
- Category_Total_Target

Category_Prop_Discrep_RKDWGT Difference Category_Prop_RKDWGT
- Category_Total_Prop

Category_RelDiff_RKDWGT reldif(Category_Total_RKDWGT,
Category_Total_Target)

Overall_Total_RKDWGT Sum of calibrated weights

Source The name of the matrix from which the totals were obtained

Comment Placeholder for comments, to be entered during manual review

For each of the input weights (SRCWGT suffix), raked weights (RKDWGT suffix) and raking ratio
(the ratio of raked and input weights, RKDRATIO suffix), the following summaries are provided.

Variable name Definition

Min_WEIGHT Min of the weights

P25_WEIGHT 25th percentile of the weights

P50_WEIGHT Median of the weights

P75_WEIGHT 75th percentile of the weights

Max_WEIGHT Max of the weights

Mean_WEIGHT Mean of the weights

SD_WEIGHT Standard deviation of the weights

DEFF_WEIGHT Apparent UWE DEFF of the weights

Options

Rows of the report

by(varlist) requests a breakdown of the sample and weight summaries by categories
of the variables specified in this option.

matrices(matrix_name [matrix_name ...]) provides a list of known control totals.

ipfraking_report will pick up the raking variables and their categories.
Each matrix is expected to be compatible with the matrices consumed by ipfraking
as control totals, ctotal() option.
While the functionality of producing results by different variables is provided with
by() option, passing the known control totals with matrices() allows comparing
the required vs. achieved control totals.
See ipfraking Remarks and ipfraking Examples.

force requests that ipfraking_report provides summaries of weights
for a given variable each time it is encountered.

The multiple opportunities include:
being one of the raking margins picked up from the control totals saved by
ipfraking, meta; supplied with by() option; and supplied with matrices() option.
The reasons to include a variable multiple times in these options is to see how the weights
perform depending on whether a variable with known control totals is included or not
as a raking margin.

Files

replace overwrite the existing file(s)

xls export the report as an Excel file, see export excel.

Example

A variation of the following example was given in ipfraking:

. webuse nhanes2, clear

. * setting up the totals

. generate byte _one = 1

. svy: total _one, over(sex, nolab)

. matrix total_sex = e(b)

. matrix rownames total_sex = sex

. svy: total _one, over(race, nolab)

. matrix total_race = e(b)

. matrix rownames total_race = race

. * interaction of sex and race

. generate sex_race = sex*10 + race

. svy: total _one, over(sex_race, nolab)

. matrix total_sex_race = e(b)

. matrix rownames total_sex_race = sex_race

. * obtaining the sample

. sample 500, count by(region)

. * calibrating the weights

. ipfraking [pw=finalwgt], ctotal(total_sex total_race) generate(rakedwgt2) meta

Let us extend this example to post-stratification (note that the requisite interaction
variable race_sex was generated with the full data set):

. * post-stratification

. ipfraking [pw=finalwgt], ctotal(total_sex_race) generate(pstrwgt2) meta

Let us now and generate weight reports for each version of the weights.

. * reports

. ipfraking_report using rakedwgt2-report, raked_weight(rakedwgt2) ///

xls replace by(_one) matrices(total_sex total_race total_sex_race)

. ipfraking_report using pstrwgt2-report, raked_weight(pstrwgt2) ///

xls replace by(_one) matrices(total_sex total_race total_sex_race)

Fine points of these reports:

* Excel copies are produced for each report (xls options)

* The list of the known control totals matrices(total_sex total_race total_sex_race)
can be copied and pasted between the reports.

- For the rakedwgt2 weight variable,
its margins sex and race will be picked up from meta results,
and will be reported as Variable_Class == "Raking margin", while the interaction
sex_race will be assigned the role of Variable_Class == "Other known target".
A warning will be produced for sex and race that these variables
are processed as raking margins, and will not be processed again due to the
matrices() option.

- For the pstrwgt2 weight variable,
sex_race will be reported as Variable_Class == "Raking margin",
while the main effects sex and race will be
reported as Variable_Class == "Other known target".
A warning will be produced for sex_race variable that
it is processed as a raking margin, and will not be processed again due to the
matrices() option.

* Overall summaries are produced for the weights through by(_one) specification.
This variable has only one category, so summaries for the weights will be computed
for the data set as a whole.
This row of the data will have
Variable_Class == "Auxiliary variable", as we did not supply the control
totals for it.

Author

Stanislav Kolenikov

Senior Scientist

Abt Associates

skolenik at gmail dot com

Also see

ipfraking (if installed)