Octopodes.jl

Appearance

Index ​

Types and functions ​

Octopodes.COMPANION_COLORS Constant

Default per-companion colours (companion identity ).

source
Octopodes.NCOMP_MARKERS Constant

Marker shape encodes the number of companions present in a draw.

source
Octopodes.BinnedIndepRuns Type

Binned version of independent MCMC runs.

  • binning

  • samples: Dims: (system index, MCMC iteration).

  • tilde_psi

  • max_n_companions

  • star_names

source
Octopodes.BinnedSample Type

  • n_companions

  • bin_memberships: Contains inactive ones (for type stability) - the inactive ones are set to zero.

source
Octopodes.Binning Type

Discretization of the (log_P_yr, log_q) into regular grids.

Each grid is specified using StepRangeLen, see interval_index.

source
Octopodes.Binning Method
julia
Binning(runs; n_log_P_yr_intervals, n_log_q_intervals)

Use the prior bounds from the independent MCMC runs and a requested number of intervals in each axis to build a binning.

source
Octopodes.IndepRuns Type

Information needed about the independent MCMC runs for each system in order to run joint inference.

  • traces: A vector of traces, one for each system. Each trace is a NamedTuple assumed to have the following fields:

    • n_planets::Vector{Int64},

    • log_P_yr::Matrix{Float64},

    • log_q::Matrix{Float64},

    • n_samples::Int64,

    • name::String

  • mv

  • log_P_yr_prior

  • log_q_prior

  • n_companions_prior

source
Octopodes.IndepRuns Method
julia
IndepRuns(d)

Load the IndepRuns data from an informal exchange format defined in Dict.

source
Octopodes.PopulationPosterior Type
julia
struct PopulationPosterior{B<:Binning}

Posterior summary of the joint population model produced by run_imh, reduced to the quantities needed to describe and plot companion demographics.

Construct one with population_posterior. The companion-rate density is    — the expected number of companions per star in bin — under the single shared bin distribution of the joint model. Multiply by 100 for the conventional "companions per 100 stars per bin" units.

  • binning: The Binning the posterior is defined on (carries the grid edges).

  • psi: Companion-count distribution . Dims: (max_n_companions + 1) × n_keep.

  • pi: Shared per-bin distribution (flattened). Dims: n_bins × n_keep.

  • lambda: Per-bin companion-rate density   . Dims: n_keep × n_log_P × n_log_q.

  • P_geq: Tail probabilities   for c = 1 … max_n_companions. Dims: max_n_companions × n_keep.

  • E_n: Expected companion count per retained draw. Length n_keep.

  • n_keep: Number of post-warmup IMH iterations retained.

  • warmup_frac: Fraction of the trace discarded as warmup.

source
Octopodes.bin Method
julia
bin(b, values)

Given a Binning and an iterable over two reals, provide the index of the corresponding bin.

source
Octopodes.bin Method
julia
bin(b, runs; star_selector, shuffle_rng)

Perform binning on all the samples. Returns an Array of BinnedSample. Rows are systems, columns are MCMC iterations.

By default, this also shuffle each system independently. Set shuffle_rng with the AbstractRNG object to change the seed, set to nothing to skip shuffling.

Assume that all traces have the same number of iterations.

source
Octopodes.binarize Method
julia
binarize(binned, k)

Produce a coarser binning based on the indicator function of whether there is at least one planet in bin index k.

source
Octopodes.binarize Method
julia
binarize(binned)

Produce a coarser binning based on the indicator function of whether there is at least one planet (irrespective of its position).

source
Octopodes.generate_binary_indep_runs Method
julia
generate_binary_indep_runs(
;
    psi_some_companion_truth,
    n_systems,
    tilde_psi_some_companion,
    mcmc_lazy_pr,
    n_systems_iters,
    rng,
    shuffle_rng
)
source
Octopodes.interval_index Method

Return the index of the intervals in the provided StepRangeLen the given point falls in, or throw BoundsError if the point falls in none of the intervals.

All the intervals are viewed as closed on the left and open to the right, except the last one which is closed on both sides.

