Package 'earthUI'

Description

Saves the result via saveRDS() to ⁠<file_name>_earthUI_result_<timestamp>.rds⁠ and verifies the file is readable and can produce a prediction. If verification fails, the file is deleted. Skipped silently for models with degree > 2 (mgcvUI only supports pairwise interactions).

Usage

auto_export_for_mgcv(result, output_folder, file_name)

Arguments

Value

Invisibly, NULL.

Description

Converts an allowed interaction matrix into a function compatible with the allowed parameter of earth::earth(). The function checks that ALL pairwise combinations among the predictors in a proposed interaction term are TRUE in the matrix.

Usage

build_allowed_function(allowed_matrix, block_degree1 = NULL)

Arguments

Details

The returned function implements the standard earth() allowed function contract. When earth proposes a new hinge function involving predictor pred with existing parent predictors indicated by the parents logical vector, the function checks that every pair of involved predictors is allowed in the matrix.

For a 3-way interaction between X, Y, Z, the function verifies that (X,Y), (Y,Z), and (X,Z) are all TRUE in the matrix.

When block_degree1 is specified, any predictor in that list is blocked from entering as a degree-1 term but is allowed in higher-degree interactions (subject to the allowed matrix).

Value

A function with signature ⁠function(degree, pred, parents, namesx, first)⁠ suitable for the allowed parameter of earth::earth().

Examples

mat <- build_allowed_matrix(c("sqft", "bedrooms", "pool"))
mat["sqft", "pool"] <- FALSE
mat["pool", "sqft"] <- FALSE
func <- build_allowed_function(mat)

# Block sale_age from degree 1 (interaction only)
mat2 <- build_allowed_matrix(c("sale_age", "living_area", "lot_size"))
func2 <- build_allowed_function(mat2, block_degree1 = "sale_age")

Description

Creates a symmetric logical matrix indicating which pairs of predictors are allowed to interact. By default, all interactions are allowed.

Usage

build_allowed_matrix(variable_names, default = TRUE)

Arguments

Value

A symmetric logical matrix with variable_names as both row and column names.

Examples

mat <- build_allowed_matrix(c("sqft", "bedrooms", "pool"))
mat["sqft", "pool"] <- FALSE
mat["pool", "sqft"] <- FALSE
mat

Description

Generates a multi-sheet xlsx workbook formatted as a Sales Comparison Grid from an RCA-adjusted data frame. Each sheet shows the subject and up to three comparable sales side by side, with factual values, value contributions, and adjustments per regression variable, plus rows for grouped variables (location, site, age), residual feature inputs, and an Adjusted Sale Price formula.

Usage

build_sales_grid(
  rca_df,
  comp_rows,
  output_file,
  specials = list(),
  title_prefix = "Intermediate Sales Comparable Grid",
  progress_fn = NULL
)

Arguments

Details

This is the non-Shiny computation kernel used by the earthUI Shiny app's Sales Grid download button, and is also suitable for use from batch scripts that already have rca_df in memory.

Value

Invisibly, the output_file path.

Description

Applies the rule: lowercase + strip all non-alphanumerics + first 6 characters. If the resulting code already exists in existing_codes, append ⁠_1⁠, ⁠_2⁠, ... until unique.

Usage

city_abbreviation(full_name, existing_codes = character(0))

Arguments

Value

Character scalar.

Description

Returns an enhanced copy of data with per-target model columns appended: ⁠est_<target>⁠, residual, cqa, optional residual_sf / cqa_sf (when a living-area column is supplied), per-g-function ⁠<var>_contribution⁠ columns, basis, and calc_residual. For appraisal or market purposes, rows are sorted by residual_sf (or residual) descending, with the subject row (row 1) pinned on top when applicable. Ranking columns (residual_sf, cqa_sf, residual, cqa) are moved to the leftmost positions.

Usage

compute_intermediate_output(
  data,
  result = NULL,
  purpose = c("general", "appraisal", "market"),
  skip_subject_row = FALSE,
  living_area_col = NULL
)

Arguments

Details

This is the non-Shiny computation kernel used by the earthUI Shiny app's Download Intermediate Output button, and is also suitable for use from batch scripts.

Value

A data frame.

Description

