@wentorai/research-plugins 1.0.0

package/skills/analysis/statistics/power-analysis-guide/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: power-analysis-guide
+description: "Sample size calculation and statistical power analysis guide"
+metadata:
+  openclaw:
+    emoji: "target"
+    category: "analysis"
+    subcategory: "statistics"
+    keywords: ["sample size calculation", "power analysis", "effect size", "significance testing"]
+    source: "wentor-research-plugins"
+---
+
+# Power Analysis Guide
+
+Calculate appropriate sample sizes for your study using power analysis, understand effect sizes, and avoid underpowered or wastefully overpowered designs.
+
+## Core Concepts
+
+### The Four Parameters of Power Analysis
+
+Every power analysis involves four interrelated quantities. Fix any three to solve for the fourth:
+
+| Parameter | Symbol | Definition | Typical Value |
+|-----------|--------|-----------|---------------|
+| **Effect size** | d, r, f, etc. | Magnitude of the phenomenon you expect to detect | Varies by field |
+| **Significance level** (alpha) | alpha | Probability of Type I error (false positive) | 0.05 |
+| **Statistical power** (1 - beta) | 1 - beta | Probability of detecting a true effect | 0.80 or 0.90 |
+| **Sample size** | N | Number of observations needed | Solve for this |
+
+### Error Types
+
+| | H0 is true (no effect) | H0 is false (effect exists) |
+|---|---|---|
+| **Reject H0** | Type I error (alpha) | Correct (power = 1 - beta) |
+| **Fail to reject H0** | Correct (1 - alpha) | Type II error (beta) |
+
+## Effect Size Conventions
+
+### Cohen's d (Two-Group Comparison)
+
+```
+d = (M1 - M2) / SD_pooled
+```
+
+| Size | Cohen's d | Interpretation |
+|------|-----------|---------------|
+| Small | 0.2 | Subtle, may need large N to detect |
+| Medium | 0.5 | Noticeable, typical in social sciences |
+| Large | 0.8 | Obvious, often visible without statistics |
+
+### Correlation (r)
+
+| Size | r | r-squared |
+|------|---|-----------|
+| Small | 0.1 | 1% variance explained |
+| Medium | 0.3 | 9% variance explained |
+| Large | 0.5 | 25% variance explained |
+
+### Cohen's f (ANOVA)
+
+| Size | f | Equivalent eta-squared |
+|------|---|----------------------|
+| Small | 0.10 | 0.01 |
+| Medium | 0.25 | 0.06 |
+| Large | 0.40 | 0.14 |
+
+### Odds Ratio (Logistic Regression)
+
+| Size | OR |
+|------|-----|
+| Small | 1.5 |
+| Medium | 2.5 |
+| Large | 4.0 |
+
+## Power Analysis in Python (statsmodels)
+
+### Two-Sample t-Test
+
+```python
+from statsmodels.stats.power import TTestIndPower
+
+analysis = TTestIndPower()
+
+# Solve for sample size
+n = analysis.solve_power(
+    effect_size=0.5,    # Cohen's d = medium
+    alpha=0.05,         # Significance level
+    power=0.80,         # 80% power
+    ratio=1.0,          # Equal group sizes
+    alternative='two-sided'
+)
+print(f"Required N per group: {int(n) + 1}")  # Output: 64
+
+# Solve for power (given N)
+power = analysis.solve_power(
+    effect_size=0.5,
+    alpha=0.05,
+    nobs1=50,
+    ratio=1.0,
+    alternative='two-sided'
+)
+print(f"Power with N=50 per group: {power:.3f}")  # Output: 0.697
+```
+
+### Paired t-Test
+
+```python
+from statsmodels.stats.power import TTestPower
+
+analysis = TTestPower()
+n = analysis.solve_power(
+    effect_size=0.3,    # Small-medium effect
+    alpha=0.05,
+    power=0.80,
+    alternative='two-sided'
+)
+print(f"Required N (paired): {int(n) + 1}")  # Output: 90
+```
+
+### One-Way ANOVA
+
+```python
+from statsmodels.stats.power import FTestAnovaPower
+
+analysis = FTestAnovaPower()
+n = analysis.solve_power(
+    effect_size=0.25,   # Cohen's f = medium
+    alpha=0.05,
+    power=0.80,
+    k_groups=4          # Number of groups
+)
+print(f"Required N per group: {int(n) + 1}")  # Output: 45
+```
+
+### Chi-Square Test
+
+```python
+from statsmodels.stats.power import GofChisquarePower
+
+analysis = GofChisquarePower()
+n = analysis.solve_power(
+    effect_size=0.3,    # Cohen's w = medium
+    alpha=0.05,
+    power=0.80,
+    n_bins=4            # Degrees of freedom + 1
+)
+print(f"Required total N: {int(n) + 1}")
+```
+
+### Multiple Regression
+
+```python
+from statsmodels.stats.power import FTestPower
+
+analysis = FTestPower()
+# For R-squared: convert to f2 = R2 / (1 - R2)
+r_squared = 0.10  # Expected R-squared for the model
+f2 = r_squared / (1 - r_squared)  # f2 = 0.111
+
+n = analysis.solve_power(
+    effect_size=f2,
+    alpha=0.05,
+    power=0.80,
+    df_num=5            # Number of predictors
+)
+# n returned is df_denom; total N = n + df_num + 1
+total_n = int(n) + 5 + 1
+print(f"Required total N: {total_n}")
+```
+
+## Power Analysis in R (pwr Package)
+
+```r
+library(pwr)
+
+# Two-sample t-test
+result <- pwr.t.test(d = 0.5, sig.level = 0.05, power = 0.80,
+                     type = "two.sample", alternative = "two.sided")
+cat("N per group:", ceiling(result$n), "\n")
+
+# Correlation test
+result <- pwr.r.test(r = 0.3, sig.level = 0.05, power = 0.80,
+                     alternative = "two.sided")
+cat("Total N:", ceiling(result$n), "\n")
+
+# One-way ANOVA (4 groups)
+result <- pwr.anova.test(k = 4, f = 0.25, sig.level = 0.05, power = 0.80)
+cat("N per group:", ceiling(result$n), "\n")
+
+# Chi-square test
+result <- pwr.chisq.test(w = 0.3, df = 3, sig.level = 0.05, power = 0.80)
+cat("Total N:", ceiling(result$N), "\n")
+
+# Plot power curve
+result <- pwr.t.test(d = 0.5, sig.level = 0.05, power = NULL,
+                     n = seq(10, 200, by = 5))
+plot(result)
+```
+
+## Using G*Power (Desktop Application)
+
+G*Power (gpower.hhu.de) is a free, widely-used GUI application for power analysis:
+
+1. **Select test family**: t-tests, F-tests, chi-square, z-tests, exact tests
+2. **Select statistical test**: e.g., "Means: Difference between two independent means (two groups)"
+3. **Select type of analysis**: A priori (compute N), Post hoc (compute power), Sensitivity (compute detectable effect)
+4. **Input parameters**: Effect size, alpha, power, allocation ratio
+5. **Calculate**: Click "Calculate" to get the result
+6. **Plot**: Use "X-Y plot for a range of values" to visualize power curves
+
+## Practical Recommendations
+
+### Choosing Effect Sizes
+
+Do NOT blindly use Cohen's conventions. Instead:
+
+1. **Literature review**: Find effect sizes reported in similar studies
+2. **Pilot data**: Run a small pilot study to estimate the effect
+3. **Smallest effect of interest (SESOI)**: What is the smallest effect that would be practically meaningful?
+4. **Meta-analyses**: Use pooled effect sizes from meta-analyses in your area
+
+### Common Mistakes
+
+| Mistake | Problem | Solution |
+|---------|---------|----------|
+| Post hoc power analysis | Circular and uninformative after data collection | Only do a priori power analysis |
+| Using Cohen's "medium" by default | May be unrealistic for your field | Base on literature or SESOI |
+| Ignoring attrition | Actual N may be lower than planned | Inflate N by 10-20% for expected dropout |
+| Forgetting multiple comparisons | Bonferroni corrections reduce power | Adjust alpha for the number of tests |
+| Not reporting power analysis | Reviewers cannot evaluate adequacy | Always report in Methods section |
+
+### Reporting Template
+
+```
+A priori power analysis was conducted using [G*Power 3.1 / statsmodels / R pwr].
+For a [test name] with an expected effect size of [d/r/f = X] (based on
+[source: previous study / meta-analysis / pilot data]), alpha = .05, and
+power = .80, the required sample size was [N per group / total N]. To account
+for an estimated [X]% attrition rate, we recruited [final N] participants.
+```

