Type: Package
Title: Descriptive, Reliability, and Inferential Tables for Psychometric Scales and Demographic Data
Version: 0.2.3
Description: Provides functions to format and summarise already computed outputs from commonly used statistical and psychometric functions into compact, single-row tables and simple graphs, with utilities to export results to CSV, Word, and Excel formats. The package does not implement new statistical methods or estimation procedures; instead, it organises and presents results obtained from existing functions such as psych::describe(), psych::alpha(), stats::t.test(), and gtsummary::tbl_summary() to streamline reporting workflows in clinical and psychological research.
License: MIT + file LICENSE
Encoding: UTF-8
RoxygenNote: 7.3.3
Imports: dplyr, gtsummary, purrr, rlang, stats, officer, openxlsx, utils, psych, stringr, flextable
Suggests: testthat (≥ 3.0.0)
Config/testthat/edition: 3
NeedsCompilation: no
Packaged: 2026-03-21 17:37:06 UTC; HP
Author: Darshankumar Dharaiya ORCID iD [aut, cre]
Maintainer: Darshankumar Dharaiya <dharaiya.darshan@gmail.com>
Depends: R (≥ 4.1.0)
Repository: CRAN
Date/Publication: 2026-03-21 17:50:03 UTC

Compute Intraclass Correlation Coefficient (ICC) for Selected Columns

Description

Computes Intraclass Correlation Coefficients (ICC) for a specified set of numeric variables within a data frame using psych::ICC().

This function standardizes column selection and basic validation while delegating all statistical estimation to psych::ICC().

Usage

compute_ICC(data, items, check_numeric = TRUE, lmer = FALSE, ...)

Arguments

data

A data frame containing the ratings or measurements.

items

A character vector specifying column names for which ICC should be calculated (e.g., raters or repeated measurements).

check_numeric

Logical. If TRUE (default), ensures all selected columns are numeric.

lmer

Logical. Passed to psych::ICC(). Default is FALSE.

...

Additional arguments passed to psych::ICC().

Details

The function does not choose or filter specific ICC models. All available ICC types (e.g., ICC1, ICC2, ICC3, single and average) are returned exactly as produced by psych::ICC().

Users are responsible for:

Value

An object returned by psych::ICC(), typically a list containing a results table with ICC estimates, F statistics, confidence intervals, and model details.

See Also

ICC

Wrap a pre computed psych::alpha object into a single row table

Description

Wrap a pre computed psych::alpha object into a single row table

Usage

make_alpha_table(alpha_res, scale_name = "Scale")

Arguments

alpha_res

A psych::alpha object (already computed)

scale_name

Name of the scale (default: "Scale")

Value

A data frame with columns: Scale, 95

Examples

# Create a minimal "psych::alpha" like object manually
alpha_obj <- list(
  total = list(
    raw_alpha = 0.85,
    lower = 0.78,
    upper = 0.92
  )
)

# Generate the formatted alpha table
make_alpha_table(alpha_obj, scale_name = "PHQ-9")

Convert Between Alphabetical and Numeric Responses

Description

Converts specified columns between alphabetical (text) and numeric values. Can either overwrite existing columns or create new ones.

Usage

make_alphanumeric_conversion(
  data,
  column_vars,
  from_values,
  to_values,
  new_names = NULL,
  case_sensitive = FALSE
)

Arguments

data

A data frame.

column_vars

Character vector of column names to convert.

from_values

Vector of values to replace (character or numeric).

to_values

Vector of replacement values (must be same length as from_values).

new_names

Optional character vector of new column names. If NULL (default), original columns are overwritten.

case_sensitive

Logical. Only relevant when converting character values. Default is FALSE.

Details

Factors are automatically converted to character before matching. Unmatched values become NA with a warning.

Value

A data frame with converted values.

Create a one-row summary table for a chi-square test

Description

This function formats the result of a pre-computed chisq.test() into a single-row data frame. It supports goodness-of-fit, independence, and homogeneity chi-square tests and includes an appropriate effect size with a qualitative interpretation.

Usage

