Guttman error graphs: a visual approach to scalability analysis

Reichenheim, Michael Eduardo; Moraes, Claudia Leite de; Bastos, João Luiz

doi:10.11606/s1518-8787.2026060007015

person Michael Eduardo Reichenheim

Study design and planning · Data collection, analysis, and interpretation · Manuscript preparation or revision · Approval of the final version · Public responsibility for the content of the article

school Universidade do Estado do Rio de Janeiro. Instituto de Medicina Social Hésio Cordeiro. Departamento de Epidemiologia. Rio de Janeiro, RJ, Brasil

0000-0001-7232-6745

person Claudia Leite de Moraes

Data collection, analysis, and interpretation · Manuscript preparation or revision · Approval of the final version · Public responsibility for the content of the article

school Universidade do Estado do Rio de Janeiro. Instituto de Medicina Social Hésio Cordeiro. Departamento de Epidemiologia. Rio de Janeiro, RJ, Brasilschool Universidade Estácio de Sá. Programa de Pós-graduação em Saúde da Família. Rio de Janeiro, RJ, Brasil

0000-0002-3223-1634

person João Luiz Bastos

Study design and planning · Data collection, analysis, and interpretation · Manuscript preparation or revision · Approval of the final version · Public responsibility for the content of the article

school Universidade Federal de Santa Catarina. Departamento de Saúde Pública. Florianópolis, SC, Brasil

0000-0002-1816-0745

personCorrespondence: Michael Reichenheim Universidade do Estado do Rio de Janeiro Rua São Francisco Xavier, 524, Bloco D, 7º andar 20550-013 Rio de Janeiro, RJ, Brazil E-mail:
michaelreichenheim@gmail.com

Associate Editor:

Leandro F. M. Rezende https://orcid.org/%200000-0002-7469-1399

Conflict of Interest:

The authors declare no conflict of interest.

Argument	Default	Instructions and explanations
data,	---	User-specified date set.
... (items)	---	Specified by the user. Items must be separated by commas, including the last one.
sw	NULL	If =TRUE, the variable containing the sample weight must be specidfied (e.g., ‘sw=data$sw_var,’. See the text for more details, as well as the Supplementary Documentation for guttemap v 1.0.
scl	1	Indicates the scaling of an internal variable, aiming to maximize discretion for projection to the target population if sw is specified. More details can be found in the text and supplementary documentation.
sclmsg	FALSE	By default, it prevents some information about the transformation and scaling of sw from being printed to the console. It can (should) be set to TRUE the first few times the user uses guttemap to guide the use of scl. More details can also be found in the text and supplementary documentation.
grtit	“Guttman Error Map”	Specifies the title of the graph. The default can be overwritten with your own title.
grfont	“Times New Roman”	If the user wishes, any other font allowed by the operating system can be specified.
grsave	FALSE	Does not save the graphic to the computer’s hard drive/SSD by default. If the user wishes to override this, simply indicate the name they want to give to the file to be saved.
grty	“svg”	Uses the SVG format by default if “grsave” is specified. This format can be converted into editable objects later. Many other formats supported by R can be specified (in quotation marks) at the user’s discretion (e.g., PDF, PostScript (PS), JPG, WMF).
titsize	18	Font size used in the title.
xlabsize	12	Font size used in horizontal labels.
ylabsize	12	Font size used in vertical labels.
valsize	3.5	Font size used for values shown within graphs, indicating the percentage of pairwise Guttman errors.
valformat	%.1f	It indicates the number of decimal places that values within graphs (GE) should be displayed. The default is 1 decimal place, but this can be overridden by the user (e.g., %.3f to display values to 3 decimal places).
item_position	“bottom”	Indicates where item labels should be positioned on the chart. The default places them below the horizontal axis to conform to tradition. However, there is an advantage to placing them at the top (specifying “top”) for vertical viewing of the GE. More details in the text.
item_order	“decreasing”	Specifies the order in which items are positioned on the graph. The default causes the order (from left to right and top to bottom) to automatically follow the decreasing frequency logic of the items, assuming that the less frequent the item, the more intense it is. The user can change the default by specifying “custom.” This changes the order of placement to that specified by the user in the item declaration argument.
legposit	“bottom”	Indicates where the legend should be positioned. In addition to the bottom, it is possible to specify “right,” ‘left,” and “top”. If the user does not want to display the legend, simply specify “none.”
legtit	“% error”	Specifies the caption title. The default can be overwritten with your own title.
legsize	100	Specifies the size of the legend in relation to the body of the graph. The default is maximum, but the user can decrease the size of the entire set (color gradient, title, and values).
obs	FALSE	Displays the effective sample size in the console if TRUE.
mat	FALSE	Displays the calculated matrices in the console if TRUE. Includes the Guttman and Loevinger H error matrices for pairs (H_ij), items (H_i), and total (H_(·)).
tith	FALSE	If TRUE, displays the H_i of the items below the item labels on the horizontal axis.
itemh	FALSE	If TRUE, displays the total H_(·) of the scale in the chart title.
nowarn	FALSE	If TRUE, it prevents messages other than those specific to guttemap from being displayed.
smooth	0	Controls the level of smoothing applied to the Guttman error map. The default “smooth=0” displays a standard discrete heatmap; “smooth=100” creates a continuous gradient heatmap, providing a smooth color gradient effect; values between 0 and 100 apply partial smoothing, blending discrete blocks with a continuous gradient effect. More details in the text.