Package index • pakhom

Run an Analysis

Top-level entry points. run_analysis() drives Modes 2 + 3 (data -> coding -> sentiment -> themes -> correlations -> report -> finalize_run). run_mode1() drives Mode 1 (Reflexive Scaffold) with the same transparency and methodology scaffolding but routes through the provocateur loop. Both produce a finalized run directory with full audit trail and HTML report.

run_analysis(): Run the full thematic analysis pipeline (Mode 2 + Mode 3)
run_mode1(): Run a Mode 1 (Reflexive Scaffold) provocateur analysis
load_config(): Load analysis configuration from YAML file
create_config(): Create a minimal configuration file
config_wizard(): Interactive configuration wizard
config_wizard_app(): Launch the interactive configuration wizard

Methodology Modes

The three methodologically-distinct operating modes, the framework spec module (Mode 3), the provocateur loop (Mode 1), and reflexive memo management for Mode 1.

run_provocateur_questioning(): Run provocateur questioning across themes (Mode 1 entry point)
load_framework_spec(): Load + validate a theoretical framework specification
list_builtin_frameworks(): List the built-in frameworks shipped with pakhom
archive_framework_spec(): Archive a Mode 3 framework spec into the run output directory
framework_prompt_block(): Build the prompt block describing the framework's constructs
apply_framework_themes(): Apply framework constructs as themes + handle anomalies (Mode 3)
make_memo(): Construct a Memo S3 object
add_memo(): Add a memo to a ResearcherReflectionLog
read_memo(): Read a memo from a ResearcherReflectionLog by id
list_memos(): List memos in a ResearcherReflectionLog as a tibble
persist_memos(): Persist all memos in a ResearcherReflectionLog to disk
load_memos(): Load memos from a run output directory back into Memo objects
memo_to_markdown(): Serialize a Memo to a Markdown string with YAML frontmatter
markdown_to_memo(): Parse a Markdown-with-YAML-frontmatter string back into a Memo
create_reflection_log(): Initialize a ResearcherReflectionLog
make_provocation(): Construct a Provocation object
provoke_counter_narrative(): Counter-narrative provocation
provoke_disconfirming_evidence(): Disconfirming-evidence provocation
provoke_alternative_interpretation(): Alternative-interpretation provocation
provoke_absent_voice(): Absent-voice provocation
provoke_assumption_surfacing(): Assumption-surfacing provocation

Mandatory Transparency Layer (Quotes, Coverage, Provenance)

Quote provenance with a verification ladder, participant spread per theme, and whole-corpus coverage with no silently skipped entries. Shared across the codebook, framework, and reflexive modes.

make_quote(): Construct a Quote provenance object
verify_quote(): Verify a quote against its source text via the verification ladder
quote_provenance_summary(): Summarize quote provenance for the report's Tier-0 dashboard
compute_quote_provenance_stats(): Aggregate verification stats across all coded segments in a coding state
compute_corpus_coverage(): Compute corpus coverage from a completed coding run
compute_mode1_coverage(): Compute Mode 1 (Reflexive Scaffold) coverage from a finished provocateur run
compute_mode1_theme_stats(): Compute per-theme statistics for a Mode 1 run
compute_provocation_provenance_stats(): Aggregate verification stats across all provocations in a reflection log
render_tier0_coverage_card(): Render the Tier-0 coverage card for a coverage object
init_fabrication_log(): Initialize the fabrication log
log_fabrication(): Append a fabricated quote to the fabrication log
make_quote_from_citation(): Construct a QuoteProvenance from a single Anthropic citation
make_quotes_from_citations(): Construct QuoteProvenance objects from a list of Anthropic citations
verify_quotes(): Verify a batch of quotes against a corpus
write_corpus_coverage(): Persist a CorpusCoverage / ProvocationCoverage object to disk

Methodological Transparency Report

A self-contained HTML methodological transparency report bundling Lincoln & Guba (1985) trustworthiness mapping, reflexivity completeness, quote provenance summary, corpus coverage funnel, audit log summary, and theme set summary. Reads disk artifacts only; never re-runs the pipeline.

