R API

Reference for the R package in r/, generated from its help pages (the same text as ?loglik_fast and friends in R) by docs/api/make_r_reference.R. Each function calls the Python function of the same name; see Using cointf from R for setup.

loglik_fast()

Log-likelihood of crossover positions under the Housworth-Stahl model

Description

Crossovers come from an interference pathway (a stationary renewal process with gamma-mixture gaps governed by nu) and an escape pathway (a Poisson process carrying a fraction p of crossovers). The likelihood sums over the unobserved pathway labels exactly.

Usage

loglik_fast(data, L, nu, p, kernel = NULL, per_meiosis = FALSE)

Arguments

data

A list with one numeric vector of crossover positions (in Morgans) per meiosis, or an object from meioses().

L

Chromosome length in Morgans: one value or one per meiosis. Must be NULL when data comes from meioses().

nu

Interference parameter, ⁠> 0⁠: one value or one per meiosis. nu = 1 is no interference.

p

Fraction of crossovers escaping interference, in ⁠[0, 1]⁠: one value or one per meiosis.

kernel

Optional kernel, e.g. from chebyshev_kernel(); the default is the exact series.

per_meiosis

If TRUE, return one log-likelihood per meiosis instead of the sum.

Value

The total log-likelihood, or a numeric vector with one value per meiosis if per_meiosis = TRUE.

Examples

data <- simulate_meioses(L = 1.5, nu = 4, p = 0.05, n = 200, seed = 7)
loglik_fast(data, 1.5, nu = 4, p = 0.05)

loglik_quartet()

Log-likelihood of phase-unknown (quartet) crossover data

Description

For a parent in a family with two offspring and no grandparents, each chromosome yields the pooled crossovers of two meioses, without knowing which meiosis each crossover came from. The likelihood sums over every assignment of crossovers to the two meioses or to the escape pathway.

Usage

loglik_quartet(data, L, nu, p, kernel = NULL, per_meiosis = FALSE)

Arguments

data

A list with one numeric vector of pooled crossover positions (in Morgans) per quartet, or an object from meioses().

L

Chromosome length in Morgans: one value or one per meiosis. Must be NULL when data comes from meioses().

nu, p

As for loglik_fast(); both meioses of a quartet share them.

kernel

Optional kernel, e.g. from chebyshev_kernel(); the default is the exact series.

per_meiosis

If TRUE, return one value per quartet (one entry of data) instead of the sum. The name matches loglik_fast().

Value

The total log-likelihood, or a numeric vector with one value per quartet if per_meiosis = TRUE.

Examples

quartets <- simulate_quartets(L = 1.5, nu = 4, p = 0.05, n = 200, seed = 7)
loglik_quartet(quartets, 1.5, nu = 4, p = 0.05)

meioses()

Prepare crossover data for repeated likelihood evaluation

Description

Validates and sorts the positions, groups meioses by crossover count and precomputes every distance the likelihood needs. Build it once and pass it to loglik_fast() or loglik_quartet() (with L = NULL) for each parameter value, for example inside an optimiser.

Usage

meioses(data, L)

Arguments

data

A list with one numeric vector of crossover positions (in Morgans) per meiosis; an entry may be empty (numeric(0)). For quartet data, one entry per quartet.

L

Chromosome length in Morgans: one value, or one per entry of data.

Value

A Python Meioses object.

Examples

mz <- meioses(list(c(0.2, 0.9), numeric(0), 0.5), L = 1.2)
loglik_fast(mz, NULL, nu = 4, p = 0.05)

chebyshev_kernel()

Faster approximate likelihood kernel

Description

Piecewise Chebyshev fits of the log gap density and log survival function, built once per value of nu and cached in the returned object. Keep one kernel and reuse it across calls so the cache is reused. With a shared nu it is 6-10 times faster than the exact series, with per-meiosis log-likelihood differences around 1e-13.

Usage

chebyshev_kernel(
  tol = 1e-12,
  u_min = 1e-06,
  u_max = 5,
  u_split = 0.25,
  n_nodes = 16,
  max_distinct = 16,
  max_cached = 256
)

Arguments

tol

Acceptance threshold for each fitted piece (not an error bound).

u_min, u_max

Distances (on the interference scale) inside this range use the fit; the rest use the exact series.

u_split

Boundary between pieces fitted in log distance and in distance.

n_nodes

Chebyshev nodes per piece.

max_distinct

Largest number of distinct nu values in one call for which fits are built; above it the exact series is used.

max_cached

Fits kept before the cache is cleared.

Value

A Python ChebyshevKernel object, to pass as kernel.

Examples

kernel <- chebyshev_kernel()
data <- simulate_meioses(L = 1.5, nu = 4, p = 0.05, n = 200, seed = 7)
loglik_fast(data, 1.5, nu = 4, p = 0.05, kernel = kernel)

simulate_meioses(), simulate_quartets()

Simulate crossover positions under the Housworth-Stahl model

Description

simulate_meioses() draws independent meioses. simulate_quartets() draws phase-unknown data: each entry pools the crossovers of two independent meioses.

Usage

simulate_meioses(L, nu, p, n, seed)

simulate_quartets(L, nu, p, n, seed)

Arguments

L

Chromosome length in Morgans, ⁠> 0⁠.

nu

Interference parameter, ⁠> 0⁠.

p

Fraction of crossovers escaping interference, in ⁠[0, 1]⁠.

n

Number of meioses (or quartets).

seed

Random seed, ⁠> 0⁠. The same seed gives the same data as the Python package.

Value

A list of sorted numeric vectors of crossover positions in Morgans.

Examples

simulate_meioses(L = 1.5, nu = 4, p = 0.05, n = 3, seed = 7)
simulate_quartets(L = 1.5, nu = 4, p = 0.05, n = 3, seed = 7)

meiosis_list()

Crossover positions from long-format data

Description

Turns one-row-per-crossover data into the list format the likelihood functions take. Meioses without crossovers are kept by giving them a row with NA position.

Usage

meiosis_list(position, meiosis)

Arguments

position

Crossover positions in Morgans; NA for a meiosis without crossovers.

meiosis

Meiosis identifier for each row.

Value

A named list with one numeric vector per meiosis, in order of first appearance.

Examples

meiosis_list(c(0.2, 0.9, NA, 0.5), c("a", "a", "b", "c"))

cointf_python()

The underlying Python module

Description

Gives direct access to the Python 'cointf' module, for functions without an R wrapper (for example cointf_python()$naive$loglik_quartet_naive).

Usage

cointf_python()

Value

The 'cointf' Python module, as a reticulate object.

Package overview and Python setup

cointf: Housworth-Stahl likelihoods from R

Description

An R interface to the Python package 'cointf'. Each R function calls the Python function of the same name through 'reticulate', so results are identical to the Python package.

Python environment

When the package is loaded it declares its Python requirement with reticulate::py_require(), and reticulate installs it into a managed environment the first time Python is used. The requirement defaults to the GitHub repository and can be changed with the option cointf.python, set before loading the package, e.g. to install from the dev branch: 

options(cointf.python = "cointf @ git+https://github.com/aabiddanda/cointf@dev")

To use an existing Python environment instead (for example one where 'cointf' was installed with ⁠pip install .⁠ from a clone), point reticulate at it before loading the package, e.g. Sys.setenv(RETICULATE_PYTHON = "/path/to/venv/bin/python"). The GitHub requirement is then not declared. Setting options(cointf.python = NULL) also skips it, for environments selected another way (e.g. reticulate::use_virtualenv()).

Author(s)

Maintainer: Arjun Biddanda aabiddanda@gmail.com

Authors:

See Also

Useful links: