# circumplex The goal of *circumplex* is to provide a powerful, flexible, and user-friendly way to analyze and visualize circumplex data. It was created and is maintained by [Jeffrey Girard](https://affcom.ku.edu/girard/); it was inspired by work from and was developed under advisement from Johannes Zimmermann and Aidan Wright. You can learn more about using this package through the vignette articles available on the [package website](https://circumplex.jmgirard.com/) or through [`?circumplex`](http://circumplex.jmgirard.com/reference/circumplex-package.md). ## Installation ``` r # Install release version from CRAN install.packages("circumplex") # Install development version from GitHub devtools::install_github("jmgirard/circumplex") ``` ## Usage ### Example 1 ``` r data("jz2017") results <- ssm_analyze( data = jz2017, scales = c("PA", "BC", "DE", "FG", "HI", "JK", "LM", "NO"), angles = c(90, 135, 180, 225, 270, 315, 360, 45), measures = c("NARPD", "ASPD"), measures_labels = c("Narcissistic PD", "Antisocial PD") ) summary(results) #> #> Statistical Basis: Correlation Scores #> Bootstrap Resamples: 2000 #> Confidence Level: 0.95 #> Listwise Deletion: TRUE #> Scale Displacements: 90 135 180 225 270 315 360 45 #> #> #> # Profile [Narcissistic PD]: #> #> Estimate Lower CI Upper CI #> Elevation 0.202 0.169 0.238 #> X-Value -0.062 -0.094 -0.029 #> Y-Value 0.179 0.145 0.213 #> Amplitude 0.189 0.154 0.227 #> Displacement 108.967 98.633 118.537 #> Model Fit 0.957 #> #> #> # Profile [Antisocial PD]: #> #> Estimate Lower CI Upper CI #> Elevation 0.124 0.087 0.158 #> X-Value -0.099 -0.133 -0.064 #> Y-Value 0.203 0.170 0.239 #> Amplitude 0.226 0.191 0.264 #> Displacement 115.927 107.327 124.188 #> Model Fit 0.964 ``` ``` r ssm_table(results, drop_xy = TRUE) ``` | Profile | Elevation | Amplitude | Displacement | Fit | |:---|:---|:---|:---|:---| | Narcissistic PD | 0.20 (0.17, 0.24) | 0.19 (0.15, 0.23) | 109.0 (98.6, 118.5) | 0.957 | | Antisocial PD | 0.12 (0.09, 0.16) | 0.23 (0.19, 0.26) | 115.9 (107.3, 124.2) | 0.964 | Correlation-based Structural Summary Statistics with 95% CIs {.table .table style="font-size: 12px; margin-left: auto; margin-right: auto;"} ``` r ssm_plot_circle(results) ``` ![](reference/figures/README-plot-1.png) ``` r ssm_plot_curve(results) ``` ![](reference/figures/README-plot2-1.png) ### Example 2 ``` r results2 <- ssm_analyze( data = jz2017, scales = PANO(), angles = octants(), grouping = "Gender", contrast = TRUE ) summary(results2) #> #> Statistical Basis: Mean Scores #> Bootstrap Resamples: 2000 #> Confidence Level: 0.95 #> Listwise Deletion: TRUE #> Scale Displacements: 90 135 180 225 270 315 360 45 #> #> #> # Profile [Female]: #> #> Estimate Lower CI Upper CI #> Elevation 0.946 0.909 0.984 #> X-Value 0.459 0.421 0.498 #> Y-Value -0.310 -0.355 -0.267 #> Amplitude 0.554 0.511 0.598 #> Displacement 325.963 322.182 330.063 #> Model Fit 0.889 #> #> #> # Profile [Male]: #> #> Estimate Lower CI Upper CI #> Elevation 0.884 0.843 0.923 #> X-Value 0.227 0.192 0.262 #> Y-Value -0.186 -0.225 -0.148 #> Amplitude 0.294 0.257 0.329 #> Displacement 320.685 313.462 327.843 #> Model Fit 0.824 #> #> #> # Contrast [Male - Female]: #> #> Estimate Lower CI Upper CI #> Δ Elevation -0.062 -0.118 -0.005 #> Δ X-Value -0.232 -0.283 -0.181 #> Δ Y-Value 0.124 0.067 0.183 #> Δ Amplitude -0.261 -0.318 -0.202 #> Δ Displacement -5.278 -13.353 2.755 #> Δ Model Fit -0.066 ``` ``` r ssm_table(results2, drop_xy = TRUE) ``` | Contrast | Elevation | Amplitude | Displacement | Fit | |:---|:---|:---|:---|:---| | Female | 0.95 (0.91, 0.98) | 0.55 (0.51, 0.60) | 326.0 (322.2, 330.1) | 0.889 | | Male | 0.88 (0.84, 0.92) | 0.29 (0.26, 0.33) | 320.7 (313.5, 327.8) | 0.824 | | Male - Female | -0.06 (-0.12, -0.01) | -0.26 (-0.32, -0.20) | -5.3 (-13.4, 2.8) | -0.066 | Correlation-based Structural Summary Statistics with 95% CIs {.table .table style="font-size: 12px; margin-left: auto; margin-right: auto;"} ``` r ssm_plot_contrast(results2, drop_xy = TRUE) ``` ![](reference/figures/README-plot3-1.png) ## Code of Conduct Please note that the ‘circumplex’ project is released with a [Contributor Code of Conduct](https://circumplex.jmgirard.com/CODE_OF_CONDUCT.html). By contributing to this project, you agree to abide by its terms. ## References Girard, J. M., Zimmermann, J., & Wright, A. G. C. (2018). New tools for circumplex data analysis and visualization in R. *Meeting of the Society for Interpersonal Theory and Research.* Montreal, Canada. Zimmermann, J., & Wright, A. G. C. (2017). Beyond description in interpersonal construct validation: Methodological advances in the circumplex Structural Summary Approach. *Assessment, 24*(1), 3–23. Wright, A. G. C., Pincus, A. L., Conroy, D. E., & Hilsenroth, M. J. (2009). Integrating methods to optimize circumplex description and comparison of groups. *Journal of Personality Assessment, 91*(4), 311–322. # Package index ## Instrument Functions Functions for importing and examining circumplex instruments - [`instruments()`](http://circumplex.jmgirard.com/reference/instruments.md) : List all available instruments - [`scales()`](http://circumplex.jmgirard.com/reference/scales.md) : Display the scales of a circumplex instrument - [`anchors()`](http://circumplex.jmgirard.com/reference/anchors.md) : Display the anchors of a circumplex instrument - [`items()`](http://circumplex.jmgirard.com/reference/items.md) : Display the items of a circumplex instrument - [`norms()`](http://circumplex.jmgirard.com/reference/norms.md) : Display the norms for a circumplex instrument ## Tidying Functions Functions for preparing data for analysis - [`ipsatize()`](http://circumplex.jmgirard.com/reference/ipsatize.md) : Ipsatize circumplex items using deviation scoring across variables - [`score()`](http://circumplex.jmgirard.com/reference/score.md) : Score circumplex scales from item responses - [`norm_standardize()`](http://circumplex.jmgirard.com/reference/norm_standardize.md) : Standardize circumplex scales using normative data - [`self_standardize()`](http://circumplex.jmgirard.com/reference/self_standardize.md) : Standardize circumplex scales using sample data ## Primary SSM Functions Functions for implementing the Structural Summary Method - [`ssm_analyze()`](http://circumplex.jmgirard.com/reference/ssm_analyze.md) : Perform analyses using the Structural Summary Method - [`ssm_analyze_long()`](http://circumplex.jmgirard.com/reference/ssm_analyze_long.md) : Perform SSM analyses on long-format repeated-measures data - [`ssm_table()`](http://circumplex.jmgirard.com/reference/ssm_table.md) : Create HTML table from SSM results or contrasts - [`ssm_parameters()`](http://circumplex.jmgirard.com/reference/ssm_parameters.md) : Calculate Structural Summary Method parameters for a set of scores - [`ssm_parameters_id()`](http://circumplex.jmgirard.com/reference/ssm_parameters_id.md) : Calculate SSM parameters for each person - [`summary(`*``*`)`](http://circumplex.jmgirard.com/reference/summary.circumplex_ssm_id.md) : Summarize per-person SSM parameters at the group level - [`ssm_draws()`](http://circumplex.jmgirard.com/reference/ssm_draws.md) : Summarize posterior draws as SSM parameters - [`ssm_score()`](http://circumplex.jmgirard.com/reference/ssm_score.md) : Calculate SSM parameters by row and add results as new columns ## SEM-Based SSM Functions Latent-variable (disattenuated) SSM via structural equation modeling - [`ssm_sem()`](http://circumplex.jmgirard.com/reference/ssm_sem.md) : Perform SEM-based (latent-variable) SSM analyses - [`ssm_sem_parameters()`](http://circumplex.jmgirard.com/reference/ssm_sem_parameters.md) : Calculate latent SSM parameters from a fitted lavaan measurement model - [`ssm_sem_syntax()`](http://circumplex.jmgirard.com/reference/ssm_sem_syntax.md) : Generate lavaan syntax for a fixed-angle circumplex measurement model ## Structure Evaluation Functions Functions for evaluating circumplex structure and CI trustworthiness - [`cpm_fit()`](http://circumplex.jmgirard.com/reference/cpm_fit.md) : Fit Browne's circular stochastic process model (circumplex fit statistics) - [`cpm_simulate()`](http://circumplex.jmgirard.com/reference/cpm_simulate.md) : Simulate data from a fitted circular process model - [`print(`*``*`)`](http://circumplex.jmgirard.com/reference/print.circumplex_cpm.md) : Print a circular process model fit - [`summary(`*``*`)`](http://circumplex.jmgirard.com/reference/summary.circumplex_cpm.md) : Summarize a circular process model fit - [`plot(`*``*`)`](http://circumplex.jmgirard.com/reference/plot.circumplex_cpm.md) : Plot a circular process model fit - [`fit_structure()`](http://circumplex.jmgirard.com/reference/fit_structure.md) : Evaluate circumplex structure (Acton & Revelle, 2004) - [`print(`*``*`)`](http://circumplex.jmgirard.com/reference/print.circumplex_structure.md) : Print circumplex-structure test results - [`summary(`*``*`)`](http://circumplex.jmgirard.com/reference/summary.circumplex_structure.md) : Summarize circumplex-structure test results - [`plot(`*``*`)`](http://circumplex.jmgirard.com/reference/plot.circumplex_structure.md) : Plot a circumplex-structure configuration - [`axes_reliability()`](http://circumplex.jmgirard.com/reference/axes_reliability.md) : Reliability of the circumplex axes (Strack, Jacobs & Grosse Holtforth, 2013) - [`print(`*``*`)`](http://circumplex.jmgirard.com/reference/print.circumplex_axes_reliability.md) : Print circumplex axes-reliability results - [`summary(`*``*`)`](http://circumplex.jmgirard.com/reference/summary.circumplex_axes_reliability.md) : Summarize circumplex axes-reliability results - [`ssm_ci_accuracy()`](http://circumplex.jmgirard.com/reference/ssm_ci_accuracy.md) : Assess the accuracy of SSM confidence intervals by simulation - [`summary(`*``*`)`](http://circumplex.jmgirard.com/reference/summary.circumplex_ci_accuracy.md) : Summarize the accuracy of SSM confidence intervals - [`plot(`*``*`)`](http://circumplex.jmgirard.com/reference/plot.circumplex_ci_accuracy.md) : Plot SSM CI accuracy across the amplitude ladder ## Visualization - Complete Plots Ready-made circumplex figures for a set of SSM results - [`ssm_plot_circle()`](http://circumplex.jmgirard.com/reference/ssm_plot_circle.md) : Create a Circular Plot of SSM Results - [`ssm_plot_curve()`](http://circumplex.jmgirard.com/reference/ssm_plot_curve.md) : Create a Curve Plot of SSM Results - [`ssm_plot_contrast()`](http://circumplex.jmgirard.com/reference/ssm_plot_contrast.md) : Create a Difference Plot of SSM Contrast Results - [`ssm_plot_trajectory()`](http://circumplex.jmgirard.com/reference/ssm_plot_trajectory.md) : Create a Trajectory Plot of SSM Results Over Time ## Visualization - Building Blocks Composable ggplot2 components for building custom circumplex figures - [`ggcircumplex()`](http://circumplex.jmgirard.com/reference/ggcircumplex.md) : Create a circumplex plotting canvas - [`coord_circumplex()`](http://circumplex.jmgirard.com/reference/coord_circumplex.md) : Circumplex coordinate system - [`geom_ssm_point()`](http://circumplex.jmgirard.com/reference/geom_ssm_point.md) : Draw SSM profile points in circumplex space - [`geom_ssm_arc()`](http://circumplex.jmgirard.com/reference/geom_ssm_arc.md) : Draw SSM confidence-region arcs in circumplex space - [`geom_ssm_path()`](http://circumplex.jmgirard.com/reference/geom_ssm_path.md) : Draw a profile's movement across occasions in circumplex space - [`scale_x_circumplex()`](http://circumplex.jmgirard.com/reference/scale_x_circumplex.md) : Angle-labeled x-axis scale for circumplex plots - [`theme_circumplex()`](http://circumplex.jmgirard.com/reference/theme_circumplex.md) : Circumplex canvas theme ## Secondary SSM Functions Functions for customizing SSM results - [`html_render()`](http://circumplex.jmgirard.com/reference/html_render.md) : Format and render data frame as HTML table ## Convenience Functions Functions that make your life easier - [`angle_unwrap()`](http://circumplex.jmgirard.com/reference/angle_unwrap.md) : Unwrap a sequence of angles onto a continuous branch - [`octants()`](http://circumplex.jmgirard.com/reference/octants.md) : Angular displacements for octant circumplex scales - [`poles()`](http://circumplex.jmgirard.com/reference/poles.md) : Angular displacements for pole circumplex scales - [`quadrants()`](http://circumplex.jmgirard.com/reference/quadrants.md) : Angular displacements for quadrant circumplex scales - [`PANO()`](http://circumplex.jmgirard.com/reference/PANO.md) : Two-letter abbreviations for octant circumplex scales ## Example Data - [`aw2009`](http://circumplex.jmgirard.com/reference/aw2009.md) : Standardized octant scores on hypothetical circumplex scales - [`jz2017`](http://circumplex.jmgirard.com/reference/jz2017.md) : Raw octant scores on real circumplex scales with covariates - [`raw_iipsc`](http://circumplex.jmgirard.com/reference/raw_iipsc.md) : Raw item responses on real circumplex scales - [`simulated_items`](http://circumplex.jmgirard.com/reference/simulated_items.md) : Simulated item responses on octant circumplex scales # Articles ### All vignettes - [Advanced Circumplex Visualization](http://circumplex.jmgirard.com/articles/advanced-visualization.md): - [Axes Reliability](http://circumplex.jmgirard.com/articles/axes-reliability.md): - [Bayesian SSM Analysis](http://circumplex.jmgirard.com/articles/bayesian-ssm-analysis.md): - [Evaluating Circumplex Structure](http://circumplex.jmgirard.com/articles/evaluating-circumplex-structure.md): - [Growth Models on SSM Parameters](http://circumplex.jmgirard.com/articles/growth-ssm-analysis.md): - [Intermediate SSM Analysis](http://circumplex.jmgirard.com/articles/intermediate-ssm-analysis.md): - [Introduction to SSM Analysis](http://circumplex.jmgirard.com/articles/introduction-to-ssm-analysis.md): - [SEM-Based SSM Analysis](http://circumplex.jmgirard.com/articles/sem-based-ssm-analysis.md): - [Using Circumplex Instruments](http://circumplex.jmgirard.com/articles/using-instruments.md):