Starting from the raw data (subject in row 1, comps in rows 2+) and a fitted earth model, produces the adjusted comparables data frame used by the Sales Comparison Grid. The user-supplied subject CQA score is converted into a subject residual via linear interpolation of the comp CQA/residual curve; per-g-function contributions and adjustments are then added for each comp, along with net/gross adjustments, percentages, and the final adjusted_sale_price.

Usage

compute_rca_adjustments(
  data,
  result,
  user_cqa,
  cqa_type = c("cqa", "cqa_sf"),
  living_area_col = NULL,
  weight_col = NULL
)

Arguments

Details

For multi-target models, the primary target drives the subject residual calculation. Additional targets receive their own residual interpolation and adjustment columns, imputed only for zero-weight rows.

This is the non-Shiny computation kernel used by the earthUI Shiny app's RCA Raw Output button, and is also suitable for use from batch scripts.

Value

An enhanced data frame with model columns, contributions, adjustments, subject_value, subject_cqa, and adjusted_sale_price.

Description

Given a vector of contract (sale) dates and a single effective date, returns the difference in integer days (effective_date - contract_date). Contract dates may be supplied as POSIXct, Date, character strings parseable by as.POSIXct(), or numeric Excel serial date numbers (origin 1899-12-30).

Usage

compute_sale_age(contract_vals, effective_date)

Arguments

Details

This function is the non-Shiny computation kernel used by the earthUI Shiny app when computing a sale_age column from a designated contract_date column. It is also suitable for use from batch scripts.

Value

An integer vector the same length as contract_vals, giving the number of whole days between effective_date and each contract date. NA contract values propagate to NA results.

Examples

compute_sale_age(
  contract_vals = as.Date(c("2024-01-15", "2024-06-01")),
  effective_date = as.Date("2025-01-01")
)

Description

Renders any .qmd file (not just earthUI-generated ones) to the requested formats via quarto::quarto_render(). Useful for converting hand-edited or manually-combined Quarto reports — e.g., a master document that uses ⁠{{< include >}}⁠ to pull in multiple project reports.

Usage

convert_quarto_file(
  qmd_path,
  formats = c("html"),
  output_dir = NULL,
  paper_size = "letter"
)

Arguments

Value

Invisibly, a character vector of output file paths.

Description

Returns a named character vector of country display names indexed by ISO 3166-1 alpha-2 code. Suitable for a selectInput choices list.

Usage

country_choices()

Value

Named character vector. Names are display names, values are lowercase 2-letter codes.

Description

Returns the ordered character vector of admin level labels for the given ISO 3166-1 alpha-2 country code. Used by the UI cascade and by regproj_path() to validate path depth.

Usage

country_schema(cc)

Arguments

Details

Unknown country codes return a generic 2-level fallback (c("region", "city")) so users in countries not yet covered by the shipped table still get a sensible cascade.

Value

Character vector of admin level labels, top to bottom.

Description

Resolution order:

1. REGPROJ_ROOT environment variable.

2. regproj_root field in user prefs (earthui_prefs_path()).

3. Per-OS default: ⁠C:/regProj⁠ on Windows; ⁠~/regProj⁠ elsewhere.

Usage

default_regproj_root()

Value

Character scalar. Absolute path.

Description

Returns a logical named vector indicating which columns are likely categorical. Character and factor columns are always flagged. Numeric columns with fewer than max_unique unique values are also flagged.

Usage

detect_categoricals(df, max_unique = 10L)

Arguments

Value

A named logical vector with one element per column. TRUE indicates the column is likely categorical.

Examples

df <- data.frame(
  price = c(100, 200, 300, 400),
  pool = c("Y", "N", "Y", "N"),
  bedrooms = c(2, 3, 2, 4),
  sqft = c(1200, 1500, 1300, 1800)
)
detect_categoricals(df)

Description

Inspects each column and returns a best-guess R type string. Character columns are tested for common date patterns. Numeric columns containing only 0/1 values (with both present) are flagged as logical.

Usage

detect_types(df)

Arguments

Value

A named character vector with one element per column. Possible values: "numeric", "integer", "character", "logical", "factor", "Date", "POSIXct", "unknown".

Examples

df <- data.frame(
  price = c(100.5, 200.3, 300.1),
  rooms = c(2L, 3L, 4L),
  pool  = c("Y", "N", "Y"),
  sold  = c(TRUE, FALSE, TRUE)
)
detect_types(df)

Description