source
Octopodes.intervals_from_bin_index Method
julia
intervals_from_bin_index(b, k)

Given a bin index, return the interval of period and mass corresponding to it. Encode it as a new Binning object.

source
Octopodes.is_binary Method
julia
is_binary(binned)

A BinnedIndepRuns is binary if the maximum number of companions is one and the number of bins is one.

See also binarize for two methods to get a binary binning from a non binary one (either by just looking at overall presence of at least on companion, or by focusing single bin).

source
Octopodes.n_intervals Method

The number of intervals (blocks) is one less than the number of grid (boundaries).

source
Octopodes.numerical Function
julia
numerical(binned)
numerical(binned, eps)

Assume that the provided binned is binary (see is_binary) and use numerical integration to obtain a discretized posterior.

Use a uniform prior over the fraction of stars with at least one companion.

source
Octopodes.numerical_posterior_plot Function
julia
numerical_posterior_plot(posterior)
numerical_posterior_plot(posterior, true_proportion)
source
Octopodes.population_heatmap_axis Method
julia
population_heatmap_axis(fig)

Return the main heatmap Axis of a population_posterior_plot figure (the block at grid position [2, 1]). Errors if no Axis is found there.

source
Octopodes.population_posterior Method
julia
population_posterior(result, binning; warmup_frac)

Summarize the raw output of run_imh into a PopulationPosterior.

result is the named tuple returned by run_imh (with fields psi_trace and pi_trace); binning is the Binning used to produce the binned runs. The leading warmup_frac of each trace is discarded, then the per-draw companion rate density   , tail probabilities   and expected count are computed.

This is the standard reduction every downstream demographics plot needs, so it lives here rather than in user scripts. See population_posterior_plot.

source
Octopodes.population_posterior_plot Method
julia
population_posterior_plot(post; kwargs...)

Plot the joint-π population posterior: a heatmap of the per-bin companion rate density   (companions per 100 stars per bin) over the grid, with the period- and mass-marginal rates and   shown as boxplots on the margins.

Three methods are provided, all reading the grid edges from the Binning so they never have to be passed by hand:

  • population_posterior_plot(post::PopulationPosterior; ...) — the usual call.

  • population_posterior_plot(result, binning; warmup_frac = 0.2, ...) — runs population_posterior for you, straight from run_imh output.

  • population_posterior_plot(lambda_grid, pi_geq1, binning; ...) — low-level, for a pre-computed rate grid (n_draws × n_log_P × n_log_q) and P(≥1) draws.

Keyword arguments:

  • figsize::Tuple = (900, 600) — figure size in points.

  • outfile::Union{String, Nothing} = nothing — if set, save the figure there.

  • colorscale = log10 — heatmap colour scale.

  • truths::Union{NamedTuple, Nothing} = nothing — optional injection truth for an injection/recovery diagnostic. Fields: log_P_yr, log_q (centres, required); optional bounds log_P_yr_lo/log_P_yr_hi/log_q_lo/log_q_hi; and n_stars (host count, used to put truth histograms in the same λ·100 units). When given, cyan crosses/errorbars mark each truth on the heatmap and normalised truth histograms are overlaid on the marginals.

  • sensitivity::Union{AbstractVector{<:Real}, Nothing} = nothing — optional per-bin relative prior-sensitivity (length binning.n_bins), as returned by relative_sensitivities. Bins whose value exceeds sensitivity_threshold are masked: blanked (drawn in masked_color) on the heatmap and excluded from the marginal sums, so the figure shows only data-constrained regions. Typical use: sensitivity = relative_sensitivities(binned, 1e-3).

  • sensitivity_threshold::Union{Real, Nothing} = nothing — required when sensitivity is given; bins with sensitivity .> sensitivity_threshold are masked.

  • masked_color = (:grey, 0.5) — fill colour for masked (poor-sensitivity) bins.

Returns the Makie.Figure.

source
Octopodes.posterior_dotplot! Method
julia
posterior_dotplot!(
    ax,
    x,
    y,
    n_companions;
    weights,
    colors,
    ncomp_markers,
    markersize,
    base_alpha,
    max_points,
    rng
)

