R API¶

Part of API Reference — MORIE API reference.

Reference for every public function exported by the morie R package. Signatures and descriptions come from the Roxygen2 .Rd files in r-package/morie/man/; see Statistical Methods for the methodology behind each function.

Causal estimators¶

Note

Documentation for R function estimate_aipw() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_atc() is pending. Run roxygen2 to generate the .Rd file.

IPW-weighted OLS ATE

Usage

estimate_ate(data, outcome, treatment, weights_col)

Arguments

data: Data frame containing the analytical sample.
outcome: Name of the outcome column.
treatment: Name of the binary treatment column.
weights_col: Name of the weights column (e.g. IPTW).

Returns

Named list with ate and se (HC3-robust).

Note

Documentation for R function estimate_att() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_cate() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_g_computation() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_gate() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_late() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function estimate_propensity_scores() is pending. Run roxygen2 to generate the .Rd file.

Effect sizes + tests¶

Note

Documentation for R function anova_one_way() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function chi_square_test() is pending. Run roxygen2 to generate the .Rd file.

Cohen’s d for independent samples

Usage

cohens_d(x, y, confidence = 0.95)

Arguments

x, y: Numeric vectors (NA dropped).
confidence: Confidence level for CI. Default 0.95.

Returns

A morie_effect_size.

Cramer’s V for a contingency table

Usage

cramers_v(contingency_table, confidence = 0.95)

Arguments

contingency_table: Numeric matrix or table.
confidence: Confidence level. Default 0.95.

Returns

A morie_effect_size.

Wraps pkg{EValue} when available. Otherwise applies the same continuous-scale z-stat -> RR approximation as the Python port.

Usage

e_value(ate, se, null = 0)

Arguments

ate: Point estimate of the treatment effect.
se: Standard error of the ATE (must be > 0).
null: Null value. Default 0.

Returns

Scalar E-value (>= 1).

Note

Documentation for R function effective_sample_size() is pending. Run roxygen2 to generate the .Rd file.

Eta-squared from ANOVA sums of squares

Usage

eta_squared(ss_effect, ss_total)

Arguments

ss_effect: Sum of squares for the effect.
ss_total: Total sum of squares.

Returns

A morie_effect_size.

Fisher’s exact test for a 2x2 table

Usage

fisher_exact_test(contingency_table, alternative = "two.sided")

Arguments

contingency_table: 2x2 matrix.
alternative: One of “two.sided”, “less”, “greater”.

Returns

A morie_test_result (subclass of morie_rich_result) with the odds ratio as the test statistic and estimate, the exact p-value, and the table total as n.

Applies J = 1 - 3 / (4 * df - 1).

Usage

hedges_g(x, y, confidence = 0.95)

Arguments

x, y: Numeric vectors (NA dropped).
confidence: Confidence level for CI. Default 0.95.

Returns

A morie_effect_size.

Note

Documentation for R function kendall_tau() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function kruskal_wallis_test() is pending. Run roxygen2 to generate the .Rd file.

Levene’s test for equality of variances

Usage

levene_test(..., center = "median")

Arguments

...: Two or more numeric vectors.
center: One of “median” (Brown-Forsythe), “mean”, “trimmed”.

Returns

A morie_test_result (subclass of morie_rich_result) with Levene’s F statistic, p-value, df, and total sample size n.

Note

Documentation for R function mann_whitney_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function odds_ratio_ci() is pending. Run roxygen2 to generate the .Rd file.

Omega-squared — less biased than eta-squared

Usage

omega_squared(ss_effect, ss_total, df_effect, ms_error)

Arguments

ss_effect, ss_total: Sums of squares.
df_effect: Numerator d.f. of the effect.
ms_error: Error mean square.

Returns

A morie_effect_size.

Note

Documentation for R function one_sample_t_test() is pending. Run roxygen2 to generate the .Rd file.

Survey + sampling¶

Note

Documentation for R function bootstrap_sample() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function calibration_weights() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function cluster_sample() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function compute_design_weights() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function design_effect() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function generate_synthetic_data() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function jackknife_estimate() is pending. Run roxygen2 to generate the .Rd file.

Datasets + I/O¶

Note

Documentation for R function canonicalize_cpads_data() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function load_cpads_data() is pending. Run roxygen2 to generate the .Rd file.

Query Perseus via Python

Usage

morie_ask_percy(
  question,
  context = NULL,
  python_bin = Sys.getenv("MORIE_PYTHON_BIN", "python3")
)