make_chisq_test_table(
  chisq_object,
  test_type = c("independence", "goodness-of-fit", "homogeneity"),
  digits = 3
)

Arguments

chisq_object

An object or list of objects of class "htest" produced by stats::chisq.test().

test_type

Character string specifying the type of chi-square test. One of "goodness-of-fit", "independence", or "homogeneity". for multiple object, if separate test_type are not provided than given test type will be uesd for all chi square test./

digits

Integer indicating the number of decimal places to round to.

Details

The function does not perform the chi-square test itself and does not introduce new statistical methods. All test statistics are extracted directly from the supplied chisq.test() object.

For goodness-of-fit tests, Cohen’s w is reported. For tests of independence and homogeneity, Cramér’s V is reported. Effect size interpretations follow conventional benchmarks (0.10 = small, 0.30 = medium, 0.50 = large).

Value

A single-row data frame with the following columns:

Examples

# Goodness-of-fit example
observed <- c(40, 30, 50)
chisq_gof <- chisq.test(observed)

make_chisq_test_table(
  chisq_object = chisq_gof,
  test_type = "goodness-of-fit"
)

# Independence test example
tbl <- matrix(c(20, 30, 10, 40), nrow = 2)
chisq_ind <- chisq.test(tbl)

make_chisq_test_table(
  chisq_object = chisq_ind,
  test_type = "independence"
)

Export a data frame to CSV, Word (.docx), or Excel (.xlsx) format.

Description

If no output path is specified, the file is written to a temporary directory using 'tempdir()'. For reproducible workflows, users are encouraged to explicitly specify an output location, either the current working directory or a full file path.

Usage

make_dataframe_to_output(data, filename = NULL, format = "csv", path = NULL)

Arguments

data

A data frame to export.

filename

Optional base file name (without extension). Defaults to object name. (without path and without extension). If not provided, the name of the input object is used.

format

Character string specifying the output format. One of '"csv"', '"word"', or '"excel"'. Default is '"csv"'.

path

Optional character string specifying the directory where the file should be saved. If 'NULL' (default), the file is written to a temporary directory. Use 'path = getwd()' to save the file in the current working directory, or provide a full directory path.

Details

- CSV files are written using 'utils::write.csv()' - Word files ('docx') are created using the 'officer' package - Excel ('xlsx') files are created using the 'openxlsx' package

Value

Invisibly returns the full file path to the generated output file.

Examples

## Not run: 

# Example dataset available in base R
data_df <- head(mtcars)

#--------------------------------------------------
# 1. Simplest use: export to CSV in temp directory
#--------------------------------------------------
make_dataframe_to_output(data_df)

#--------------------------------------------------
# 2. Specify filename
#--------------------------------------------------
make_dataframe_to_output(
  data = data_df,
  filename = "mtcars_sample"
)

#--------------------------------------------------
# 3. Export as Word document
#--------------------------------------------------
make_dataframe_to_output(
  data = data_df,
  filename = "mtcars_word_table",
  format = "word"
)

#--------------------------------------------------
# 4. Export as Excel file
#--------------------------------------------------
make_dataframe_to_output(
  data = data_df,
  filename = "mtcars_excel_table",
  format = "excel"
)

#--------------------------------------------------
# 5. Save to current working directory
#--------------------------------------------------
make_dataframe_to_output(
  data = data_df,
  filename = "mtcars_current_folder",
  format = "csv",
  path = "getwd()"
)

#--------------------------------------------------
# 6. Save Excel file to current working directory
#--------------------------------------------------
make_dataframe_to_output(
  data = data_df,
  filename = "mtcars_excel_current",
  format = "excel",
  path = "getwd()"
)

#--------------------------------------------------
# 7. Export another base dataset (iris)
#--------------------------------------------------
make_dataframe_to_output(
  data = head(iris),
  filename = "iris_sample",
  format = "word"
)

#--------------------------------------------------
# 8. Using a custom folder path
#--------------------------------------------------
make_dataframe_to_output(
  data = head(airquality),
  filename = "airquality_data",
  format = "excel",
  path = "D:/output_folder"
)


## End(Not run)

Create a demographics summary table

Description