Returns the path to ⁠<R_user_dir("earthUI","config")>/prefs.json⁠. The file holds user-level configuration that lives outside the regProj tree itself — most importantly, the location of the regProj root.

Usage

earthui_prefs_path()

Value

Character scalar.

Description

Read user preferences (returns empty list if file missing)

Usage

earthui_prefs_read()

Value

Named list.

Description

Write user preferences (atomic; creates the config dir if needed)

Usage

earthui_prefs_write(prefs)

Arguments

Value

Invisibly, the prefs path.

Description

The Shiny app persists per-file, per-purpose settings in a SQLite DB keyed by "<filename>||<purpose>". export_settings() reads that row and writes a single JSON file containing the full settings bundle (target, earth parameters, variable selections, type/special overrides, and interactions), plus an rca block for batch RCA inputs — the subject CQA score and CQA score type.

Usage

export_settings(filename, purpose, output_json)

Arguments

Details

If output_json already exists, the rca block of the existing file is preserved — re-exporting from the UI does not clobber hand-edited CQA inputs.

The emitted rca block has two fields:

cqa_score

null or a number in ⁠[0.00, 10.00]⁠.

cqa_score_type

"CQA/sf" (based on residual / living-area, default) or "CQA" (based on residual).

The emitted reports field is an array of formats to render in batch mode: any subset of "html", "pdf", "docx". An empty array ⁠[]⁠ (default) means no reports are generated.

Value

Invisibly, the output_json path.

Examples

## Not run: 
export_settings("Appraisal_1.csv", "appraisal",
                "~/configs/Appraisal_1.json")

## End(Not run)

Description

Wrapper around earth::earth() with parameter validation and automatic cross-validation when interaction terms are enabled.

Usage

fit_earth(
  df,
  target,
  predictors,
  categoricals = NULL,
  linpreds = NULL,
  type_map = NULL,
  degree = 1L,
  allowed_func = NULL,
  allowed_matrix = NULL,
  nfold = NULL,
  nprune = NULL,
  thresh = NULL,
  penalty = NULL,
  minspan = NULL,
  endspan = NULL,
  fast.k = NULL,
  pmethod = NULL,
  glm = NULL,
  trace = NULL,
  nk = NULL,
  newvar.penalty = NULL,
  fast.beta = NULL,
  ncross = NULL,
  stratify = NULL,
  varmod.method = NULL,
  varmod.exponent = NULL,
  varmod.conv = NULL,
  varmod.clamp = NULL,
  varmod.minspan = NULL,
  keepxy = NULL,
  Scale.y = NULL,
  Adjust.endspan = NULL,
  Auto.linpreds = NULL,
  Force.weights = NULL,
  Use.beta.cache = NULL,
  Force.xtx.prune = NULL,
  Get.leverages = NULL,
  Exhaustive.tol = NULL,
  wp = NULL,
  weights = NULL,
  ...,
  .capture_trace = TRUE
)

Arguments

Value

A list with class "earthUI_result" containing:

model

The fitted earth model object.

target

Name of the response variable.

predictors

Names of predictor variables used.

categoricals

Names of categorical predictors.

degree

Degree of interaction used.

cv_enabled

Logical; whether cross-validation was used.

data

The data frame used for fitting.

Examples

# Using the included demo appraisal dataset
demo_file <- system.file("extdata", "Appraisal_1.csv", package = "earthUI")
df <- import_data(demo_file)
result <- fit_earth(df, target = "sale_price",
                    predictors = c("living_sqft", "lot_size", "age"))
format_summary(result)

Description

Extracts the ANOVA table from a fitted earth model.

Usage

format_anova(earth_result)

Arguments

Value

A data frame with the ANOVA decomposition showing which predictors contribute to each basis function and their importance.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
format_anova(result)

Description

Converts a fitted earth model into a LaTeX-formatted mathematical representation using g-function notation. Basis functions are grouped by degree (constant, first-degree, second-degree, third-degree) and labeled with indices that encode the group, position, and factor variable count.

Usage

format_model_equation(earth_result, digits = 7L, response_idx = NULL)

Arguments

Value

A list containing:

latex

Character string. LaTeX array environment for HTML/MathJax rendering.

latex_inline

Character string. Wrapped in display math delimiters for MathJax/HTML rendering.

latex_pdf

Character string. LaTeX for native PDF output with escaped special characters in text blocks.

