Package 'scimagR'

Description

Replaces identifying header fields (PatientName, PatientID, PatientBirthDate, etc.) and removes private tags. Saves an ID mapping CSV to a user-specified secure location.

Usage

anonymize_dicom(
  dicom_dir,
  mapping_csv,
  prefix = "SCI",
  python = Sys.getenv("PYTHON_BIN", "python3")
)

Arguments

Details

WARNING: This modifies DICOM files in-place. Create a backup first. The mapping CSV must NOT be stored in the project directory.

Value

Exit code (invisible).

Examples

## Not run: 
anonymize_dicom("data/raw/dicom", "/secure/id_mapping.csv")

## End(Not run)

Description

Verifies that dcm2niix is installed and on PATH.

Usage

check_dcm2niix(verbose = TRUE)

Arguments

Value

Named list with components: available, version, path.

Examples

## Not run: 
check_dcm2niix()

## End(Not run)

Description

Verifies that Python 3 with pydicom is available.

Usage

check_pydicom(python = Sys.getenv("PYTHON_BIN", "python3"), verbose = TRUE)

Arguments

Value

Named list with components: available, version, path.

Examples

## Not run: 
check_pydicom()

## End(Not run)

Description

Verifies that SCT is installed and on PATH. Returns version and path information.

Usage

check_sct(verbose = TRUE)

Arguments

Value

Named list with components:

• available: Logical.

• version: Character. Version string or NA.

• path: Character. Path to sct_version executable or NA.

Examples

## Not run: 
check_sct()

## End(Not run)

Description

Maps integer grades 0–4 to an ordered factor:

• 0: none

• 1: mild

• 2: moderate

• 3: severe

• 4: non-evaluable

Usage

classify_artifact(grade)

Arguments

Value

Ordered factor with 5 levels: none < mild < moderate < severe < non-evaluable.

Examples

classify_artifact(c(0, 1, 2, 3, 4))

Description

Classification based on established SCI literature (Grassner et al. 2025, Freund et al. 2019):

• <= 1 day: hyperacute

• 2–14 days: acute

• 15–90 days: subacute

• 91–365 days: intermediate

• more than 365 days: chronic

Usage

classify_phase(days)

Arguments

Value

Ordered factor with 5 levels: hyperacute < acute < subacute < intermediate < chronic.

Examples

classify_phase(c(0, 5, 30, 200, 400))

Description

Calculates the ratio of anterior-posterior to transverse diameter.

Usage

compute_compression_ratio(ap, transverse)

Arguments

Value

Numeric. Compression ratio (unitless). NA if transverse <= 0 or any input is NA.

Examples

compute_compression_ratio(ap = 6.5, transverse = 12.0)

Description

Calculates the ratio of CSA at the injury level to the reference CSA (average of adjacent levels).

Usage

compute_csa_ratio(csa_injury, csa_above, csa_below)

Arguments

Value

Numeric. CSA ratio (unitless). NA if reference is <= 0 or any input is NA.

Examples

compute_csa_ratio(csa_injury = 45, csa_above = 70, csa_below = 72)

Description

Calculates MSCC using the formula:

$MSCC = (1 - d_i / ((d_a + d_b) / 2)) \times 100$

Usage

compute_mscc(di, da, db)

Arguments

Value

Numeric. MSCC percentage. NA if any input is NA or if the reference diameter is <= 0.

Examples

compute_mscc(di = 5.2, da = 8.1, db = 8.5)
compute_mscc(di = 0, da = 8, db = 8) # 100% compression

Description

Iterates over a registry and converts all sessions from DICOM to NIfTI.

Usage

convert_batch(
  registry,
  dicom_root,
  nifti_root,
  compress = TRUE,
  verbose = TRUE
)

Arguments

Value

Tibble with columns: pat_id, session, status, n_files.

Examples

## Not run: 
convert_batch(registry, "data/raw/dicom", "data/nifti")

## End(Not run)

Description

Converts a single session's DICOM files to NIfTI format using dcm2niix.

Usage

convert_dcm2niix(dicom_dir, output_dir, compress = TRUE, verbose = TRUE)

Arguments

Value