Create a demographics summary table

Usage

make_demographic_table(data, vars, continuous_vars = NULL)

Arguments

data

A data frame

vars

demographic variables to include in the table

continuous_vars

Optional subset of vars to be treated as continuous

Value

A gtsummary table

Examples

df <- data.frame(
  age = c("25", "30 years", "35", " 40 ", "22.5", "28+", NA, ""),
  sex = c("M", "F", "m", "f", " M ", "F", "m", NA),
  education = c("HS", "BA", "MA", "ma", "Hs", "Ma", "Ba Bed", "Msc bed ")
)

# Generate a demographic summary table (assign to object to avoid printing)
demo_table <- make_demographic_table(df, vars = c("age", "sex", "education"))
demo_table # optionally inspect the table

Create and Export Demographic Summary Table

Description

Generates a demographic summary table using 'make_demographic_table()' and exports the resulting table to Word, Excel, or CSV format.

This is a convenience wrapper that combines analysis and output in a single step for users who want immediate file export.

Usage

make_demographic_table_to_output(
  data,
  vars,
  continuous_vars = NULL,
  file_name = "demographic_table",
  format = c("word", "excel", "csv"),
  path = NULL
)

Arguments

data

A data frame containing the dataset.

vars

Character vector of variable names to include in the demographic summary.

continuous_vars

Optional character vector specifying which variables should be treated as continuous. If 'NULL', numeric variables are automatically detected.

file_name

Name of the output file WITHOUT extension (e.g., "demographics").

format

Output format. Must be one of:

  • '"word"' - exports to a Word document (.docx)

  • '"excel"' - exports to an Excel file (.xlsx)

  • '"csv"' - exports to a CSV file (.csv)

path

Optional character string specifying the directory where the file should be saved. If 'NULL' (default), the file is written to a temporary directory. Provide a full directory path or use getwd() during the function call.

Details

The demographic table includes:

Word export uses 'flextable' and 'officer' for formatting. Excel export uses 'openxlsx'. CSV export uses base R 'write.csv()'.

Value

Invisibly returns the full file path to the generated output file.

Create a one-row summary table for an independent-samples t-test

Description

This function performs an independent-samples t-test (Welch's t-test by default) between two groups defined by a binary grouping variable and returns a single-row data frame. The output includes group names, sample sizes, mean difference, test statistics, p-value, and effect size (Cohen's d) with a qualitative interpretation.

Usage

make_independent_t_test_table(data, outcome, group)

Arguments

data

A data frame containing the outcome and grouping variables.

outcome

Character string specifying the numeric outcome variable.

group

Character string specifying the grouping variable. Must have exactly two levels.

Details

The function is intended for streamlined reporting and does not introduce new statistical methods. All computations rely on stats::t.test().

Welch’s t-test is used by default, which does not assume equal variances. Cohen’s d is computed using the pooled standard deviation for comparability with conventional benchmarks. Group ordering follows the factor level order of the grouping variable.

Value

A single-row data frame with the following columns:

Examples

set.seed(123)

data_t <- data.frame(
  group = rep(c("CBT", "Psychodynamic"), each = 30),
  score = c(
    rnorm(30, mean = 18, sd = 4),
    rnorm(30, mean = 21, sd = 4)
  )
)

make_independent_t_test_table(
  data = data_t,
  outcome = "score",
  group = "group"
)

Create a Summary Table for a One-Sample t-test

Description

Create a Summary Table for a One-Sample t-test

Usage

make_one_sample_t_test_table(t_res, variable_label = "Variable", digits = 3)

Arguments

t_res

An object of class "htest" produced by t.test(),or a list of such objects.

variable_label

A character string to label the tested variable(s).

digits

Integer indicating the number of decimal places to round to.

Value

A data frame summarizing the one-sample t-test results.

Examples

data("attitude")
A <- as.data.frame(attitude)

# Example 1: One-sample t-test with default mu = 0
t1 <- t.test(A$rating)
make_one_sample_t_test_table(
  t_res = t1,
  variable_label = "Rating"
)