bundle_transparency_report(): Bundle a run's transparency artifacts into a single report

Methodology Decision Aids

User-facing helpers for choosing a methodology mode and for annotating plots / reports with the mode and provenance evidence.

methodology_decision_aid(): Methodology decision aid
configuration_selection_aid(): Configuration-selection aid
methodology_plot_caption(): Build a caption string suitable for use as a ggplot watermark

Run State and Soft-Lock

Every run is either active or finalized, and the methodology mode is locked once a run is finalized so it cannot silently change between states. Fork a run via clone_run_with_new_mode().

init_run_state(): Initialize the run-metadata record for a new (or resumed) run
read_run_metadata(): Read and parse run_metadata.json for a run directory
is_run_finalized(): Check whether a run directory is finalized
finalize_run(): Mark a run as finalized
methodology_mismatch_status(): Detect a methodology mismatch between a config and an existing run
clone_run_with_new_mode(): Clone a run directory with a new methodology mode

Output Stamping

Methodology stamping helpers. Every CSV / JSON / HTML / plot produced by a run carries the mode + run id stamp so a reviewer reading any artifact alone sees the methodology declaration.

stamp_methodology_html(): Build an HTML methodology badge for the report header
stamp_methodology_csv(): Stamp a CSV file with a methodology comment header
stamp_methodology_json(): Stamp a JSON file with a methodology envelope
stamp_methodology_console(): Build a console banner string for the methodology mode
methodology_label(): Human-readable label for a methodology mode
methodology_short_code(): Map a methodology mode to its short-code (M1 / M2 / M3)
methodology_description_short(): One-line description of what the mode commits the AI to
run_id_with_mode(): Build a Mode N run-directory suffix for a fresh run

Methodology Rules

Methodology rules generated from config and injected into the model context every turn, following the Lin and Corley (2025) pattern.

generate_methodology_rules(): Generate the methodology-rules text for a config
write_methodology_rules(): Write methodology rules to a markdown file under run_dir

S3 Print Methods

print() dispatchers for the package’s S3 classes. Each is invoked automatically when you print(x) an object of the corresponding class; they are documented here for reference.

print(<AIProvider>): Print method for AIProvider
print(<CheckpointManager>): Print method for CheckpointManager
print(<Code>): Print method for Code
print(<ComparisonResult>): Print method for ComparisonResult
print(<CorpusCoverage>): Print method for CorpusCoverage
print(<FrameworkSpec>): Print method for FrameworkSpec
print(<LiveTracker>): Print method for LiveTracker
print(<Memo>): Print method for Memo
print(<Provocation>): Print method for Provocation
print(<ProvocationCoverage>): Print method for ProvocationCoverage
print(<QuoteProvenance>): Print method for QuoteProvenance
print(<ResearcherReflectionLog>): Print method for ResearcherReflectionLog
print(<ResponseCache>): Print method for ResponseCache
print(<Subtheme>): Print method for Subtheme
print(<ThematicConfig>): Print method for ThematicConfig
print(<ThemeSet>): Print method for ThemeSet

Internal Helpers

Documented internal helpers used by the pipeline. Listed for completeness; not part of the user-facing API and may change without notice.

detect_columns(): Detect and map columns based on platform type
export_theme_entry_csvs(): Export CSV files for each theme's entries
generate_ai_synthesis(): Generate AI-powered executive summary and conclusion
generate_downloads_section(): Generate downloads appendix section
generate_insights(): Generate AI insights from correlation findings
generate_run_id(): Generate a unique run ID based on timestamp (UTC).
get_emotion_interpretation(): Get interpretation text for an emotion
hash_config(): Compute a hash of a config file for change detection
load_and_combine_tables(): Load and combine multiple tables from a SQLite database
make_anchor_id(): Create an HTML anchor ID from a string
make_safe_filename(): Create a safe filename from a string
parse_json_safely(): Parse JSON safely with automatic repair for truncated/malformed responses
parse_raw_data_files(): Parse raw data DOCX files and extract metadata from filenames
preprocess_text(): Preprocess text data for analysis
standardize_data(): Standardize data to common schema
truncate_text(): Truncate text to specified length with ellipsis
validate_config(): Validate configuration completeness and correctness
.LIVE_CODEBOOK_SNAPSHOT_EVERY: Default codebook-snapshot rewrite cadence
.THEME_DEFAULTS: Default values for optional theme fields
.THEME_REQUIRED_FIELDS: Required fields for each theme within a ThemeSet