Character vector of output NIfTI paths.

Examples

## Not run: 
convert_dcm2niix("data/raw/dicom/SCI001/ses-01", "data/nifti/SCI001/ses-01")

## End(Not run)

Description

Shows which patients have which modalities at which timepoints.

Usage

coverage_matrix(registry)

Arguments

Value

Tibble in wide format with one row per patient and one column per session containing the modality.

Examples

## Not run: 
reg <- validate_registry("imaging_registry.csv", strict = FALSE)
cm <- coverage_matrix(reg)

## End(Not run)

Description

Creates an empty QC log tibble or reads an existing one from CSV.

Usage

create_qc_log(path = NULL)

Arguments

Value

Tibble with QC log columns: pat_id, session, rater, date, seg_type, quality, notes.

Examples

qc <- create_qc_log()

Description

Takes raw DICOM metadata (from extract_dicom_metadata()), restructures it into a proper imaging registry with computed fields (days_post_trauma, phase classification), and optionally saves to CSV.

Usage

create_registry(dicom_meta, trauma_dates, op_dates = NULL, output_csv = NULL)

Arguments

Value

Tibble with registry columns.

Examples

## Not run: 
meta <- read.csv("dicom_metadata.csv")
trauma <- c(SCI001 = "2024-01-15", SCI002 = "2024-02-20")
reg <- create_registry(meta, trauma)

## End(Not run)

Description

Walks a DICOM directory tree and extracts key header fields (StudyDate, Modality, SeriesDescription, FieldStrength, etc.) from the first DICOM file per session.

Usage

extract_dicom_metadata(
  dicom_dir,
  output_csv,
  python = Sys.getenv("PYTHON_BIN", "python3")
)

Arguments

Value

Character. Path to output CSV (invisible).

Examples

## Not run: 
extract_dicom_metadata("data/raw/dicom", "data/metadata/dicom_metadata.csv")

## End(Not run)

Description

Filters a dataset to sessions that meet artifact grade and modality criteria for analysis.

Usage

filter_evaluable(
  df,
  max_artifact = 2,
  modalities = c("MRT", "CT+MRT"),
  verbose = TRUE
)

Arguments

Value

Filtered data frame.

Examples

## Not run: 
evaluable <- filter_evaluable(registry, max_artifact = 2)

## End(Not run)

Description

Reports dimensions, missing values per column, and duplicate count for a data frame. Returns the data frame invisibly for piping.

Usage

integrity_summary(df, id_cols = NULL)

Arguments

Value

Invisibly returns df.

Examples

## Not run: 
registry |> integrity_summary(id_cols = c("pat_id", "session"))

## End(Not run)

Description

Records before/after row counts and reason for an exclusion step. Useful for building a CONSORT-style exclusion flow.

Usage

log_exclusion(step, n_before, n_after, reason = "")

Arguments

Value

A 1-row tibble with columns: step, n_before, n_after, n_excluded, reason.

Examples

log_exclusion("Artifact filter", 100, 85, "artifact_grade > 2")

Description

Named character vector of 5 colours for MRI artifact grades: none (green), mild (yellow), moderate (orange), severe (red), non-evaluable (grey).

Usage

pal_artifact

Examples

pal_artifact

Description

Named character vector of 3 colours for imaging modalities.

Usage

pal_modality

Examples

pal_modality

Description

Named character vector of 5 viridis-derived colours for SCI phases: hyperacute, acute, subacute, intermediate, chronic.

Usage

pal_phase

Examples

pal_phase

Description

Creates a tile plot showing modality coverage per patient and session, with optional artifact grade overlay.

Usage

plot_coverage(registry)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
plot_coverage(registry)

## End(Not run)

Description

Creates a forest plot for comparing model estimates with confidence intervals. Useful for sensitivity analysis comparisons.

Usage

plot_forest(estimates_df, xlab = "Estimate", title = NULL, vline = 0)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
est <- data.frame(
  model = c("Full", "Sensitivity 1", "Sensitivity 2"),
  estimate = c(-2.1, -1.9, -2.3),
  ci_lower = c(-3.5, -3.4, -3.8),
  ci_upper = c(-0.7, -0.4, -0.8)
)
plot_forest(est)