latex_word

Character string. LaTeX for Word/docx output.

groups

List of group structures for programmatic access.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
eq <- format_model_equation(result)
cat(eq$latex)

Description

Extracts key statistics from a fitted earth model including coefficients, basis functions, R-squared, GCV, GRSq, and RSS.

Usage

format_summary(earth_result)

Arguments

Value

A list containing:

coefficients

Data frame of model coefficients and basis functions.

r_squared

Training R-squared.

gcv

Generalized cross-validation value.

grsq

Generalized R-squared (1 - GCV/variance).

rss

Residual sum of squares.

n_terms

Number of terms in the pruned model.

n_predictors

Number of predictors used in the final model.

n_obs

Number of observations.

cv_rsq

Cross-validated R-squared (if CV was used, else NA).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
summary_info <- format_summary(result)
summary_info$r_squared

Description

Extracts variable importance scores from a fitted earth model using earth::evimp().

Usage

format_variable_importance(earth_result)

Arguments

Value

A data frame with columns variable, nsubsets, gcv, and rss, sorted by overall importance (nsubsets).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
format_variable_importance(result)

Description

Writes a self-contained Quarto project under ⁠<dest_dir>/<base>_qmd/⁠ containing the populated ⁠<base>.qmd⁠ source, all pre-generated plots (PNG + PDF), the report data RDS, and reference.docx for Word rendering. The resulting bundle can be edited or combined with other Quarto sources, then rendered to HTML / Word / PDF via convert_quarto_file().

Usage

generate_quarto_report(earth_result, dest_dir, base = "earth_report")

Arguments

Details

Use this when you want the Quarto source as a first-class artifact — e.g., to combine reports from multiple projects into a master document before publishing.

Value

Invisibly, the absolute path to the generated .qmd file.

Description

Reads model settings for a project from ⁠<REGPROJ_ROOT>/projects.sqlite⁠. Used by the Shiny UI to restore settings on file open, and by external tools (ValEngr, batch scripts) to inspect project state. Settings are scoped by project + purpose and are shared across all data files in the project (a small test extract and the full dataset share one config).

Usage

get_project_settings(
  project_path,
  method = "earth",
  purpose = "general",
  root = default_regproj_root()
)

Arguments

Value

Named list with settings, variables, and (for earth) interactions (each a JSON string), or NULL if no row exists.

Description

Reads a CSV (.csv) or 'Excel' (.xlsx, .xls) file and returns a data frame. Column names are converted to snake_case and duplicates are made unique.

Usage

import_data(filepath, sheet = 1, sep = ",", dec = ".", ...)

Arguments

Value

A data frame with column names converted to snake_case. Duplicate column names are made unique by appending numeric suffixes.

Examples

# Load the included demo appraisal dataset
demo_file <- system.file("extdata", "Appraisal_1.csv", package = "earthUI")
df <- import_data(demo_file)
head(df)

Description

Returns TRUE if path exists, sits two directories deep under root (⁠<purpose>/<flat_segment>/⁠), and the flat segment parses cleanly.

Usage

is_project_dir(path, root = default_regproj_root())

Arguments

Value

Logical scalar.

Description

Opens an interactive 'shiny' GUI for building and exploring 'earth' (MARS-style) models. The application provides data import, variable configuration, model fitting, result visualization, and report export.

Usage

launch(port = 7878L, ...)

Arguments

Value

This function does not return a value; it launches the Shiny app.

Examples

if (interactive()) {
  launch()
}

Description

Returns a data frame describing each non-intercept g-function group from the model equation, including degree, factor count, graph dimensionality, and the number of terms. The g-function notation is ${}^{f}g^{j}_{k}$ where f = number of factor variables (top-left), j = degree of interaction (top-right), k = position within the degree group (bottom-right).

Usage

list_g_functions(earth_result)

Arguments

Value

A data frame with columns:

index

Integer. Sequential index (1-based).

label

Character. Variable names in the group.

g_j

Integer. Degree of the g-function (top-right superscript).

g_k

Integer. Position within the degree (bottom-right subscript).

g_f

Integer. Number of factor variables (top-left superscript).

d

Integer. Graph dimensionality (degree minus factor count).

n_terms

Integer. Number of terms in the group.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
list_g_functions(result)

Description