Configuration

Configuration creation, validation, and defaults

default_config(): Create a default configuration object
validate_methodology_mode(): Validate a methodology mode declaration

Data Loading & Exploration

Load data from SQLite and explore databases

load_data(): Load data from a SQLite database
load_corpus_from_config(): Load and preprocess a corpus from a pakhom configuration
explore_database(): Explore a SQLite database schema
detect_variable_types(): Detect variable types for dynamic correlation method selection

AI Provider

AI provider abstraction for OpenAI and Anthropic

create_ai_provider(): Create an AI provider client
cache_response(): Write a raw API response to the cache, indexed by prompt_hash
init_response_cache(): Initialize a content-addressable response cache
read_cached_response(): Read a cached raw response by prompt_hash

Pipeline Steps

Individual analysis steps (called by run_analysis)

run_progressive_coding(): Run progressive sequential coding on all entries
create_coding_state(): Create a new progressive coding state
get_analytic_sample(): Get the analytic sample (entries that received at least one code)
analyze_sentiment(): Run batch sentiment analysis on all entries
generate_themes_iterative(): Generate themes by grouping codes into AI-judged clusters
generate_themes_multipass(): Generate themes via multi-pass clustering + label-after-clustering
cascade_theme_assignments(): Cascade theme assignments from codes to entries deterministically
enrich_themes(): Enrich themes with entry counts, sentiment, and quotes
calculate_correlations(): Calculate correlation matrix with p-values

Themes & Theme Data

Working with ThemeSet objects and Code / Subtheme accessors

create_theme_set(): Create a ThemeSet object (canonical internal representation)
create_code_object(): Create a Code S3 object
create_subtheme(): Create a Subtheme S3 object
theme_names(): Extract theme names from ThemeSet
n_themes(): Get the number of themes
theme_set_to_tibble(): Convert ThemeSet to tibble for export/inspection
normalize_theme_result(): Normalize raw AI theme output to canonical ThemeSet
prune_empty_themes(): Remove themes with zero assigned entries after enrichment
theme_codes(): Flatten code names across all subthemes of a theme (back-compat with codes_included)
theme_code_keys(): Flatten code keys across all subthemes of a theme
theme_code_objects(): Flatten Code S3 objects across all subthemes (and sub-subthemes) of a theme
theme_segments(): Flatten coded_segments across all codes of a theme
theme_n_subthemes(): Number of TOP-LEVEL real subthemes in a theme (excludes virtual wrappers)
theme_n_subthemes_total(): Total real (named) subthemes across every depth of a theme
subtheme_code_names(): Code names (display) within a Subtheme
subtheme_code_keys(): Code keys within a Subtheme
subtheme_n_codes(): Number of DIRECT codes in a Subtheme (excludes nested sub-subthemes)
subtheme_n_codes_total(): Number of codes in a Subtheme INCLUDING nested sub-subthemes
subtheme_n_subthemes(): Number of nested subthemes within a Subtheme

Checkpoint & Resume

Save and restore pipeline progress

init_checkpoints(): Initialize checkpoint system for a pipeline run
save_checkpoint(): Save checkpoint at a given pipeline step
save_partial_checkpoint(): Save partial checkpoint within a step (for long-running batch operations)
load_checkpoint(): Load checkpoint for a step
list_checkpoints(): List available checkpoints with metadata
find_latest_run(): Find the most recent run folder in the results directory
find_resume_point(): Determine the last completed step for resume