## End(Not run)

Description

Shows individual patient trajectories over time with an optional group-level smoother.

Usage

plot_spaghetti(df, x, y, group, colour = NULL, smoother = TRUE, title = NULL)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
plot_spaghetti(df, x = "days_post_trauma", y = "csa",
               group = "pat_id", colour = "phase")

## End(Not run)

Description

Creates a violin plot with embedded boxplot (no outlier points) and jittered individual data points. Uses viridis palette by default.

Usage

plot_violin_box(df, x, y, fill = x, title = NULL, ylab = y)

Arguments

Value

A ggplot2 object.

Examples

## Not run: 
plot_violin_box(df, x = "phase", y = "mscc", fill = "phase")

## End(Not run)

Description

Saves a ggplot2 plot at publication-ready resolution with white background.

Usage

save_fig(plot, filename, path, width = 7, height = 5, dpi = 600)

Arguments

Value

Character. Full path to saved file (invisible).

Examples

## Not run: 
p <- ggplot2::ggplot(mtcars, ggplot2::aes(wt, mpg)) + ggplot2::geom_point()
save_fig(p, "test_plot.png", tempdir())

## End(Not run)

Description

Saves any R object as .rds with a confirmation message.

Usage

save_rds(obj, filename, path)

Arguments

Value

Character. Full path to saved file (invisible).

Examples

## Not run: 
save_rds(mtcars, "cars.rds", tempdir())

## End(Not run)

Description

Saves a data frame as .xlsx via writexl.

Usage

save_table(df, filename, path)

Arguments

Value

Character. Full path to saved file (invisible).

Examples

## Not run: 
save_table(mtcars, "cars.xlsx", tempdir())

## End(Not run)

Description

Colour and Fill Scales for Artifact Grades

Usage

scale_colour_artifact(...)

scale_fill_artifact(...)

Arguments

Value

A ggplot2 scale object.

Description

Colour and Fill Scales for Imaging Modalities

Usage

scale_colour_modality(...)

scale_fill_modality(...)

Arguments

Value

A ggplot2 scale object.

Description

Convenience wrappers around ggplot2::scale_colour_manual() and ggplot2::scale_fill_manual() using pal_phase.

Usage

scale_colour_phase(...)

scale_fill_phase(...)

Arguments

Value

A ggplot2 scale object.

Examples

## Not run: 
ggplot(df, aes(x, y, colour = phase)) + geom_point() + scale_colour_phase()

## End(Not run)

Description

Sets up a complete workflowr project with full directory structure, pre-configured YAML files, template Rmd files, CSV templates, and a .gitignore tuned for neuroimaging projects.

Usage

sci_create_project(
  path,
  title = "SCI Imaging Analysis",
  author = "Author Name",
  seed = 20260411L,
  open = TRUE
)

Arguments

Value

Character. Path to created project (invisible).

Examples

## Not run: 
sci_create_project("~/projects/my-sci-study",
  title = "Cervical SCI Longitudinal MRI Analysis",
  author = "Raban Heller")

## End(Not run)

Description

Scans the project directory and reports which processing steps are complete for each patient and session.

Usage

sci_pipeline_status(project_dir)

Arguments

Value

Tibble with columns: pat_id, session, converted, sc_seg, lesion_seg, vert_labels, qc_done, params_extracted.

Examples

## Not run: 
sci_pipeline_status("~/projects/my-sci-study")

## End(Not run)

Description

Orchestrates all external tool steps in sequence:

1. DICOM metadata extraction

2. Anonymization (if requested)

3. DICOM to NIfTI conversion

4. Spinal cord segmentation

5. Lesion segmentation (SCIsegV2)

6. Vertebral labeling

7. Parameter extraction

8. Merge & export

Usage