# Example 2: One-sample t-test with specified mu
t2 <- t.test(A$rating, mu = 60)
make_one_sample_t_test_table(
  t_res = t2,
  variable_label = "Rating"
)

# Example 3: Multiple one-sample t-tests combined into one table
t1 <- t.test(A$rating)
t2 <- t.test(A$learning)
t3 <- t.test(A$raises)

make_one_sample_t_test_table(
  t_res = list(t1, t2, t3),
  variable_label = c("Rating", "Learning", "Raises")
)

# Example 4: Multiple tests with different mu values
t1 <- t.test(A$rating, mu = 60)
t2 <- t.test(A$learning, mu = 65)
t3 <- t.test(A$raises, mu = 50)

make_one_sample_t_test_table(
  t_res = list(t1, t2, t3),
  variable_label = c("Rating", "Learning", "Raises (mu = 50)")
)

Create a one-row summary table of a paired t-test

Description

This function performs a paired t-test between two numeric variables in a data frame and returns a one-row summary table including means, mean difference, t-value, degrees of freedom, p-value, and confidence interval.

Usage

make_paired_t_test_table(
  data,
  var1,
  var2,
  var_name = NULL,
  alternative = "two.sided",
  conf.level = 0.95
)

Arguments

data

A data frame containing the two numeric variables.

var1

Character string. Name of the first variable (observation 1) in 'data'.

var2

Character string. Name of the second variable (observation 2) in 'data'.

var_name

Optional character string. Custom name for the variable to display in the table. Default is 'var1 vs var2'.

alternative

Character string specifying the alternative hypothesis. One of '"two.sided"', '"less"', or '"greater"'. Default is '"two.sided"'.

conf.level

Confidence level for the interval. Default is 0.95.

Value

A one-row data frame with columns:

Examples

# example data
df <- data.frame(
  before = c(10, 12, 14, 15, 11),
  after  = c(11, 13, 13, 16, 12)
)

# Run the paired t-test summary
make_paired_t_test_table(df, var1 = "before", var2 = "after")

Create Reverse Scores as New Columns

Description

Create Reverse Scores as New Columns

Usage

make_reverse_score(data, vars, min_val, max_val, suffix = "_rev")

Arguments

data

A data frame.

vars

A character vector of column names to reverse.

min_val

The minimum possible score of the scale.

max_val

The maximum possible score of the scale.

suffix

A character string to append to the new column names. Defaults to "_rev".

Value

A data frame containing the original data plus the new reversed columns.

Create Descriptive Table for Multiple Scale Columns

Description

Computes descriptive statistics for one or more scale total columns. Accepts either a numeric vector (single column) or a data frame with column names.

Usage

make_scale_description_table(
  x = NULL,
  data = NULL,
  columns = NULL,
  scale_names = NULL,
  type = NULL
)

Arguments

x

Optional numeric vector of total scores (single column, old-style).

data

Optional data frame containing one or more scale columns.

columns

Optional character vector of column names in 'data' (new-style).

scale_names

Optional character vector of names for each scale. Defaults to column names.

type

"summary" for base::summary(), NULL (default) uses psych::describe().

Value

A data frame with one row per column, containing descriptive statistics.

Compute Scale Total Score

Description

Computes the total score for a psychometric scale by summing specified numeric variables. The resulting total score is appended as a new column to the input data frame. Missing values are handled using 'na.rm = TRUE'.

Usage

make_scale_total(data, vars, new_var)

Arguments

data

A data frame.

vars

A character vector of column names to be summed.

new_var

A single character string specifying the name of the new total score column.

Value

The input data frame with one additional numeric column.

scaledescr

Description

Provides helper functions to format and summarise already computed outputs from commonly used statistical and psychometric functions into compact, single-row tables and simple graphs. Functions such as make_scale_description_table(), make_demographic_table(), make_alpha_table(), make_paired_t_test_table(), and make_dataframe_to_output() organise results obtained from existing functions including psych::describe(), psych::alpha(), stats::t.test(), and gtsummary::tbl_summary() for streamlined reporting and export to CSV, Word, and Excel formats. The package does not implement new statistical methods or perform additional estimation.