Scatter a set of per-companion posterior draws onto an existing ax::Axis.

This is the units-agnostic core. x and y are (max_n_companions × n_samples) matrices — the same layout as an IndepRuns trace's log_P_yr/log_q — holding whatever quantities you want on the axes. n_companions (length n_samples) says how many companions are present in each draw; for draw i, the first n_companions[i] rows of column i are plotted.

weights (length n_samples, or nothing) is the per-draw re-weighting vector: every companion in draw i is drawn with opacity proportional to weights[i] (normalised to its maximum). Pass nothing for the plain, unweighted posterior. Colour encodes companion identity (colors); marker shape encodes the draw's companion count (ncomp_markers).

Returns ax.

source
Octopodes.posterior_dotplot! Method
julia
posterior_dotplot!(ax, trace; view, weights, kwargs...)

Overlay one IndepRuns system trace onto ax. view selects which trace fields map to the axes:

  • :log_P_q (default) → (trace.log_P_yr, trace.log_q), the same plane as population_posterior_plot, so a re-weighted system posterior can be drawn directly on the population heatmap (see the Figure method).

For physical-unit views (mass vs separation) the trace does not carry the needed columns; call the (ax, x, y, n_companions) method with matrices you build from a richer samples table instead.

source
Octopodes.posterior_dotplot! Method
julia
posterior_dotplot!(fig, args; kwargs...)

Overlay a system posterior on top of the heatmap of a figure returned by population_posterior_plot — the second of the two calls in the usual "plot the population model, then drop a re-weighted system onto it" workflow:

julia
fig = population_posterior_plot(post)
posterior_dotplot!(fig, runs.traces[s]; weights = w[:, s])

The scatter is drawn onto the main heatmap Axis (found with population_heatmap_axis); args/kwargs are forwarded to the Axis methods above. Returns fig.

source
Octopodes.posterior_dotplot Method
julia
posterior_dotplot(
    x,
    y,
    n_companions;
    weights,
    xlabel,
    ylabel,
    title,
    xscale,
    yscale,
    figsize,
    nbins,
    show_marginals,
    upper_limit,
    upper_quantile,
    min_bin_weight,
    kwargs...
)

Standalone per-system dotplot: a scatter of the posterior draws with weighted period- and mass-marginal step histograms and a weighted upper-envelope line (the per-x-bin upper_quantile of y).

Units-agnostic like posterior_dotplot!: x, y are (max_n_companions × n_samples) and weights is per-draw (or nothing). Set the axis dressing with xlabel/ylabel/xscale/yscale. Returns the Figure.

source
Octopodes.posterior_dotplot Method
julia
posterior_dotplot(
    trace;
    view,
    weights,
    xlabel,
    ylabel,
    title,
    kwargs...
)

Standalone dotplot for one IndepRuns system trace in the chosen view (default :log_P_q, with sensible axis labels). See the matrix method for the keyword arguments.

source
Octopodes.relative_sensitivities Method
julia
relative_sensitivities(binned, eps)

For each bin, binarize with respect to that bin using binarize, and compute sensitivity for that bin. Return a vector of relative sensivities, one for each bin.

Relative absolute relative_sensitivities are obtained by dividing by the primal value and taking abs values.

source
Octopodes.run_imh Function
julia
run_imh(rng, binned)
run_imh(rng, binned, processor)
source
Octopodes.sensitivity Method
julia
sensitivity(binned, eps)

Assume that the provided binned is binary (see is_binary).

Compute the mean of the distribution obtain in numerical. Embed the prior assumed there in Beta(2mu, 2(1-mu)) family prior (i.e., considering perturbations of the prior mean). Use ForwardDiff to compute the derivative of the posterior mean with respect to mu at 1/2 (i.e., in the neighbourhood of the uniform prior).

source
Octopodes.vector_to_array Method
julia
vector_to_array(b, vector)

Given a Binning and a vector of reals, reshape it into a matrix where the rows correspond to blocks in the log_P_yr partition, and the columns, to blocks in the log_q partition.

To perform the inverse operation, simply use vec(matrix).

source