morie_assistant_query(
  question,
  context = NULL,
  python_bin = Sys.getenv("MORIE_PYTHON_BIN", "python3")
)

Arguments

question: User question.
context: Optional context string.
python_bin: Python executable to use. Defaults to MORIE_PYTHON_BIN or python3.

Returns

Agent text response.

Examples

# See the package vignettes for usage examples:
#   vignette(package = "morie")

Returns the path to morie.db that ships with the package (inst/extdata/morie.db). This database contains all CPADS, CCS, CSADS, CSUS, HealthInfobase, and CIHI datasets pre-loaded as SQLite tables.

Usage

morie_builtin_db()

Returns

File path string.

Examples

morie_builtin_db()

Reads a local file and writes it to the cache so that CI and Docker environments (which may lack the original files) can still run tests.

Usage

morie_cache_file(path, table_name, db_path = NULL, con = NULL)

Arguments

path: Path to a CSV or RDS file.
table_name: Name for the cached table.
db_path: Optional path to a SQLite file (default backend).
con: Optional pre-opened DBI connection (overrides db_path).

Returns

Number of rows cached (invisible).

Examples

tdir <- tempfile("morie-cache-")
dir.create(tdir)
f <- file.path(tdir, "demo.csv")
write.csv(data.frame(x = 1:3, y = 4:6), f, row.names = FALSE)
morie_cache_file(f, "demo", db_path = file.path(tdir, "cache.db"))

List all tables in the MORIE cache

Usage

morie_cache_list(db_path = NULL, con = NULL)

Arguments

db_path: Optional path to a SQLite file (default backend).
con: Optional pre-opened DBI connection (overrides db_path).

Returns

A data.frame with columns table and rows.

Examples

\donttest{
db <- tempfile(fileext = ".db")
morie_cache_store(data.frame(x = 1:3), "demo", db_path = db)
morie_cache_list(db_path = db)
file.remove(db)
}

Load a table from the MORIE cache

Usage

morie_cache_load(table_name, db_path = NULL, con = NULL)

Arguments

table_name: Name of the table.
db_path: Optional path to a SQLite file (default backend).
con: Optional pre-opened DBI connection (overrides db_path).

Returns

A data.frame, or NULL if the table does not exist.

Examples

\donttest{
db <- tempfile(fileext = ".db")
morie_cache_store(
  data = data.frame(x = 1:5),
  table_name = "demo",
  db_path = db
)
morie_cache_load(table_name = "demo", db_path = db)
file.remove(db)
}

Writes (or replaces) a table in the shared SQLite cache.

Usage

morie_cache_store(data, table_name, db_path = NULL, con = NULL)

Arguments

data: A data.frame to cache.
table_name: Name of the destination table.
db_path: Optional path to a SQLite file (default backend).
con: Optional pre-opened DBI connection. When supplied, the table is written through con and db_path is ignored. Use this for non-SQLite backends (PostgreSQL, DuckDB, MariaDB).

Returns

Number of rows written (invisible).

Examples

\donttest{
db <- tempfile(fileext = ".db")
morie_cache_store(
  data = data.frame(x = rnorm(50), y = rnorm(50)),
  table_name = "demo",
  db_path = db
)
file.remove(db)
}

Returns a data.frame describing every dataset available through the MORIE data management system. Each row maps a short catalog key to its source, survey, year, file format, local path, SQLite table name, and CKAN resource ID (if available).

Usage

morie_dataset_catalog()

Returns

A data.frame with 44 rows (one per dataset) and columns: key, name, source, survey, year, format, type, large_file, local_path, table_name, ckan_resource_id, download_url, zip_member. The download_url / zip_member columns are empty for datasets reachable through the SQLite cache or the CKAN datastore.

Details

Keys match the Python DATASET_CATALOG in data.py exactly. Use ``morie_load_dataset`` to load by key.

Examples

cat <- morie_dataset_catalog()
nrow(cat)
head(cat[, c("key", "name", "source", "year")])
# Find Ontario carceral datasets:
cat[
  grepl("OTIS|Ontario", paste(cat$source, cat$survey)),
  c("key", "year")
]

Get metadata for a single dataset

Usage

morie_dataset_info(key)

Arguments

key: Dataset catalog key (or fuzzy match).

Returns

A named list with dataset metadata.

Examples

# Use a real catalog key (run `morie_dataset_catalog()$key` to list them):
info <- morie_dataset_info("ocp21")
info$source
info$year
# Fuzzy match works for partial / forgiving keys:
morie_dataset_info("cpads")$key

