# semEffect

**Repository Path**: openResearch/semEffect

## Basic Information

- **Project Name**: semEffect
- **Description**: semEffect: Unified Effect Analysis and Visualization for Structural Equation Models in R
- **Primary Language**: R
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: https://github.com/PhDMeiwp/semEffect/
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-08
- **Last Updated**: 2025-09-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# semEffect: Unified Effect Analysis and Visualization for Structural Equation Models in R


[![CRAN download counts](https://cranlogs.r-pkg.org/badges/grand-total/semEffect)](https://cran.r-project.org/package=semEffect)

<div align="center">
<img src="docs/images/semEffect_logo.png" width="200">
</div>

## Description
<br>Provides a **unified interface** to calculate, extract, and visualize standardized effect decompositions (direct, indirect, and total effects) for three major structural equation modeling (SEM) frameworks: **'lavaan', 'piecewiseSEM', and 'plspm'**. 
	The package simplifies comparative SEM analysis by **offering consistent functions across different modeling paradigms**. 
	Key features include automated handling of zero-effect variables, generation of publication-ready 'ggplot2' visualizations, and returning both wide-format and long-format effect tables. 
	It supports flexible effect filtering, accepts multi-model object inputs, and allows extensive customization of visualization parameters. 
	**The 'sem_modeling()' function serves as a central wrapper, enabling users to fit models using different packages with a unified syntax.** 
</br>

## Citation

Please cite the package as:

Mei et al. (2025) semEffect: Unified Effect Analysis and Visualization for Structural Equation Models in R. R package version 1.3.0.

<div align="center">
<img src="docs/images/TOC.png" width="600">
</div>

## Installation

### Option 1: Install from CRAN:
```r
install.packages("semEffect")
```

### Option 2: Install from GitHub:
```r
install.packages("devtools")
devtools::install_github("PhDMeiwp/semEffect", dependencies = TRUE)
```

### Option 3: Install from Gitee:
```r
install.packages("remotes")
remotes::install_git("https://gitee.com/openResearch/semEffect.git")
```

## Core Functions

### 1. `sem_modeling()` - Unified SEM Fitting Interface
Fit SEM models using different packages with consistent syntax:
```r
sem_modeling(model, data, type = "lavaan", modes = NULL, ...)
```

### 2. `get_effect()` - Effect Extraction
Extract standardized effects from fitted SEM objects:
```r
get_effect(object, target, delete_zero_effect = TRUE, zero_threshold = 1e-10)
```

### 3. `plot_effect()` - Effect Visualization
Create publication-ready visualizations of effect values:
```r
plot_effect(object, target, total_only = FALSE, 
            total_color = "skyblue",
            color_palette = c("darkgreen", "skyblue", "orange"))
```

## Usage Examples

### Example 1: lavaan Framework
```r
library(semEffect)
library(lavaan)

# Define model using lavaan syntax
model <- "
  # Measurement model
  ind60 =~ x1 + x2 + x3
  dem60 =~ y1 + y2 + y3 + y4
  dem65 =~ y5 + y6 + y7 + y8

  # Structural model
  dem60 ~ ind60
  dem65 ~ ind60 + dem60
"

# Fit model using sem_modeling
fit <- sem_modeling(model, data = PoliticalDemocracy, type = "lavaan")

# Extract effects for target variable
effects <- get_effect(fit, target = "dem65")

# View results
print(effects$effect_table)

# Create visualization
p <- plot_effect(fit, target = "dem65", total_only = FALSE)
print(p)
```

### Example 2: piecewiseSEM Framework
```r
library(semEffect)
library(piecewiseSEM)

# Create model list
# option 1
model_list <- "
    rich ~ cover
    cover ~ firesev
    firesev ~ age
"

#option 2
model_list <- list(
  lm(rich ~ cover, data = keeley),
  lm(cover ~ firesev, data = keeley),
  lm(firesev ~ age, data = keeley)
)

# Fit model using sem_modeling
pmod <- sem_modeling(model_list, data = keeley, type = "piecewiseSEM")

# Analyze effects with custom colors
effects <- get_effect(pmod, target = "rich")
plot_effect(pmod, target = "rich", 
            color_palette = c("darkgreen", "grey80", "purple"))
```

### Example 3: plspm Framework with Lavaan-style Syntax
```r
library(semEffect)
library(plspm)
data(satisfaction)

# Define model using lavaan-style syntax
model_plspm <- "
  # Measurement model
  IMAG =~ imag1 + imag2 + imag3 + imag4 + imag5
  EXPE =~ expe1 + expe2 + expe3 + expe4 + expe5
  QUAL =~ qual1 + qual2 + qual3 + qual4 + qual5
  VAL =~ val1 + val2 + val3 + val4
  SAT =~ sat1 + sat2 + sat3 + sat4
  LOY =~ loy1 + loy2 + loy3 + loy4

  # Structural model
  EXPE ~ IMAG
  QUAL ~ EXPE
  VAL ~ EXPE + QUAL
  SAT ~ IMAG + EXPE + QUAL + VAL
  LOY ~ SAT + IMAG
"

# Fit model (modes default to all "A" reflective)
pls_fit <- sem_modeling(model_plspm, data = satisfaction, type = "plspm")

# Extract and visualize effects
effects <- get_effect(pls_fit, target = "LOY")
plot_effect(pls_fit, target = "LOY", total_only = TRUE,
            total_color = RColorBrewer::brewer.pal(5, "Set2"))
```

## Advanced Features

### Customizing Visualizations
```r
# Customize plot appearance
p <- plot_effect(fit, target = "dem65", total_only = FALSE)
p +
  ggplot2::coord_flip() +
  ggplot2::theme_minimal() +
  ggplot2::ggtitle("Standardized Effects for Dem65") +
  ggplot2::theme(legend.position = "bottom")
```

### Handling Zero Effects
```r
# Keep zero-effect variables in results
effects <- get_effect(fit, target = "dem65", delete_zero_effect = FALSE)

# Adjust zero threshold
effects <- get_effect(fit, target = "dem65", zero_threshold = 1e-5)
```

### Model Comparison
```r
# Compare different SEM frameworks on same data
lavaan_fit <- sem_modeling(model, data = PoliticalDemocracy, type = "lavaan")
plspm_fit <- sem_modeling(model, data = PoliticalDemocracy, type = "plspm")

# Compare effects
lavaan_effects <- get_effect(lavaan_fit, target = "dem65")
plspm_effects <- get_effect(plspm_fit, target = "dem65")
```


## Contributing

We welcome contributions to the semEffect package:

- **Bug reports and feature requests**: File them on https://github.com/PhDMeiwp/semEffect/issues
- **Pull requests**: Submit via https://github.com/PhDMeiwp/semEffect/pulls
- **Documentation improvements**: Help us improve examples and documentation

## License

This package is distributed under the GPL-3 license.

## Contact

For questions and support, please use the https://github.com/PhDMeiwp/semEffect/issues or contact the maintainer directly.