| Title: | Analysis and Visualization of Circular Data |
|---|---|
| Description: | Circumplex models, which organize constructs in a circle around two underlying dimensions, are popular for studying interpersonal functioning, mood/affect, and vocational preferences/environments. This package provides tools for analyzing and visualizing circular data, including scoring functions for relevant instruments and a generalization of the bootstrapped structural summary method from Zimmermann & Wright (2017) <doi:10.1177/1073191115621795> and functions for creating publication-ready tables and figures from the results. |
| Authors: | Jeffrey Girard [aut, cre] (ORCID: <https://orcid.org/0000-0002-7359-3746>), Johannes Zimmermann [aut] (ORCID: <https://orcid.org/0000-0001-6975-2356>), Aidan Wright [aut] (ORCID: <https://orcid.org/0000-0002-2369-0601>) |
| Maintainer: | Jeffrey Girard <[email protected]> |
| License: | GPL-3 |
| Version: | 1.2.0.9999 |
| Built: | 2026-07-03 15:13:21 UTC |
| Source: | https://github.com/jmgirard/circumplex |
Display the anchors of a circumplex instrument including the total number of anchors and each anchor's numerical value and text label. Anchors are the response options that respondants select from (e.g., 0 = No, 1 = Yes).
anchors(x)anchors(x)
x |
Required. An object of the instrument class. |
The same input object. Prints text to console.
Other instrument functions:
instruments(),
items(),
norms(),
scales()
anchors(csip)anchors(csip)
A small example dataset containing standardized scores on eight hypothetical circumplex scales. Taken from Wright, Pincus, Conroy, & Hilsenroth (2009).
aw2009aw2009
A data frame with 5 observations and 8 variables:
circumplex scale at 90 degrees
circumplex scale at 135 degrees
circumplex scale at 180 degrees
circumplex scale at 225 degrees
circumplex scale at 270 degrees
circumplex scale at 315 degrees
circumplex scale at 360 degrees
circumplex scale at 45 degrees
A ggplot2 layer that draws, for each profile, the wedge spanning its
amplitude confidence interval (radially) and its displacement confidence
interval (angularly), on the canvas produced by ggcircumplex(). The
amplitude/displacement-to-canvas transform – including the wrap-around when
a displacement interval crosses the 0/360 degree boundary – is handled
internally, so the bounds are supplied directly in SSM units.
geom_ssm_arc( mapping = NULL, data = NULL, stat = StatSsmArc, position = "identity", ..., amax = 0.5, n = 360, na.rm = TRUE, show.legend = NA, inherit.aes = TRUE )geom_ssm_arc( mapping = NULL, data = NULL, stat = StatSsmArc, position = "identity", ..., amax = 0.5, n = 360, na.rm = TRUE, show.legend = NA, inherit.aes = TRUE )
mapping, data, stat, position, show.legend, inherit.aes, ...
|
Standard
ggplot2 layer arguments. |
amax |
A single positive number giving the amplitude represented by the
canvas's outer ring; must match the |
n |
The number of points used to draw each arc's curved edges (default = 360). |
na.rm |
Ignored; profiles with a missing displacement or amplitude bound (degenerate profiles) are always dropped. |
A ggplot2 layer.
ggcircumplex(), geom_ssm_point()
data("jz2017") res <- ssm_analyze(jz2017, scales = 2:9, measures = "NARPD") amax <- 0.5 ggcircumplex(octants(), amax = amax) + geom_ssm_arc( data = res$results, mapping = ggplot2::aes( amplitude_min = a_lci, amplitude_max = a_uci, displacement_min = d_lci, displacement_max = d_uci ), amax = amax, alpha = 0.4 )data("jz2017") res <- ssm_analyze(jz2017, scales = 2:9, measures = "NARPD") amax <- 0.5 ggcircumplex(octants(), amax = amax) + geom_ssm_arc( data = res$results, mapping = ggplot2::aes( amplitude_min = a_lci, amplitude_max = a_uci, displacement_min = d_lci, displacement_max = d_uci ), amax = amax, alpha = 0.4 )
A ggplot2 layer that places a point for each profile at its
amplitude and displacement, on the canvas produced by ggcircumplex().
The amplitude/displacement-to-canvas transform is handled internally, so
the amplitude and displacement aesthetics are supplied directly in SSM
units (amplitude in the score metric, displacement in degrees).
geom_ssm_point( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., amax = 0.5, na.rm = TRUE, show.legend = NA, inherit.aes = TRUE )geom_ssm_point( mapping = NULL, data = NULL, stat = "identity", position = "identity", ..., amax = 0.5, na.rm = TRUE, show.legend = NA, inherit.aes = TRUE )
mapping, data, stat, position, show.legend, inherit.aes, ...
|
Standard
ggplot2 layer arguments. |
amax |
A single positive number giving the amplitude represented by the
canvas's outer ring; must match the |
na.rm |
Ignored; profiles with a missing displacement or amplitude (degenerate profiles) are always dropped, since they have no location. |
A ggplot2 layer.
ggcircumplex(), geom_ssm_arc()
data("jz2017") res <- ssm_analyze(jz2017, scales = 2:9, measures = "NARPD") amax <- 0.5 ggcircumplex(octants(), amax = amax) + geom_ssm_point( data = res$results, mapping = ggplot2::aes(amplitude = a_est, displacement = d_est), amax = amax )data("jz2017") res <- ssm_analyze(jz2017, scales = 2:9, measures = "NARPD") amax <- 0.5 ggcircumplex(octants(), amax = amax) + geom_ssm_point( data = res$results, mapping = ggplot2::aes(amplitude = a_est, displacement = d_est), amax = amax )
Build an empty circular canvas – the amplitude rings, displacement spokes,
and scale labels that circumplex figures are drawn on – as a ggplot2
object. Additional layers (points, arcs, annotations) can be added to it
with +, so it serves as the reusable foundation for custom circumplex
visualizations. The package's own ssm_plot_circle() draws on the same
canvas.
ggcircumplex( angles = octants(), labels = NULL, amax = 0.5, font_size = 12, instrument = NULL )ggcircumplex( angles = octants(), labels = NULL, amax = 0.5, font_size = 12, instrument = NULL )
angles |
Optional. A numeric vector of the angular position (in
degrees) of each circumplex scale, going counterclockwise from the right
(default = |
labels |
Optional. Either |
amax |
Optional. A single positive number giving the amplitude at the outer ring, which sets the amplitude-axis labels; the center of the circle is fixed at amplitude 0 (default = 0.5). |
font_size |
Optional. A single positive number giving the size (in pt) of the scale and amplitude labels (default = 12). |
instrument |
Optional. Either |
A ggplot2 object containing the empty circumplex canvas.
ssm_plot_circle(), which draws SSM results on this canvas.
# A default octant canvas ggcircumplex() # Label the scales with their circumplex pole abbreviations ggcircumplex(octants(), labels = PANO()) # Derive the angles and labels from a circumplex instrument ggcircumplex(instrument = csip)# A default octant canvas ggcircumplex() # Label the scales with their circumplex pole abbreviations ggcircumplex(octants(), labels = PANO()) # Derive the angles and labels from a circumplex instrument ggcircumplex(instrument = csip)
Format a data frame as an HTML table and render it to the web viewer.
html_render(df, caption = NULL, align = "l", ...)html_render(df, caption = NULL, align = "l", ...)
df |
A data frame to be rendered as an HTML table. |
caption |
A string to be displayed above the table. |
align |
A string indicating the alignment of the cells (default = "l"). |
... |
Other arguments to pass to |
HTML syntax for the df table.
Other table functions:
ssm_table()
The circumplex package includes information about numerous circumplex
instruments including instructions for scoring and standardizing items.
Individual instruments can be loaded using the instrument function.
instruments()instruments()
Other instrument functions:
anchors(),
items(),
norms(),
scales()
instruments()instruments()
Rescore each circumplex item using deviation scoring across variables. In other words, subtract each observation's mean response from each response. This effectively removes the presence of a general factor, which can make certain circumplex fit analyses more powerful.
ipsatize(data, items, na.rm = TRUE, prefix = "", suffix = "_i", append = TRUE)ipsatize(data, items, na.rm = TRUE, prefix = "", suffix = "_i", append = TRUE)
data |
Required. A data frame or matrix containing at least circumplex scales. |
items |
Required. A character vector containing the column names, or a
numeric vector containing column indexes, of item variables in |
na.rm |
Optional. A logical that determines whether missing values should be ignored during the calculation of the mean during ipsatization (default = TRUE). |
prefix |
Optional. A string that will be added to the start of each
|
suffix |
Optional. A string that will be added to the end of each
|
append |
Optional. A logical that determines whether to append the
ipsatized scores to |
A data frame that matches data except that the variables specified
in items have been rescored using ipsatization.
Other tidying functions:
norm_standardize(),
score(),
self_standardize()
data("raw_iipsc") ipsatize(raw_iipsc, items = 1:32) ipsatize(raw_iipsc, items = sprintf("IIP%02d", 1:32))data("raw_iipsc") ipsatize(raw_iipsc, items = 1:32) ipsatize(raw_iipsc, items = sprintf("IIP%02d", 1:32))
Display the items of a circumplex instrument including the total number of
items and each item's number and text. The item ordering/numbering displayed
here is the same ordering/numbering assumed by the score() function.
items(x)items(x)
x |
Required. An object of the instrument class. |
The same input object. Prints text to console.
Other instrument functions:
anchors(),
instruments(),
norms(),
scales()
items(csip)items(csip)
A large example dataset containing gender, raw mean scores on the Inventory of Interpersonal Problems - Short Circumplex (IIP-SC), and raw sum scores on the Personality Diagnostic Questionnaire - 4th Edition Plus (PDQ-4+).
jz2017jz2017
A data frame with 1166 observations and 19 variables:
Self-reported Gender
Domineering Problems (IIP-SC) 90 degrees
Vindictive Problems (IIP-SC) 135 degrees
Cold Problems (IIP-SC) 180 degrees
Socially Avoidant Problems (IIP-SC) 225 degrees
Nonassertive Problems(IIP-SC) 270 degrees
Easily Exploited Problems (IIP-SC) 315 degrees
Overly Nurturant Problems (IIP-SC) 360 degrees
Intrusive Problems (IIP-SC) 45 degrees
Paranoid PD Symptoms (PDQ-4+)
Schizoid PD Symptoms (PDQ-4+)
Schizotypal PD Symptoms (PDQ-4+)
Antisocial PD Symptoms (PDQ-4+)
Borderline PD Symptoms (PDQ-4+)
Histrionic PD Symptoms (PDQ-4+)
Narcissistic PD Symptoms (PDQ-4+)
Avoidant PD Symptoms (PDQ-4+)
Dependent PD Symptoms (PDQ-4+)
Obsessive-Compulsive PD Symptoms (PDQ-4+)
Take in a data frame containing circumplex scales, angle definitions for each scale, and normative data (from the package or custom) and return that same data frame with each specified circumplex scale transformed into standard scores (i.e., z-scores) based on comparison to the normative data.
norm_standardize( data, scales, angles = octants(), instrument, sample = 1, prefix = "", suffix = "_z", append = TRUE )norm_standardize( data, scales, angles = octants(), instrument, sample = 1, prefix = "", suffix = "_z", append = TRUE )
data |
Required. A data frame or matrix containing at least circumplex scales. |
scales |
Required. A character vector containing the column names, or a numeric vector containing the column indexes, for the variables (scale scores) to be standardized. |
angles |
Required. A numeric vector containing the angular displacement
of each circumplex scale included in |
instrument |
Required. An instrument object from the package. To see the
available circumplex instruments, see |
sample |
Required. An integer corresponding to the normative sample to
use in standardizing the scale scores (default = 1). See |
prefix |
Optional. A string to include at the beginning of the newly
calculated scale variables' names, before the scale name and |
suffix |
Optional. A string to include at the end of the newly
calculated scale variables' names, after the scale name and |
append |
Optional. A logical that determines whether the calculated
standardized scores should be added as columns to |
A data frame that contains the norm-standardized versions of scales.
Other tidying functions:
ipsatize(),
score(),
self_standardize()
data("jz2017") norm_standardize(jz2017, scales = 2:9, instrument = iipsc, sample = 1)data("jz2017") norm_standardize(jz2017, scales = 2:9, instrument = iipsc, sample = 1)
Display the norms for a circumplex instrument including the total number of normative data sets available and each data set's number, sample size, population, and source reference and hyperlink. If another normative data set exists that is not yet included in the package, please let us know.
norms(x)norms(x)
x |
Required. An object of the instrument class. |
The same input object. Prints text to console.
Other instrument functions:
anchors(),
instruments(),
items(),
scales()
norms(csip)norms(csip)
Return a vector of angular displacements, in degrees, for eight equally
spaced circumplex scales corresponding to the circumplex octants. Can be
passed to the angles parameter of other functions in this package.
octants()octants()
A numeric vector with eight elements, each corresponding to the angular displacement (in degrees) of a subscale, in the following order: PA, BC, DE, FG, HI, JK, LM, NO.
octants()octants()
Return a vector of abbreviations for octant circumplex scales, from PA to NO.
PANO(case = "upper")PANO(case = "upper")
case |
An optional string the determines whether the abbreviations should be in uppercase or lowercase. (default = "upper") |
A character vector with eight elements, each corresponding to the abbreviation of an octant subscale: PA, BC, DE, FG, HI, JK, LM, NO.
PANO() PANO(case = "lower")PANO() PANO(case = "lower")
Return a vector of angular displacements, in degrees, for four equally spaced
circumplex scales corresponding to the circumplex poles. Can be passed to the
angles parameter of other functions in this package.
poles()poles()
A numeric vector with four elements, each corresponding to the angular displacement (in degrees) of a subscale, in the following order: PA, DE, HI, LM.
poles()poles()
Return a vector of angular displacements, in degrees, for four equally spaced
circumplex scales corresponding to the circumplex quadrants. Can be passed to
the angles parameter of other functions in this package.
quadrants()quadrants()
A numeric vector with eight elements, each corresponding to the angular displacement (in degrees) of a subscale, in the following order: BC, FG, JK, NO.
quadrants()quadrants()
A small example dataset containing raw item responses on the Inventory of Interpersonal Problems, Short Circumplex (IIP-SC). This data set is useful for testing functions that operate on item-level data.
raw_iipscraw_iipsc
A data frame with 10 observations and 32 variables.
A ggplot2 continuous position scale for the angle axis of a linear
circumplex plot, such as the score-by-angle curve drawn by
ssm_plot_curve(). It places axis breaks at the circumplex scale angles and
labels them, by default, with their angular position in degrees. Custom text
labels or a circumplex_instrument can be supplied instead, using the same
conventions as ggcircumplex(), so the linear axis and the circular canvas
label their scales consistently.
scale_x_circumplex(angles = octants(), labels = NULL, instrument = NULL, ...)scale_x_circumplex(angles = octants(), labels = NULL, instrument = NULL, ...)
angles |
Optional. A numeric vector of the angular position (in
degrees) of each circumplex scale (default = |
labels |
Optional. Either |
instrument |
Optional. Either |
... |
Additional arguments passed to
|
A ggplot2 scale object that can be added to a plot with +.
# Degree-labeled angle axis scale_x_circumplex(octants()) # Label the axis with an instrument's scale abbreviations scale_x_circumplex(instrument = csip)# Degree-labeled angle axis scale_x_circumplex(octants()) # Label the axis with an instrument's scale abbreviations scale_x_circumplex(instrument = csip)
Display the scales of a circumplex instrument including the total number of scales and each scale's abbreviation, hypothetical angle, and text label.
scales(x, items = FALSE)scales(x, items = FALSE)
x |
Required. An object of the instrument class. |
items |
Optional. A logical determining whether the items for each scale should be displayed below its other information (default = FALSE). |
The same input object. Prints text to console.
Other instrument functions:
anchors(),
instruments(),
items(),
norms()
scales(csip) scales(csip, items = TRUE)scales(csip) scales(csip, items = TRUE)
Calculate mean scores on circumplex scales from item responses by using a set of scoring instructions, which may be loaded from the package or created as a custom data frame.
score( data, items, instrument, na.rm = TRUE, prefix = "", suffix = "", append = TRUE )score( data, items, instrument, na.rm = TRUE, prefix = "", suffix = "", append = TRUE )
data |
Required. A data frame or matrix containing at least circumplex scales. |
items |
Required. The variable names or column numbers for the variables
in |
instrument |
Required. An instrument object from the package. To see the
available circumplex instruments, use |
na.rm |
Optional. A logical that determines if missing values should be omitted from the calculation of scores (default = TRUE). When set to TRUE, scales with missing data are essentially calculated with mean imputation. |
prefix |
Optional. A string to include at the beginning of the newly
calculated scale variables' names, before |
suffix |
Optional. A string to include at the end of the newly
calculated scale variables' names, after |
append |
Optional. A logical that determines whether the calculated
score variables will be appended to |
A data frame that matches .data except that new variables are
appended that contain mean scores on each variable included in key.
Other tidying functions:
ipsatize(),
norm_standardize(),
self_standardize()
data("raw_iipsc") score(raw_iipsc, items = 1:32, instrument = iipsc, prefix = "IIPSC_")data("raw_iipsc") score(raw_iipsc, items = 1:32, instrument = iipsc, prefix = "IIPSC_")
Take in a data frame containing circumplex scales (or items) and return that same data frame with each specified variable transformed into standard scores (i.e., z-scores) based on observed means and SDs.
self_standardize( data, scales, na.rm = TRUE, prefix = "", suffix = "_z", append = TRUE )self_standardize( data, scales, na.rm = TRUE, prefix = "", suffix = "_z", append = TRUE )
data |
Required. A data frame or matrix containing at least circumplex scales. |
scales |
Required. A character vector containing the column names, or a numeric vector containing the column indexes, for the variables (scale scores) to be standardized. |
na.rm |
Optional. A logical that determines whether to remove missing values from scales when calculating the means and SDs used for standardization (default = TRUE). |
prefix |
Optional. A string to include at the beginning of the newly
calculated scale variables' names, before the scale name and |
suffix |
Optional. A string to include at the end of the newly
calculated scale variables' names, after the scale name and |
append |
Optional. A logical that determines whether the calculated
standardized scores should be added as columns to |
A data frame that contains the self-standardized versions of
scales.
Other tidying functions:
ipsatize(),
norm_standardize(),
score()
self_standardize(aw2009, scales = 1:8)self_standardize(aw2009, scales = 1:8)
Calculate SSM parameters with confidence intervals (bootstrapped by
default, or Monte Carlo via method) for a variety of different analysis
types. Depending on what arguments are supplied, either mean-based or
correlation-based analyses will be performed, one or more groups will be
used to stratify the data, and contrasts between groups or measures will be
calculated.
ssm_analyze( data, scales, angles = octants(), measures = NULL, grouping = NULL, contrast = FALSE, boots = 2000, interval = 0.95, listwise = TRUE, measures_labels = NULL, parallel = "no", ncpus = 1, method = "bootstrap" )ssm_analyze( data, scales, angles = octants(), measures = NULL, grouping = NULL, contrast = FALSE, boots = 2000, interval = 0.95, listwise = TRUE, measures_labels = NULL, parallel = "no", ncpus = 1, method = "bootstrap" )
data |
Required. A data frame or matrix containing at least circumplex scales. |
scales |
Required. A character vector of column names, or a numeric
vector of column indexes, from |
angles |
Optional. A numeric vector containing the angular displacement
of each circumplex scale included in |
measures |
Optional. Either |
grouping |
Optional. Either |
contrast |
Optional. A logical indicating whether to output the
difference between two measures' or two groups' SSM parameters. Can only be
set to TRUE when there are exactly two measures and one group, one measure
and two groups, or no measures and two groups (default = FALSE). The
contrast is always the second level minus the first. For two groups, this
is the second level of |
boots |
Optional. A single positive whole number indicating how many
bootstrap resamples (or, when |
interval |
Optional. A single positive number between 0 and 1 (exclusive) that indicates what confidence level to use when estimating the confidence intervals (default = 0.95). |
listwise |
Optional. A logical indicating whether missing values should be handled by listwise deletion (TRUE) or pairwise deletion (FALSE). Note that pairwise deletion may result in different missing data patterns in each bootstrap resample and is slower to compute (default = TRUE). |
measures_labels |
Optional. Either |
parallel |
Optional. A string indicating whether to distribute the
bootstrap computation across multiple CPU cores: "no" (default),
"multicore" (process forking; available on macOS and Linux, ignored on
Windows), or "snow" (a local PSOCK cluster; available on all platforms).
Passed to |
ncpus |
Optional. A single positive whole number indicating how many
CPU cores to use when |
method |
Optional. A string indicating how to estimate the confidence
intervals: "bootstrap" (default) resamples the data, whereas "montecarlo"
draws parameter replicates from the asymptotic sampling distribution of
the group mean vector (mean-based analyses) or the measure-scale
correlation vector (correlation-based analyses) – a multivariate normal
with empirically estimated covariance – and propagates them through the
SSM parameter transformation. The Monte Carlo method is much faster for
large samples but relies on the asymptotic normality of the means or
correlations, so prefer the bootstrap for small samples; it also requires
listwise-complete data. Correlations are drawn jointly across measures
within each group on the Fisher z scale and back-transformed. The
|
A list containing the results and description of the analysis.
results |
A data frame with the SSM parameter estimates |
details |
A list with the number of bootstrap resamples or Monte Carlo draws (boots), the confidence interval percentage level (interval), the angular displacement of scales (angles), and the interval estimation method (method) |
call |
A language object containing the function call that created this object |
scores |
A data frame containing the mean scale scores |
type |
A string indicating what type of SSM analysis was done |
The profile displacement parameter is reported in the half-open interval
[0, 360) degrees. A profile that peaks exactly at the 0/360 degree
boundary is reported as approximately 360 (equivalently 0, the same
direction); which of the two appears is a floating-point detail and both
denote the same pole. Contrast displacements are instead reported as a
signed difference in (-180, 180] degrees (see the "Contrast" block in
the printed output).
Degenerate profiles (flat or zero-amplitude) have undefined displacement
(and fit, if flat), which is reported as NA with a warning. Bootstrap
resamples that produce degenerate profiles (e.g., a resampled measure
with zero variance) are excluded from the confidence intervals with a
warning reporting how many were dropped; the intervals are then
conditional on estimability.
[0, 360)degrees. A profile that peaks exactly at the 0/360 degree boundary is reported as approximately 360 (equivalently 0, the same direction); which of the two appears is a floating-point detail and both denote the same pole. Contrast displacements are instead reported as a signed difference in(-180, 180]: R:0,%20360)%60%20degrees.%20A%20profile%20that%20peaks%20exactly%20at%20the%200/360%20degree%0A%20%20boundary%20is%20reported%20as%20approximately%20360%20(equivalently%200,%20the%20same%0A%20%20direction);%20which%20of%20the%20two%20appears%20is%20a%20floating-point%20detail%20and%20both%0A%20%20denote%20the%20same%20pole.%20Contrast%20displacements%20are%20instead%20reported%20as%20a%0A%20%20signed%20difference%20in%20%60(-180,%20180
This is the only function in the package that consumes R's random number
stream (ssm_score()/ssm_parameters() and the tidying functions are
deterministic). Call set.seed() immediately before ssm_analyze() for
reproducible confidence intervals:
Bootstrap (method = "bootstrap", the default): the
same seed gives byte-identical results, regardless of the
parallel/ncpus settings (see their descriptions below), because
boot::boot() draws all resample indices from the seed before any
work is parallelized.
Monte Carlo (method = "montecarlo"): the same seed
gives byte-identical results. Adding a group or measure, or
reordering scales/measures, changes the random draw sequence, so
results are reproducible for a fixed call but will not match after
such structural edits even with the same seed.
The two methods are not expected to agree numerically
for the same seed – they consume the random stream in unrelated
ways. Their statistical agreement (validated on real data; see
vignette("introduction-to-ssm-analysis")) is a separate property
from RNG reproducibility.
Increasing boots changes the CI by design (more resamples/draws
should tighten Monte Carlo error), so results are not expected to be
stable across different boots values, only within a fixed call.
Other ssm functions:
ssm_parameters(),
ssm_score(),
ssm_table()
Other analysis functions:
ssm_parameters(),
ssm_score()
# Load example data data("jz2017") # Single-group mean-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO") ) # Single-group correlation-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = c("NARPD", "ASPD") ) # Monte Carlo confidence intervals (faster for large samples) ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), method = "montecarlo" ) # Multiple-group mean-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), grouping = "Gender" ) # Multiple-group mean-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), grouping = "Gender", contrast = TRUE ) # Single-group correlation-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = c("NARPD", "ASPD"), contrast = TRUE ) # Multiple-group correlation-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = "NARPD", grouping = "Gender" ) # Multiple-group correlation-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = "NARPD", grouping = "Gender", contrast = TRUE )# Load example data data("jz2017") # Single-group mean-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO") ) # Single-group correlation-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = c("NARPD", "ASPD") ) # Monte Carlo confidence intervals (faster for large samples) ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), method = "montecarlo" ) # Multiple-group mean-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), grouping = "Gender" ) # Multiple-group mean-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), grouping = "Gender", contrast = TRUE ) # Single-group correlation-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = c("NARPD", "ASPD"), contrast = TRUE ) # Multiple-group correlation-based SSM ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = "NARPD", grouping = "Gender" ) # Multiple-group correlation-based SSM with contrast ssm_analyze( jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), measures = "NARPD", grouping = "Gender", contrast = TRUE )
Calculate SSM parameters (without confidence intervals) for a set of scores
and generate a data frame with customizable labels for each parameter value.
This function requires the input to be a numeric vector (or coercable to one)
and returns only the parameters. See ssm_score() for a similar
function that calculates SSM parameters for each row of a data frame.
ssm_parameters( scores, angles = octants(), prefix = "", suffix = "", e_label = "Elev", x_label = "Xval", y_label = "Yval", a_label = "Ampl", d_label = "Disp", f_label = "Fit" )ssm_parameters( scores, angles = octants(), prefix = "", suffix = "", e_label = "Elev", x_label = "Xval", y_label = "Yval", a_label = "Ampl", d_label = "Disp", f_label = "Fit" )
scores |
Required. A numeric vector (or single row data frame) containing one score for each of a set of circumplex scales. |
angles |
Required. A numeric vector containing the angular displacement
of each circumplex scale included in |
prefix |
Optional. A string to append to the beginning of all of the SSM parameters' variable names (default = ""). |
suffix |
Optional. A string to append to the end of all of the SSM parameters' variable names (default = ""). |
e_label |
Optional. A string representing the variable name of the SSM elevation parameter (default = "Elev"). |
x_label |
Optional. A string representing the variable name of the SSM x-value parameter (default = "Xval"). |
y_label |
Optional. A string representing the variable name of the SSM y-value parameter (default = "Yval"). |
a_label |
Optional. A string representing the variable name of the SSM amplitude parameter (default = "Ampl"). |
d_label |
Optional. A string representing the variable name of the SSM displacement parameter (default = "Disp"). |
f_label |
Optional. A string representing the variable name of the SSM fit or R-squared value (default = "Fit"). |
A data frame containing the SSM parameters calculated from scores.
For degenerate profiles the undefined parameters are returned as NA
with a warning: a flat profile (zero variance) has undefined displacement
and fit, and a profile with real variance but zero amplitude (i.e., no
first-harmonic component) has undefined displacement and a fit of 0.
Note that this applies only to amplitudes that are zero up to machine
precision; small real amplitudes are always estimated, and their
uncertainty is expressed through confidence intervals (see
ssm_analyze()).
Other ssm functions:
ssm_analyze(),
ssm_score(),
ssm_table()
Other analysis functions:
ssm_analyze(),
ssm_score()
# Manually enter octant scores scores <- c(0.55, 0.58, 0.62, 0.76, 1.21, 1.21, 1.48, 0.90) ssm_parameters(scores) # Customize several of the labels ssm_parameters(scores, x_label = "LOV", y_label = "DOM") # Add a prefix to all labels ssm_parameters(scores, prefix = "IIP_")# Manually enter octant scores scores <- c(0.55, 0.58, 0.62, 0.76, 1.21, 1.21, 1.48, 0.90) ssm_parameters(scores) # Customize several of the labels ssm_parameters(scores, x_label = "LOV", y_label = "DOM") # Add a prefix to all labels ssm_parameters(scores, prefix = "IIP_")
Take in the results of a Structural Summary Method analysis and plot the point and interval estimate for each row (e.g., group or measure) in a circular space quantified by displacement and amplitude.
ssm_plot_circle( ssm_object, amax = NULL, legend_font_size = 12, scale_font_size = 12, drop_lowfit = FALSE, repel = FALSE, angle_labels = NULL, palette = "Set2", vary_shapes = FALSE, ... )ssm_plot_circle( ssm_object, amax = NULL, legend_font_size = 12, scale_font_size = 12, drop_lowfit = FALSE, repel = FALSE, angle_labels = NULL, palette = "Set2", vary_shapes = FALSE, ... )
ssm_object |
Required. The output of |
amax |
A positive real number corresponding to the radius of the circle. It is used to scale the amplitude values and will determine which amplitude labels are drawn. |
legend_font_size |
A positive real number corresponding to the size (in pt) of the text labels in the legend (default = 12). |
scale_font_size |
A positive real number corresponding to the size (in pt) of the text labels for the amplitude and displacement scales (default = 12). |
drop_lowfit |
A logical determining whether profiles with low model fit (<.70) should be omitted or plotted with dashed borders (default = FALSE). |
repel |
An experimental argument for plotting text labels instead of colors. |
angle_labels |
A character vector specifying text labels to plot around
the circle for each scale. Can also specify NULL to default to numerical
angle labels or a vector of empty strings ("") to hide the labels. If not
NULL, must have the same length and ordering as the |
palette |
A string corresponding to the palette to be used from ColorBrewer for the color and fill aesthetics. If set to NULL, all points will appear blue and no legend will be there (useful for showing the coverage of a high number of variables). |
vary_shapes |
A logical determining whether profiles should each get their own shape or vary only by fill color. This only works when the number of profiles is five or less. (default = FALSE) |
... |
Not used. Supplying an unrecognized argument produces a warning. |
A ggplot variable containing a completed circular plot.
data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD") ) ssm_plot_circle(res)data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD") ) ssm_plot_circle(res)
Take in the results of a Structural Summary Method analysis with pairwise contrasts and plot the point and interval estimates for each parameter's contrast (e.g., between groups or measures).
ssm_plot_contrast( ssm_object, drop_xy = FALSE, sig_color = "#fc8d62", ns_color = "white", linesize = 1.25, fontsize = 12, ... )ssm_plot_contrast( ssm_object, drop_xy = FALSE, sig_color = "#fc8d62", ns_color = "white", linesize = 1.25, fontsize = 12, ... )
ssm_object |
Required. The results output of |
drop_xy |
A logical determining whether the X-Value and Y-Value parameters should be removed from the plot (default = FALSE). |
sig_color |
Optional. A string corresponding to the color to use to denote significant contrasts (default = "#fc8d62"). |
ns_color |
Optional. A string corresponding to the color to use to denote non-significant contrasts (default = "white"). |
linesize |
Optional. A positive number corresponding to the size of the point range elements in mm (default = 1.5). |
fontsize |
Optional. A positive number corresponding to the size of the axis labels, numbers, and facet headings in pt (default = 12). |
... |
Not used. Supplying an unrecognized argument produces a warning. |
A ggplot variable containing difference point-ranges faceted by SSM parameter. An interval that does not contain the value of zero has p<.05.
data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD"), contrast = TRUE ) ssm_plot_contrast(res)data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD"), contrast = TRUE ) ssm_plot_contrast(res)
Take in the results of a Structural Summary Method analysis and plot the scores by angle and the estimated SSM curve.
ssm_plot_curve( ssm_object, angle_labels = NULL, base_size = 11, drop_lowfit = FALSE, ... )ssm_plot_curve( ssm_object, angle_labels = NULL, base_size = 11, drop_lowfit = FALSE, ... )
ssm_object |
Required. The results output of |
angle_labels |
Optional. Either NULL or a character vector that
determines the x-axis labels. If NULL, the labels will be the angle
numbers. If a character vector, must be the same length and in the same
order as the |
base_size |
Optional. A positive number corresponding to the base font size in pts (default = 11). |
drop_lowfit |
Optional. A logical indicating whether to omit profiles with low fit (<.70) or include them with dashed lines (default = FALSE). |
... |
Not used. Supplying an unrecognized argument produces a warning. |
A ggplot object depicting the SSM curve(s) of each profile.
data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = 10:13 ) ssm_plot_curve(res) ssm_plot_curve(res, angle_labels = PANO())data("jz2017") res <- ssm_analyze( jz2017, scales = 2:9, measures = 10:13 ) ssm_plot_curve(res) ssm_plot_curve(res, angle_labels = PANO())
Calculate the SSM parameters for each row of a data frame and add the results as additional columns. This can be useful when the SSM is being used for the description or visualization of individual data points rather than for statistical inference on groups of data points.
ssm_score(data, scales, angles = octants(), append = TRUE, ...)ssm_score(data, scales, angles = octants(), append = TRUE, ...)
data |
Required. A data frame or matrix containing at least circumplex scales. |
scales |
Required. The variable names or column numbers for the
variables in |
angles |
Required. A numeric vector containing the angular displacement
of each circumplex scale included in |
append |
Optional. A logical indicating whether to append the output to
|
... |
Optional. Additional named arguments passed to
|
A data frame containing .data plus six additional columns
containing the SSM parameters (calculated rowwise).
Other ssm functions:
ssm_analyze(),
ssm_parameters(),
ssm_table()
Other analysis functions:
ssm_analyze(),
ssm_parameters()
data("aw2009") ssm_score( aw2009, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO") )data("aw2009") ssm_score( aw2009, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO") )
Take in the results of an SSM analysis and return an HTML table with the desired formatting.
ssm_table(ssm_object, caption = NULL, drop_xy = FALSE, render = TRUE)ssm_table(ssm_object, caption = NULL, drop_xy = FALSE, render = TRUE)
ssm_object |
Required. The results output of |
caption |
A string to be displayed above the table (default = NULL). |
drop_xy |
A logical indicating whether the x-value and y-value parameters should be omitted from the output (default = FALSE). |
render |
A logical indicating whether the table should be displayed in the RStudio viewer or web browser (default = TRUE). |
A data frame containing the information for the HTML table. As a side-effect, may also output the HTML table to the web viewer.
Other ssm functions:
ssm_analyze(),
ssm_parameters(),
ssm_score()
Other table functions:
html_render()
# Load example data data("jz2017") # Create table of profile results res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD") ) ssm_table(res) # Create table of contrast results res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD"), contrast = TRUE ) ssm_table(res)# Load example data data("jz2017") # Create table of profile results res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD") ) ssm_table(res) # Create table of contrast results res <- ssm_analyze( jz2017, scales = 2:9, measures = c("NARPD", "ASPD"), contrast = TRUE ) ssm_table(res)