Returns "mac" on Darwin, "ubuntu" on Linux, "win11" on Windows. This is the value used as the ⁠<os>⁠ segment in regProj paths so that multi-OS output can be merged cleanly on a developer's machine.

Usage

os_detect()

Value

Character scalar: "mac", "ubuntu", or "win11".

Description

Creates a scatter plot of actual vs predicted values with a 1:1 reference line.

Usage

plot_actual_vs_predicted(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_actual_vs_predicted(result)

Description

Creates a scatter plot showing each variable's actual contribution to the prediction. For each observation, the contribution is the sum of coefficient * basis function value across all terms involving that variable.

Usage

plot_contribution(earth_result, variable, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_contribution(result, "wt")

Description

Creates a heatmap of pairwise correlations among the target variable and numeric predictors, with cells colored by degree of correlation and values printed in each cell.

Usage

plot_correlation_matrix(earth_result)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_correlation_matrix(result)

Description

Creates a ggplot2 visualization for any g-function group. For d <= 1, produces a 2D scatter plot (same as plot_g_function()). For d >= 2, produces a filled contour plot suitable for static formats like PDF and Word.

Usage

plot_g_contour(earth_result, group_index, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_g_contour(result, 1)

Description

Creates a contribution plot for a specific g-function group. For degree-1 groups (single variable), produces a 2D scatter + piecewise-linear plot with slope labels and knot markers. For degree-2 groups (two variables), produces a 3D surface plot using plotly if available, or a filled contour plot.

Usage

plot_g_function(earth_result, group_index, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object for d <= 1, or a plotly widget for d >= 2 (when plotly is installed). Falls back to ggplot2 contour if plotly is not available.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_g_function(result, 1)

Description

Creates a base R persp() 3D surface plot for g-function groups with d >= 2. For d <= 1, produces a 2D scatter plot (same as plot_g_function()). The surface is colored by contribution value using a blue-white-red scale. Suitable for PDF and Word output where interactive plotly is not available.

Usage

plot_g_persp(
  earth_result,
  group_index,
  theta = 30,
  phi = 25,
  response_idx = NULL
)

Arguments

Value

Invisible NULL (base graphics). For d <= 1, returns a ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"), degree = 2L)
plot_g_persp(result, 1)

Description

Creates a partial dependence plot for a selected variable from a fitted earth model.

Usage

plot_partial_dependence(
  earth_result,
  variable,
  n_grid = 50L,
  response_idx = NULL
)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_partial_dependence(result, "wt")

Description

Creates a normal Q-Q plot of the model residuals.

Usage

plot_qq(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_qq(result)

Description

Creates a two-panel diagnostic plot: residuals vs fitted values and a Q-Q plot of residuals.

Usage

plot_residuals(earth_result, response_idx = NULL)

Arguments

Value

A ggplot2::ggplot object showing residuals vs fitted values. Use plot_qq() for the Q-Q plot separately.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_residuals(result)

Description

Creates a horizontal bar chart of variable importance from a fitted earth model.

Usage

plot_variable_importance(earth_result, type = "nsubsets")

Arguments

Value

A ggplot2::ggplot object.

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
plot_variable_importance(result)

Description

Pre-generates all plots and data for the earth model report. Returns the path to a directory containing all assets. This directory can be passed to render_report() to avoid re-computing anything during rendering.

Usage

prepare_report_assets(earth_result, assets_dir = NULL)

Arguments

Value

The path to the assets directory (invisibly).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
assets <- prepare_report_assets(result)

Description

Joins country, admin levels, and project name with ⁠_⁠ to produce the single hierarchy-encoding folder name used at the project level under ⁠<root>/<purpose>/⁠. Validates each component: admin codes must match ⁠^[a-z0-9-]+$⁠ (no internal underscores), project name allows ⁠^[A-Za-z0-9_-]+$⁠.

Usage

regproj_flat_segment(country, levels, project_name)

Arguments

Value

Character scalar (e.g. "us_ca_081_burlin_20251231_j").

Description

Returns a DBI connection. Creates the schema on first call. The caller is responsible for DBI::dbDisconnect().

Usage

regproj_geo_db_connect(root = default_regproj_root())

Arguments

Details

On first creation, the tables are seeded from:

• the shipped reference data (regproj_reference()) — 24 countries, 51 US states, 3,076 US counties.

• the shipped places data (pkg/inst/extdata/regproj_geo.rds) — US incorporated places + GeoNames-derived city/admin data for GB, DE, IT, FR, SE, SG.

• any pre-existing ⁠<REGPROJ_ROOT>/.regproj-index.json⁠ (legacy migration).

Value

A DBIConnection to the SQLite database.

Description

⁠<REGPROJ_ROOT>/geo.sqlite⁠ — holds country codes and a flexible, variable-depth admin_entries table for state / county / city / deeper-level admin codes per country. Travels with the regProj tree.

Usage

regproj_geo_db_path(root = default_regproj_root())

Arguments

Value

Character scalar.

Description

Returns the basenames of regular files in ⁠<project_path>/<os>_in/⁠. Hidden dotfiles and subdirectories are excluded. Sorted alphabetically.

Usage

regproj_in_files(project_path, os = os_detect())

Arguments

Value

Character vector of file basenames.

Description

Looks up full_name under scope (e.g. "us/ca") in the geo SQLite DB (which is seeded with shipped reference data on first creation). Returns NULL if not found.

Usage

regproj_index_get(scope, full_name, root = default_regproj_root())

Arguments

Value

Character scalar code, or NULL.

Description

The geo data is now stored in ⁠<REGPROJ_ROOT>/geo.sqlite⁠ (see regproj_geo_db_path()). This path returns the location of the legacy .regproj-index.json file, which is migrated into the SQLite DB on first connect and is no longer written to.

Usage

regproj_index_path(root = default_regproj_root())

Arguments

Value

Character scalar.

Description

Inserts (or replaces) the mapping under the given scope.

Usage

regproj_index_put(scope, full_name, code, root = default_regproj_root())

Arguments

Value

Invisibly, the code.

Description

Returns the entire geo DB as a nested list keyed by scope (slash- separated parent-code path), for backward compatibility with callers that iterate. New code should prefer regproj_index_get() or direct DB queries via regproj_geo_db_connect().

Usage

regproj_index_read(root = default_regproj_root())

Arguments

Value

Named list. Outer key is scope ("" for countries, then slash-separated codes per admin level). Inner key is full name; value is the code.

Description

Deprecated. The geo data is now in SQLite; this is a no-op kept for backward compatibility.

Usage

regproj_index_write(idx, root = default_regproj_root())

Arguments

Value

Invisibly, the geo DB path.

Description

Stores the basename of the most-recently-selected input file in ⁠<project>/<os>/.regproj-last⁠, so it can be auto-selected the next time the project is opened.

Usage

regproj_last_file_path(project_path, os = os_detect())

regproj_last_file_get(project_path, os = os_detect())

regproj_last_file_set(project_path, basename, os = os_detect())

Arguments

Value

Path / basename / invisible path.

Description

Walks ⁠<root>/<purpose>/<country>/<state>/<county>/<city>/<project_name>/⁠ and returns a data frame describing each project found, with its mtime (most recent of the in/ and out/ trees, falling back to the project folder itself).

Usage

regproj_list_projects(
  root = default_regproj_root(),
  sort_by = c("recent", "alpha")
)

Arguments

Details

Recognized purposes: gen, appr, mktarea. Other top-level subdirectories under ⁠<root>⁠ are ignored, including any leading-dot files like .regproj-index.json.

Value

Data frame with columns: project_path (absolute), purpose, country, state, county, city, project_name, mtime (POSIXct). Empty data frame (correct columns, zero rows) if no projects exist or root is missing.

Description

Inverse of regproj_flat_segment(). Splits on ⁠_⁠, takes the first token as country, then the next length(country_schema(country)) tokens as admin levels; the remaining tokens (joined by ⁠_⁠) are the project name. Returns NULL on parse failure.

Usage

regproj_parse_flat(segment)

Arguments

Value

Named list with country, levels (character vector), project_name — or NULL if parsing failed.

Description

Composes the path ⁠<root>/<purpose>/<flat_segment>/<os>_<in|out>[_<method>]⁠ from its components. The hierarchy (country / admin levels / project name) is concatenated into a single folder under ⁠<purpose>/⁠ to keep the tree shallow. Pure path computation — does not create any directories unless create = TRUE.

Usage

regproj_path(
  purpose,
  country,
  levels,
  project_name,
  os = os_detect(),
  in_or_out = c("out", "in"),
  method = "earth",
  root = default_regproj_root(),
  create = FALSE
)

Arguments

Value

Character scalar. Absolute normalized path.

Description

Returns a DBI connection. Creates the schema on first call. The caller is responsible for DBI::dbDisconnect().

Usage

regproj_projects_db_connect(root = default_regproj_root())

Arguments

Value

A DBIConnection to the SQLite database.

Description

⁠<REGPROJ_ROOT>/projects.sqlite⁠ — one row per project, keyed by the flat segment (e.g. "us_ca_081_burlin_20251231_j"). Holds project metadata and per-method settings as JSON blobs.

Usage

regproj_projects_db_path(root = default_regproj_root())

Arguments

Value

Character scalar.

Description

Reads pkg/inst/extdata/regproj_reference.json once per session and caches the result. Contains country names, US states, and US counties (with FIPS codes). Used by the UI cascades to populate dropdowns.

Usage

regproj_reference()

Value

A nested list with components version, countries, states, counties.

Description

Renders a parameterized 'Quarto' report from the fitted 'earth' model results. Requires the 'quarto' R package and a 'Quarto' installation.

Usage

render_report(
  earth_result,
  output_format = "html",
  output_file = NULL,
  paper_size = "letter",
  assets_dir = NULL
)

Arguments

Value

The path to the rendered output file (invisibly).

Examples

result <- fit_earth(mtcars, "mpg", c("cyl", "disp", "hp", "wt"))
render_report(result, output_format = "html",
              output_file = tempfile(fileext = ".html"))

Description

Given an RCA-adjusted data frame (subject in row 1, comps in rows 2+), builds comp-summary tables, filters by weight, sorts by gross adjustment percentage, splits into "recommended" (gross adjustment < threshold) and "others", and caps the recommended list.

Usage

select_sales_grid_comps(
  rca_df,
  sale_age_col = "sale_age",
  min_weight = 0,
  max_gross_adj_pct = 0.25,
  max_recommended = 30L
)

Arguments

Details

This is the non-Shiny computation kernel used by the earthUI Shiny app's Sales Grid modal, and is also suitable for use from batch scripts.

Value

A named list with:

recommended

Data frame of recommended comps, sorted by sale_age ascending, capped at max_recommended rows.

others

Data frame of eligible comps not in the recommended set, sorted by gross_adj_pct ascending.

Each data frame has columns: row, id, address, sale_price, sale_age, weight, gross_adj, gross_adj_pct.

Description

Writes model settings for a project to ⁠<REGPROJ_ROOT>/projects.sqlite⁠. Used by the Shiny UI to persist settings, and by external tools to seed projects programmatically. Settings are scoped by project + purpose and shared across all data files in the project.

Usage

set_project_settings(
  project_path,
  settings = NULL,
  variables = NULL,
  interactions = NULL,
  method = "earth",
  purpose = "general",
  root = default_regproj_root()
)

Arguments

Value

Invisibly, NULL.

Description

Checks each selected predictor's actual data against the user-declared type. Returns a list of errors (blocking), warnings (non-blocking), and any Date/POSIXct columns that will be auto-converted to numeric.

Usage

validate_types(df, type_map, predictors)

Arguments

Value

A list with components:

ok

Logical. TRUE if no blocking errors found.

warnings

Character vector of non-blocking warnings.

errors

Character vector of blocking errors.

date_columns

Character vector of Date/POSIXct predictor columns that will be auto-converted to numeric.

Examples

df <- data.frame(price = c(100, 200, 300), city = c("A", "B", "C"))
types <- list(price = "numeric", city = "character")
validate_types(df, types, predictors = c("price", "city"))

Description

Writes the model print-out, summary.earth(), and optional variance model / trace log to ⁠<file_name>_earth_output_<timestamp>.txt⁠ in output_folder.

Usage

write_earth_output(result, output_folder, file_name)

Arguments

Value

Invisibly, NULL.

Description

Writes the timestamped contents of an earth fitting trace to ⁠<file_name>_earth_log_<timestamp>.txt⁠ in output_folder. If output_folder is NULL or empty, ⁠~/Downloads⁠ is used. The folder is created if it doesn't exist. Errors are caught and reported via message() so batch pipelines don't fail on logging issues.

Usage

write_fit_log(output_folder, lines, file_name)

Arguments

Value

Invisibly, NULL.