package/skills/analysis/statistics/sem-guide/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: sem-guide
+description: "Structural equation modeling with latent variables guide"
+metadata:
+  openclaw:
+    emoji: "network"
+    category: "analysis"
+    subcategory: "statistics"
+    keywords: ["structural equation modeling", "SEM", "latent variable model", "multilevel model"]
+    source: "wentor-research-plugins"
+---
+
+# Structural Equation Modeling Guide
+
+Build, estimate, and evaluate structural equation models (SEM) with latent variables using Python (semopy) and R (lavaan), including confirmatory factor analysis and path analysis.
+
+## What Is SEM?
+
+Structural Equation Modeling is a multivariate statistical framework that combines factor analysis and path analysis to test complex theoretical models involving:
+
+- **Observed (manifest) variables**: Directly measured (e.g., survey items, test scores)
+- **Latent (unobserved) variables**: Theoretical constructs measured indirectly through observed indicators (e.g., "motivation," "intelligence")
+- **Structural paths**: Directional relationships between variables (regression-like)
+- **Measurement model**: How latent variables relate to their indicators (CFA)
+- **Structural model**: How latent variables relate to each other (path analysis)
+
+## SEM Components
+
+| Component | Description | Diagram Symbol |
+|-----------|-------------|---------------|
+| Observed variable | Measured directly | Rectangle |
+| Latent variable | Inferred from indicators | Oval/circle |
+| Regression path | Directional relationship | Single-headed arrow |
+| Covariance | Non-directional association | Double-headed arrow |
+| Error/residual | Unexplained variance | Small circle with arrow |
+
+## Step 1: Confirmatory Factor Analysis (CFA)
+
+CFA tests whether observed variables load onto hypothesized latent factors.
+
+### In R (lavaan)
+
+```r
+library(lavaan)
+
+# Define the measurement model
+# =~ means "is measured by"
+cfa_model <- '
+  # Latent variable definitions
+  Motivation =~ mot1 + mot2 + mot3 + mot4
+  SelfEfficacy =~ se1 + se2 + se3
+  Performance =~ perf1 + perf2 + perf3 + perf4
+
+  # Covariances between latent variables (estimated by default in CFA)
+'
+
+# Fit the model
+fit <- cfa(cfa_model, data = mydata, estimator = "MLR")
+
+# View results
+summary(fit, fit.measures = TRUE, standardized = TRUE)
+
+# Key output to examine:
+# - Factor loadings (standardized > 0.5 is desirable)
+# - Model fit indices (see table below)
+# - Modification indices (for model improvement)
+modindices(fit, sort = TRUE, minimum.value = 10)
+```
+
+### In Python (semopy)
+
+```python
+import semopy
+import pandas as pd
+
+# Define model in lavaan-like syntax
+model_spec = """
+Motivation =~ mot1 + mot2 + mot3 + mot4
+SelfEfficacy =~ se1 + se2 + se3
+Performance =~ perf1 + perf2 + perf3 + perf4
+"""
+
+# Fit the model
+model = semopy.Model(model_spec)
+result = model.fit(data)
+
+# View parameter estimates
+print(model.inspect())
+
+# Get fit statistics
+stats = semopy.calc_stats(model)
+print(stats.T)
+```
+
+## Step 2: Full Structural Model
+
+After confirming the measurement model, add structural (regression) paths.
+
+### In R (lavaan)
+
+```r
+sem_model <- '
+  # Measurement model
+  Motivation =~ mot1 + mot2 + mot3 + mot4
+  SelfEfficacy =~ se1 + se2 + se3
+  Performance =~ perf1 + perf2 + perf3 + perf4
+
+  # Structural model (regressions)
+  # ~ means "is regressed on"
+  Performance ~ Motivation + SelfEfficacy
+  SelfEfficacy ~ Motivation
+
+  # Optional: define indirect effect
+  # indirect := a * b
+'
+
+fit <- sem(sem_model, data = mydata, estimator = "MLR")
+summary(fit, fit.measures = TRUE, standardized = TRUE, rsquare = TRUE)
+```
+
+### Mediation Analysis
+
+```r
+mediation_model <- '
+  # Measurement model
+  X =~ x1 + x2 + x3
+  M =~ m1 + m2 + m3
+  Y =~ y1 + y2 + y3
+
+  # Structural model
+  M ~ a*X          # a path
+  Y ~ b*M + c*X    # b path + direct effect c
+
+  # Define indirect and total effects
+  indirect := a * b
+  total := c + a * b
+'
+
+fit <- sem(mediation_model, data = mydata, se = "bootstrap", bootstrap = 1000)
+summary(fit, standardized = TRUE)
+
+# Bootstrap confidence intervals for indirect effect
+parameterEstimates(fit, boot.ci.type = "bca.simple", standardized = TRUE)
+```
+
+## Model Fit Assessment
+
+### Fit Index Reference Table
+
+| Index | Good Fit | Acceptable | What It Measures |
+|-------|----------|------------|-----------------|
+| Chi-square (p) | p > 0.05 | Sensitive to N; use with other indices | Exact fit test |
+| Chi-square/df | < 2 | < 3 | Parsimony-adjusted exact fit |
+| CFI | > 0.95 | > 0.90 | Comparative fit vs. null model |
+| TLI | > 0.95 | > 0.90 | CFI adjusted for parsimony |
+| RMSEA | < 0.06 | < 0.08 | Approximate fit per df |
+| SRMR | < 0.08 | < 0.10 | Average residual correlation |
+| AIC/BIC | Lower = better | -- | Model comparison (not absolute) |
+
+### Interpreting Fit
+
+```r
+# Extract fit measures in lavaan
+fitMeasures(fit, c("chisq", "df", "pvalue", "cfi", "tli", "rmsea",
+                    "rmsea.ci.lower", "rmsea.ci.upper", "srmr"))
+```
+
+**Reporting template:**
+```
+The structural equation model demonstrated adequate fit to the data:
+chi-square(df) = X.XX, p = .XXX; CFI = .XX; TLI = .XX; RMSEA = .XXX
+[90% CI: .XXX, .XXX]; SRMR = .XXX.
+```
+
+## Model Modification and Comparison
+
+### Modification Indices
+
+```r
+# Show top modification indices
+mi <- modindices(fit, sort = TRUE)
+head(mi, 10)
+
+# Common modifications:
+# - Allow error covariances between similarly-worded items
+# - Add cross-loadings (if theoretically justified)
+# - Remove non-significant paths
+```
+
+### Model Comparison
+
+```r
+# Compare nested models using chi-square difference test
+fit1 <- sem(model1, data = mydata)  # More constrained
+fit2 <- sem(model2, data = mydata)  # Less constrained
+
+anova(fit1, fit2)  # Chi-square difference test
+
+# For non-nested models, compare AIC/BIC
+fitMeasures(fit1, c("aic", "bic"))
+fitMeasures(fit2, c("aic", "bic"))
+```
+
+## Common Pitfalls
+
+| Issue | Problem | Solution |
+|-------|---------|----------|
+| Small sample size | Unstable estimates, poor fit | Minimum N = 200, or 10-20 per parameter |
+| Too many parameters | Overfitting, non-convergence | Simplify model, use parceling |
+| Non-normal data | Biased standard errors | Use MLR estimator or bootstrapping |
+| Ignoring missing data | Biased results | Use FIML (full information maximum likelihood) |
+| Data-driven respecification | Capitalizing on chance | Cross-validate with holdout sample |
+| Conflating fit with truth | Good fit does not mean correct model | Consider equivalent/alternative models |
+
+## Assumptions and Diagnostics
+
+1. **Multivariate normality**: Check with Mardia's test; use robust estimators (MLR) if violated
+2. **Linearity**: SEM assumes linear relationships between variables
+3. **No multicollinearity**: Correlations between latent variables should not exceed 0.85
+4. **Sufficient sample size**: Rule of thumb: N >= 200 or 10-20 observations per estimated parameter
+5. **Correct model specification**: Omitted variables can bias all estimates
+
+```r
+# Check multivariate normality
+library(MVN)
+mvn(mydata[, c("mot1", "mot2", "mot3", "se1", "se2", "se3")],
+    mvnTest = "mardia")
+
+# Use robust estimation if non-normal
+fit_robust <- sem(sem_model, data = mydata, estimator = "MLR")
+```