Manuscript Learning

Learn from prior manual thematic analyses

load_previous_studies(): Load all previous studies from a base directory
generate_learning_context(): Generate task-specific learning context from previous analyses
generate_learning_reflection(): Generate AI reflection on what was learned from previous studies
discover_study_folders(): Discover study folders matching a pattern
extract_manuscript_sections(): Extract structured sections from manuscript text
parse_manuscript(): Parse a finalized themes manuscript (DOCX or PDF)

Human Verification

Inter-rater reliability and code verification

run_human_verification(): Run human verification / IRR process
verify_excerpts(): Verify coded excerpts against source text

Report & Export

HTML report, CSV/JSON exports, and QDA-software interoperability

generate_report(): Generate the full HTML analysis report
generate_mode1_report(): Generate the Mode 1 (Reflexive Scaffold) HTML analysis report
export_results(): Export all analysis results to files
export_qdpx(): Export coding results to QDPX format
export_theme_subtheme_summary_csvs(): Export per-theme paper-style subtheme-summary CSVs

Comparison

Compare results across pipeline runs and across AI models

compare_runs(): Compare the current run against all previous runs
compare_models(): Compare runs that used different AI models for inter-model reliability
list_available_runs(): List available analysis runs
compare_theme_groups(): Compare continuous variables across theme groups using Mann-Whitney U tests

Temporal Analysis

Within-run longitudinal analysis when entries have timestamps

analyze_temporal_patterns(): Analyse temporal patterns in theme prevalence within a single run
generate_temporal_plots(): Generate PNG plots for temporal analysis results

Audit Log

JSONL trail of every AI decision for post-hoc transparency review

init_audit_log(): Initialize the AI decision audit log
close_audit_log(): Close the audit log file connection
log_ai_decision(): Record a single AI decision in the audit log
log_ai_request(): Record an AI request with the structured response from ai_complete
summarize_audit_log(): Summarize the AI decision audit log

Mode 1 Live Tracking

Live in-memory tracking of Mode 1 (reflexive scaffold) provocation progress so the orchestrator can monitor cluster coverage and code assignments mid-run.

init_live_tracker(): Initialize the live tracker for a run
live_record_assignment(): Record one (entry, code, segment) assignment to the live tracker
live_record_clustering_pass(): Record one clustering-pass snapshot to the live tracker (C3)
live_snapshot_codebook(): Snapshot the current codebook to codebook_live.json
live_snapshot_clusters(): Snapshot the current theme/cluster hierarchy to code_to_cluster.json

Statistical Analysis

Correlation and co-occurrence helpers

aggregate_overall_statistics(): Aggregate overall analysis statistics for report
aggregate_theme_statistics(): Aggregate per-theme statistics for report
test_theme_cooccurrence(): Test theme co-occurrence patterns with chi-square tests of independence
create_theme_network(): Create theme co-occurrence network visualization
create_correlation_plot(): Create correlation plot
interpret_correlations(): Interpret correlation results for reporting
prepare_correlation_data(): Prepare data for correlation analysis
extract_significant(): Extract significant correlations as tidy tibble

Scraper

Reddit data collection

scrape_reddit(): Scrape Reddit subreddits into a SQLite database

Pipeline Integrity

Verify pipeline run integrity

verify_run_integrity(): Verify that a run directory contains all expected output files

Pipeline Step Helpers

Exported functions called from inside the pipeline that researchers may also call directly for finer control (e.g., feeding external coding state through enrichment + cascade independently).

as_coding_results(): Convert ProgressiveCodingState to legacy CodingResults format
compute_coding_benchmarks(): Compute empirical coding benchmarks from parsed QDA codebooks
enrich_themes(): Enrich themes with entry counts, sentiment, and quotes
parse_codebook(): Parse a QDA software codebook export (NVivo, ATLAS.ti, MAXQDA, or generic)

Package

pakhom-package pakhom: pakhom: AI-Assisted Thematic Analysis with Methodology-as-Architecture