Opens (or creates) the per-user cache database. The default backend is strong{DuckDB} — zero-config like SQLite, but vectorised + columnar, so it handles the multi-GB-scale open-data PUMFs (TPS, CPADS bulk) that morie ingests without breaking down on analytical queries. For back-compat, an existing SQLite cache at morie.db is reused; if duckdb is unavailable, falls back to SQLite.

Usage

morie_db_connect(db_path = NULL)

Arguments

db_path: Optional path to a DuckDB (*.duckdb) or SQLite (*.db) file. Defaults to the MORIE_CACHE_DB env var, else morie.duckdb / morie.db in the per-user cache directory.

Returns

A DBI connection object.

Details

For non-default backends (PostgreSQL, MariaDB, MS SQL Server, …), construct your own DBI connection and pass it as con to the verb{morie_cache_*} and morie_load_dataset functions:

preformatted{ con <- DBI::dbConnect(RPostgres::Postgres(),

host = “…”, dbname = “morie”, user = “…”, password = “…”)

morie_load_dataset(“ocp21”, con = con) }

Examples

\donttest{
# DuckDB (default when 'duckdb' is installed); pass a '.db' path for SQLite.
if (requireNamespace("duckdb", quietly = TRUE) &&
  requireNamespace("DBI", quietly = TRUE)) {
  tmp <- tempfile(fileext = ".duckdb")
  con <- morie_db_connect(db_path = tmp)
  DBI::dbListTables(con)
  DBI::dbDisconnect(con)
  file.remove(tmp)
}
}

Downloads large bootstrap weight CSVs that are too big to ship with the package. Data is cached in the user cache database for future use.

Usage

morie_download_bootstrap(
  survey = "all",
  limit = 32000L,
  db_path = NULL,
  con = NULL
)

Arguments

survey: One of "csads_2021", "csads_2023", "csus_2019", "csus_2023", or "all" (default).
limit: Max records per CKAN request (default 32000).
db_path: Optional path to a SQLite/DuckDB file (default backend).
con: Optional pre-opened DBI connection (overrides db_path).

Returns

Invisibly, the number of CSV files successfully downloaded.

Examples

\donttest{
# See the package vignettes for usage examples:
#   vignette(package = "morie")
}

Fetch data from the CKAN API and cache it

Usage

morie_fetch_ckan(
  dataset_key = "cpads",
  limit = Inf,
  db_path = NULL,
  resource_id = NULL,
  con = NULL
)

Arguments

dataset_key: One of "cpads", "csads", "csus".
limit: Maximum records to fetch. The CKAN datastore caps a single request at 32000 rows, so larger resources are paged through with offset; the default reads the entire resource.
db_path: Optional override for the database path.
resource_id: Optional CKAN datastore resource id. When supplied (e.g. from morie_dataset_catalog()$ckan_resource_id) it is used directly, so any catalogued dataset can be fetched without a built-in database; dataset_key then only labels the cache table.
con: Optional pre-opened DBI connection (overrides db_path).

Returns

A data.frame.

Examples

\dontrun{
# Requires network access. Fetches the first 5000 rows of the
# Canadian Postsecondary Alcohol and Drug Use Survey from the
# Government of Canada CKAN datastore:
cpads <- morie_fetch_ckan(dataset_key = "cpads", limit = 5000L)
nrow(cpads)
}

List all datasets with cache status

Usage

morie_list_datasets(db_path = NULL, con = NULL)

Arguments

db_path: Optional path to a SQLite/DuckDB file (default backend).
con: Optional pre-opened DBI connection (overrides db_path).

Returns

A data.frame with columns: key, name, source, survey, year, type, cached (logical), rows (integer or NA).

Examples

morie_list_datasets()

Resolution order: enumerate{ item Local RDS/CSV files in standard project locations item SQLite cache (data/cache/morie.db) item CKAN API fetch (requires internet) }

Usage

morie_load_cpads(db_path = NULL, use_ckan = TRUE, con = NULL)

Arguments

db_path: Optional path to a SQLite/DuckDB file (default backend).
use_ckan: Logical; if TRUE and data not found locally or in cache, attempt to fetch from the CKAN API.
con: Optional pre-opened DBI connection (overrides db_path).

Returns

A data.frame with canonical CPADS columns.

Examples

\dontrun{
# Needs the CPADS PUMF (local file, cache, or a live CKAN fetch).
cpads <- morie_load_cpads(use_ckan = TRUE)
if (!is.null(cpads)) head(cpads)
}