package/skills/analysis/statistics/survival-analysis-guide/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: survival-analysis-guide
+description: "Conduct Kaplan-Meier, Cox regression, and time-to-event analyses"
+metadata:
+  openclaw:
+    emoji: "hourglass_flowing_sand"
+    category: "analysis"
+    subcategory: "statistics"
+    keywords: ["survival analysis", "Kaplan-Meier", "Cox regression", "time-to-event", "hazard ratio", "censoring"]
+    source: "wentor-research-plugins"
+---
+
+# Survival Analysis Guide
+
+A skill for conducting time-to-event analyses including Kaplan-Meier estimation, log-rank tests, and Cox proportional hazards regression. Covers censoring concepts, assumption checking, and reporting standards for clinical and social science research.
+
+## Core Concepts
+
+### What Is Survival Analysis?
+
+Survival analysis studies the time until an event of interest occurs. Despite the name, the "event" need not be death -- it can be any well-defined transition:
+
+```
+Medical:      Time to disease recurrence, death, or recovery
+Engineering:  Time to equipment failure
+Social:       Time to job termination, divorce, or graduation
+Business:     Time to customer churn or first purchase
+Ecology:      Time to species extinction in a habitat
+```
+
+### Censoring
+
+```
+Right censoring (most common):
+  The event has not occurred by the end of the study period.
+  Example: Patient is still alive at study end.
+  The survival time is "at least T" -- we know T but not the true event time.
+
+Left censoring:
+  The event occurred before the observation period began.
+  Example: HIV infection detected, but seroconversion happened before testing.
+
+Interval censoring:
+  The event occurred between two observation times.
+  Example: A patient tests negative at visit 3 and positive at visit 4.
+```
+
+## Kaplan-Meier Estimation
+
+### Computing the Survival Curve
+
+```python
+import numpy as np
+
+
+def kaplan_meier(times: list[float], events: list[int]) -> dict:
+    """
+    Compute Kaplan-Meier survival estimates.
+
+    Args:
+        times: Observed times (event or censoring time)
+        events: Event indicator (1 = event occurred, 0 = censored)
+
+    Returns:
+        Dict with time points and survival probabilities
+    """
+    data = sorted(zip(times, events), key=lambda x: x[0])
+    n = len(data)
+
+    unique_event_times = sorted(set(t for t, e in data if e == 1))
+    survival = 1.0
+    results = {"time": [0], "survival": [1.0]}
+
+    at_risk = n
+    idx = 0
+
+    for t_event in unique_event_times:
+        # Count censored before this event time
+        while idx < n and data[idx][0] < t_event:
+            if data[idx][1] == 0:
+                at_risk -= 1
+            idx += 1
+
+        # Count events at this time
+        d = sum(1 for t, e in data if t == t_event and e == 1)
+        c = sum(1 for t, e in data if t == t_event and e == 0)
+
+        survival *= (at_risk - d) / at_risk
+        results["time"].append(t_event)
+        results["survival"].append(survival)
+
+        at_risk -= (d + c)
+        idx = max(idx, sum(1 for t, _ in data if t <= t_event))
+
+    return results
+```
+
+### Using lifelines in Python
+
+```python
+from lifelines import KaplanMeierFitter
+
+kmf = KaplanMeierFitter()
+kmf.fit(durations=time_column, event_observed=event_column, label="Overall")
+
+# Plot the survival curve
+kmf.plot_survival_function()
+
+# Median survival time
+print(f"Median survival: {kmf.median_survival_time_}")
+
+# Survival probability at specific time
+print(f"5-year survival: {kmf.predict(5.0):.3f}")
+```
+
+## Log-Rank Test
+
+### Comparing Survival Between Groups
+
+```python
+from lifelines.statistics import logrank_test
+
+results = logrank_test(
+    durations_A=group_a_times,
+    durations_B=group_b_times,
+    event_observed_A=group_a_events,
+    event_observed_B=group_b_events
+)
+
+print(f"Test statistic: {results.test_statistic:.3f}")
+print(f"p-value: {results.p_value:.4f}")
+```
+
+The log-rank test is the standard method for comparing two or more survival curves. It tests the null hypothesis that the survival functions are identical. It is most powerful when hazards are proportional (consistent relative risk over time).
+
+## Cox Proportional Hazards Regression
+
+### Model Fitting
+
+```python
+from lifelines import CoxPHFitter
+import pandas as pd
+
+cph = CoxPHFitter()
+cph.fit(
+    df,
+    duration_col="time",
+    event_col="event",
+    formula="age + treatment + stage"
+)
+
+cph.print_summary()
+
+# Hazard ratios
+print(cph.summary[["exp(coef)", "exp(coef) lower 95%", "exp(coef) upper 95%", "p"]])
+```
+
+### Interpreting Hazard Ratios
+
+```
+Hazard Ratio (HR) = exp(coefficient)
+
+HR = 1.0   No effect
+HR > 1.0   Increased hazard (worse survival)
+HR < 1.0   Decreased hazard (better survival)
+
+Example output:
+  treatment:  HR = 0.65, 95% CI [0.48, 0.88], p = 0.005
+  Interpretation: Treatment group has 35% lower hazard of the event
+                  compared to the control group.
+```
+
+### Checking the Proportional Hazards Assumption
+
+```python
+# Schoenfeld residuals test
+cph.check_assumptions(df, p_value_threshold=0.05, show_plots=True)
+```
+
+If the proportional hazards assumption is violated, consider: stratified Cox models, time-varying covariates, or accelerated failure time (AFT) models as alternatives.
+
+## Reporting Standards
+
+### STROBE-style Reporting for Survival Analyses
+
+```
+1. Report number of events and total person-time at risk
+2. Present Kaplan-Meier curves with number-at-risk tables
+3. Report median survival with 95% confidence intervals
+4. Report hazard ratios with 95% CIs and p-values
+5. State which covariates were included in adjusted models
+6. Report proportional hazards assumption test results
+7. Specify the handling of tied event times (Efron, Breslow)
+8. Note any competing risks and how they were handled
+```