sci_run_pipeline(
  project_dir,
  steps = 1:8,
  anonymize = FALSE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Details

Each step checks for existing outputs (idempotent). The pipeline can be interrupted and resumed at any step.

Value

Tibble with pipeline status per step.

Examples

## Not run: 
sci_run_pipeline("~/projects/my-sci-study", steps = 1:3)

## End(Not run)

Description

Runs sct_analyze_lesion to compute lesion volume, length, max axial damage ratio, and tissue bridge measurements.

Usage

sct_analyze_lesion(lesion_seg, sc_seg, output_dir = NULL, verbose = TRUE)

Arguments

Value

Character. Path to output CSV, or NA on failure.

Examples

## Not run: 
sct_analyze_lesion("sub-01_lesion_seg.nii.gz", "sub-01_seg.nii.gz")

## End(Not run)

Description

Creates an HTML QC report overlaying a segmentation on the original image.

Usage

sct_generate_qc(
  input,
  segmentation,
  qc_dir,
  process = "sct_deepseg",
  verbose = TRUE
)

Arguments

Value

Exit code (invisible).

Examples

## Not run: 
sct_generate_qc("sub-01_T2w.nii.gz", "sub-01_T2w_seg.nii.gz", "qc/")

## End(Not run)

Description

Runs SCT's vertebral labeling on a spinal cord segmentation.

Usage

sct_label_vertebrae(
  input,
  segmentation,
  contrast = "t2",
  output_dir = NULL,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

Value

Character. Path to vertebral label NIfTI, or NA on failure.

Examples

## Not run: 
sct_label_vertebrae("sub-01_T2w.nii.gz", "sub-01_T2w_seg.nii.gz")

## End(Not run)

Description

Runs sct_process_segmentation to compute cross-sectional area (CSA), AP diameter, and transverse diameter per vertebral level.

Usage

sct_process_segmentation(
  sc_seg,
  vert_labels,
  output_dir = NULL,
  perslice = FALSE,
  verbose = TRUE
)

Arguments

Value

Character. Path to output CSV, or NA on failure.

Examples

## Not run: 
sct_process_segmentation("sub-01_seg.nii.gz", "sub-01_labels-disc.nii.gz")

## End(Not run)

Description

Runs SCIsegV2 lesion segmentation model via SCT.

Usage

sct_segment_lesion(
  input,
  output = NULL,
  output_dir = NULL,
  overwrite = FALSE,
  verbose = TRUE,
  qc_dir = NULL
)

Arguments

Value

Character. Path to output lesion segmentation, or NA on failure.

Examples

## Not run: 
sct_segment_lesion("sub-01_T2w.nii.gz")

## End(Not run)

Description

Runs SCT's contrast-agnostic spinal cord segmentation model.

Usage

sct_segment_sc(
  input,
  output = NULL,
  output_dir = NULL,
  overwrite = FALSE,
  verbose = TRUE,
  qc_dir = NULL
)

Arguments

Value

Character. Path to output segmentation file, or NA on failure.

Examples

## Not run: 
sct_segment_sc("sub-01_T2w.nii.gz")

## End(Not run)

Description

A clean ggplot2 theme based on ggplot2::theme_bw(), optimized for publication-ready neuroimaging figures. Uses Arial font, no minor gridlines, and a bottom legend.

Usage

theme_sci(base_size = 11, base_family = "Arial")

Arguments

Value

A ggplot2 theme object.

Examples

## Not run: 
library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) + geom_point() + theme_sci()

## End(Not run)

Description

Adds one or more QC entries to a QC log.

Usage

update_qc_log(qc_log, entries, output_csv = NULL)

Arguments

Value

Updated QC log tibble.

Examples

## Not run: 
qc <- create_qc_log()
entry <- tibble::tibble(
  pat_id = "SCI001", session = "ses-01", rater = "RH",
  date = Sys.Date(), seg_type = "sc", quality = "good", notes = ""
)
qc <- update_qc_log(qc, entry)

## End(Not run)

Description

Checks required columns and valid quality values.

Usage

validate_qc_log(qc_log)

Arguments

Value

Invisibly returns the validated QC log.

Description

Checks: required columns present, no duplicate pat_id x session, dates are valid, days_post_trauma >= 0, artifact_grade in 0–4, modality in allowed values.

Usage

validate_registry(registry, strict = TRUE)

Arguments

Value

Invisibly returns the validated registry tibble.

Examples

## Not run: 
validate_registry("data/metadata/imaging_registry.csv")

## End(Not run)