Skip to contents

hsquared

R interface · Julia engine · a twin, not a port

How much is genetic?

Formula first. The engine returns heritability, variance components, and breeding values on the routes that are covered. A route is a named model type with its own validation evidence (for example the default univariate animal model). Covered is a validation status: that evidence passed, so point estimates may be reported in that scope. Experimental 0.9.0 release, not production. CRAN availability is tracked separately.

Get started Choose a model Fit a model

Before you report anything

Warning — experimental 0.9.0 release. Not production. CRAN availability is tracked separately. There are 7 R-public covered routes; public_covered_count is that ledger total, not a function you can call. Fitting needs local Julia and an HSquared.jl checkout. Julia engine-covered ≠ R-public covered (the engine can validate a path that R does not yet expose as reportable). Report point estimates only within a covered route. No interval is nominally coverage-calibrated (the share of intervals that contain the truth is not shown to be 95%); named univariate pedigree intervals are only classified as directional-conservative (they tend to be at least as wide as a nominal 95% interval on the measured designs, not “never under-cover”). See Can I fit and report this?.

Your first analysis

  1. 1. Get started
    Install or validate a first animal-model formula.
  2. 2. Choose a model
    Check the route scope before fitting.
  3. 3. Fit
    Run the smallest honest workflow.
  4. 4. Diagnose
    Read fit diagnostics before extracting results.
  5. 5. Report
    Use route-scoped point estimates only.

Start here

If you want to… Read this
check a formula without installing Julia Getting started (engine = "validate")
decide whether a number may go in a paper Can I fit and report this?
see the seven R-public covered routes Model status
set up the Julia engine Installation
look up a function Reference
understand evidence history without mistaking it for a release Progression & evidence

Quick start — no Julia required

This four-animal pedigree is a syntax demo, not a number for a paper.

library(hsquared)

ped <- data.frame(
  id   = c("sire", "dam", "off1", "off2"),
  sire = c(NA, NA, "sire", "sire"),
  dam  = c(NA, NA, "dam", "dam")
)
dat <- data.frame(
  id     = c("sire", "dam", "off1", "off2"),
  sex    = c("m", "f", "m", "f"),
  weight = c(42, 38, 40, 37)
)

hsquared(
  weight ~ sex + animal(1 | id, pedigree = ped),
  data = dat,
  control = hs_control(engine = "validate")
)

Fitting — requires the Julia engine

With a local Julia, JuliaCall, and an HSquared.jl checkout (see Installation):

fit <- hsquared(
  weight ~ sex + animal(1 | id, pedigree = ped),
  data = dat
)
summary(fit)

The first fit in a session takes about 30 s while Julia starts and compiles. Later fits take under a second for a few hundred animals. The call prints no progress, so the first one can look frozen.

Report only what Can I fit and report this? allows for the route you ran.

Installation 

install.packages("remotes")
remotes::install_github("itchyshin/hsquared")

pak::pak("itchyshin/hsquared") is equivalent. Neither command builds vignettes, so vignette("hsquared") is empty after install; use Getting started on the website.

Fitting also needs Julia 1.10 or later with julia on PATH, JuliaCall, and a local HSquared.jl tree. HSquared is not in the Julia General registry — do not use Pkg.add("HSquared") by name.

install.packages("JuliaCall")

Clone the engine, install its Julia dependencies, then point R at that tree:

git clone https://github.com/itchyshin/HSquared.jl
julia --project=/path/to/HSquared.jl -e 'using Pkg; Pkg.instantiate()'
Sys.setenv(HSQUARED_JULIA_PROJECT = "/path/to/HSquared.jl")

HSquared.jl does not ship a Manifest.toml, so skipping Pkg.instantiate() fails on the first fit with a missing Optim package. The first call still precompiles Julia packages (about 30 seconds when the project is already instantiated; about two minutes on a cold depot). See Getting started for the per-call julia_project alternative.

Authors

Shinichi Nakagawa (ORCID 0000-0002-7765-5182, ), Yefeng Yang (ORCID 0000-0002-8610-4016), Szymon Drobniak (ORCID 0000-0001-8101-6247).

Twin

hsquared is the applied R interface. HSquared.jl is the sparse engine. A twin, not a port.