Resolution tiers, tried in order: built-in DB -> user cache -> local file -> CKAN datastore -> direct download URL -> ArcGIS layer -> error. Supports fuzzy matching: morie_load_dataset("cpads_2021") resolves to ocp21.

Usage

morie_load_dataset(key, db_path = NULL, refresh = FALSE, con = NULL)

Arguments

key: Dataset catalog key (or fuzzy match).
db_path: Optional path to a SQLite/DuckDB file (default backend).
refresh: If TRUE, bypass the built-in database and the user cache (and, for remotely-backed datasets, the local file) and re-fetch from the remote source, overwriting the cached copy. Use this to pick up time-to-time updates to a dataset.
con: Optional pre-opened DBI connection for the user cache (overrides db_path). The built-in DB read is always SQLite-based and is unaffected by con.

Returns

A data.frame.

Examples

\dontrun{
df <- morie_load_dataset("ocp21") # CPADS 2021-2022 (default DuckDB cache)
df <- morie_load_dataset("ocp21", refresh = TRUE) # force re-fetch

# PostgreSQL cache (run a server first):
# con <- DBI::dbConnect(RPostgres::Postgres(),
#   host = "localhost", dbname = "morie", user = "...")
# df <- morie_load_dataset("ocp21", con = con)
}

Resolve standard project paths

Usage

morie_paths(project_root = NULL)

Arguments

project_root: Project root directory. If NULL, inferred from the current working directory.

Returns

Named list of key paths.

Examples

tryCatch(morie_paths(),
  error = function(e) message("not inside a morie project tree")
)

Lists or retrieves bundled userguide PDF files. These are the official PUMF codebooks and user guides from Health Canada / Statistics Canada.

Usage

morie_userguide(name = NULL)

Arguments

name: Filename (e.g., "20212022-cpads-pumf-user-guide.pdf"). If NULL, lists all available userguides.

Returns

File path string, or character vector of filenames.

Examples

morie_userguide()

Workflow + audit¶

Note

Documentation for R function ask_percy() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function audit_public_outputs() is pending. Run roxygen2 to generate the .Rd file.

Build a Perseus agent prompt

Usage

morie_build_prompt(question, context = NULL)

build_assistant_prompt(question, context = NULL)

Arguments

question: User question.
context: Optional context string.

Returns

Character scalar prompt.

Examples

# See the package vignettes for usage examples:
#   vignette(package = "morie")

Note

Documentation for R function build_outputs_manifest() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function build_prompt() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function cpads_contract() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function default_synthetic_name_map() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function default_workflow_map() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function find_project_root() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function list_morie_modules() is pending. Run roxygen2 to generate the .Rd file.

Other¶

Note

Documentation for R function paired_t_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function point_biserial_r() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function power_prop_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function power_t_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function pps_sample() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function proportion_ci() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function read_outputs_manifest() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function risk_difference_ci() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function risk_ratio_ci() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_ebac_selection_ipw_analysis() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_morie_module() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_morie_modules() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_pipeline() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_propensity_ipw_analysis() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function run_workflow_step() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function sample_size_logistic() is pending. Run roxygen2 to generate the .Rd file.

Wraps pkg{rbounds} when available; otherwise computes normal- approximation Wilcoxon signed-rank bounds in base R.

Usage

sensitivity_rosenbaum(
  data,
  treatment,
  outcome,
  covariates,
  gamma_range = c(1, 3),
  n_gamma = 20L
)

Arguments

data: Data frame with treatment + outcome columns.
treatment: Binary treatment column (0/1).
outcome: Outcome column.
covariates: Covariates (used only for matching approximation, here a simple rank-match).
gamma_range: c(min, max) of Gamma. Default c(1, 3).
n_gamma: Number of Gamma values. Default 20.

Returns

Data frame with Gamma, p_lower, p_upper.

Note

Documentation for R function shapiro_wilk_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function simple_random_sample() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function spearman_rho() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function stratified_sample() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function summarize_output_audit() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function two_sample_t_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function validate_cpads_data() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function validate_outputs_manifest() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function wilcoxon_signed_rank_test() is pending. Run roxygen2 to generate the .Rd file.

Note

Documentation for R function write_synthetic_data() is pending. Run roxygen2 to generate the .Rd file.

MORIE

Table of Contents

Related Topics

R API¶

Causal estimators¶

Effect sizes + tests¶

Survey + sampling¶

Datasets + I/O¶

Workflow + audit¶

Other¶