Command line ============ ``ljos-consensus settle [FLAGS]`` =================================== ======================================================================================================================================================================================================================================================================== Flag Meaning =================================== ======================================================================================================================================================================================================================================================================== ``--issue ID`` ballots from ``vissue vote ID --json`` ``--ballots JSON`` ``[{agent, choice}]``, or an object with ``ballots``, ``votes`` or ``agents[].voted`` ``--trust JSON`` ``[[from, to, weight], ...]`` or ``[{from, to, weight}, ...]`` ``--self-trust MODE`` how a voter weighs its own ballot when its row does not say: ``earned`` (the default) as the others weigh it, or ``constant`` at ``--self-weight`` for every voter ``--self-weight W`` the self-weight under ``constant``, and the fallback under ``earned`` for a voter nobody names; default 0.5 ``--discount-of JSON`` ``{agent: d}``, the share of its inbound weight each voter keeps; ``correlation`` prints it ``--susceptibility S`` 1 is DeGroot; below 1 anchors each voter to its ballot; default 1 ``--susceptibility-of JSON`` ``{agent: s}``, a persona's own anchor per voter ``--epsilon E [--epsilon-of JSON]`` bounded confidence instead of the trust graph: each voter averages only voters within L1 distance ``E`` of its own opinion ``--max-iter N``, ``--tol T`` the fixed-point budget; defaults 200 and 1e-9 ``--engine NAME`` ``iterate`` (the default) steps to the fixed point and stops on a bound; ``exact`` reads it off in closed form; ``energy`` minimises the Friedkin-Johnsen energy under a constant ``--self-weight``, without ``--discount-of``, and needs a voter below susceptibility 1 ``--seldon [--out DIR]`` write Seldon inputs, run ``seldon``, read the result =================================== ======================================================================================================================================================================================================================================================================== Output: ==================== ============================================================================================ Field Meaning ==================== ============================================================================================ ``options`` the options, sorted ``shares`` each option's share, in that order ``rounds`` the steps taken ``settled`` within ``--tol`` of the fixed point ``residual`` the bound or distance that says so ``engine`` ``degroot-fj``, ``fj-exact``, ``fj-energy``, ``bounded-confidence``, ``seldon`` or ``empty`` ``polarization`` the sum over voters of the squared distance from the mean final opinion ``disagreement`` the sum over trust edges of weight times the squared distance between the two ends ``agents`` the voters ``influence`` each voter's social power: the weight its ballot carries in the shares, summing to one ``effective_voters`` ``1 / sum influence^2`` ``margin`` the leading share less the next ``tie`` the margin is within twice the residual and rounding ==================== ============================================================================================ Polarization and disagreement follow Musco, Musco and Tsourakakis (doi:10.1145/3178876.3186103). Only the iterate and exact engines fill the last five fields. ``ljos-consensus surprising (--issue ID | --ballots JSON) --predictions JSON`` The surprisingly popular answer (Prelec, Seung and McCoy, doi:10.1038/nature21054). ``--predictions`` is an array of ``{agent, expect}`` where ``expect`` is an option, or an object of option to the share the voter expects the others to give it. Output: ``options``, ``actual`` and ``predicted`` shares, ``surprise`` (actual minus predicted), ``answer`` (the largest surprise; absent below two predictors), ``predictors``. ``ljos-consensus reputation --trust JSON [--agents a,b,c] [--alpha A]`` EigenTrust (Kamvar, Schlosser and Garcia-Molina, doi:10.1145/775152.775242): a global standing per voter from the pairwise rows, the principal eigenvector of the row-normalised trust matrix pulled toward a uniform pre-trust by ``alpha`` (default 0.15). Output: ``standing`` as an object of voter to a share of one. ``ljos-consensus reliability (--items JSON | --project P) [--rounds N]`` Dawid and Skene's estimate (doi:10.2307/2346806) of each voter's accuracy from many items with no known truth: expectation maximisation over the items' hidden answers and the voters' accuracies, twenty rounds by default. ``--items`` is a JSON array of ballot arrays; ``--project`` reads every issue of a tracker project that holds two or more ballots. Output: ``items``, ``rounds``, and ``accuracy`` as an object of voter to a value in (0, 1), Laplace smoothed so no voter reaches a certainty. ``ljos-consensus correlation (--items JSON [--truths JSON] | --project P) [--min-shared N] [--gate Z] [--rounds N]`` How much the voters share their mistakes. A voter's correctness on each item is read against the item's named outcome, or else the Dawid-Skene answer. ``--truths`` names the outcomes, one string or null per item. ``rho`` is the Pearson correlation of those indicators for each pair, over the items both voted on; it is zero below ``--min-shared``, which defaults to 5. A pair counts only when ``sqrt(shared) rho`` passes ``--gate``, the one-sided test of independence. The gate defaults to 1.645, five percent, and 0 counts every positive reading. ====================== ========================================================================= Field Meaning ====================== ========================================================================= ``agents`` the voters, in the order of the matrices ``rho``, ``shared`` the correlations, and the items each pair shares ``gate`` the test a pair passed to count ``discount`` voter to ``1 / (1 + sum_{j !`` i} rho\ :sub:`ij`)= over the counted pairs ``effective_voters`` ``n^2 / sum_ij rho_ij`` over the counted pairs: what equal weights get ``independent_voters`` the sum of the discounts ``items``, ``named`` the items read, and how many had a named outcome ====================== ========================================================================= ``ljos-consensus rounds --agents a,b,c [--susceptibility S] [--susceptibility-of JSON] [--tol T]`` The contraction bound over the named voters and the round count it guarantees: ``bound`` is the largest susceptibility, and ``predicted_rounds`` is ``1 + ceil(ln(tol) / ln(bound))`` rounds to reach ``tol`` (default 1e-9). A pure DeGroot panel reports the bound of one and a null count with the reason, since convergence there is asymptotic; size ``--max-iter`` by judgement. One unanchored voter voids the guarantee for the whole panel, which is what the maximum says. The step ======== ``x(t+1) = (1 - s) x(0) + s W x(t)``, with ``W`` the row-stochastic trust matrix and ``s`` the susceptibility. A voter's opinion is a distribution over the options, one-hot at the start. ``--self-trust`` fills a missing self weight. A voter with no row of its own listens to everyone, itself included, each in proportion to its discount, so equally when there is none. A voter's inbound weight is scaled by its discount before the rows are normalised. Shares are the column sums of the fixed point, normalised. The fixed point is ``x* = P x(0)``. ``P`` is ``(I - L W)^{-1} (I - L)``, with ``L`` the diagonal of susceptibilities, wherever every closed group of the trust graph holds an anchored voter; a closed group that listens fully settles on its stationary distribution, and the voters outside it solve against that. The iteration stops when ``q / (1 - q)`` times its last step, plus the binary64 floor ``gamma(n + 2) / (1 - q)``, is under ``--tol``, with ``q`` the largest susceptibility. A panel where some voter listens fully stops on its distance to ``x*``, or on its last step when ``x*`` cannot be read off. Library ======= The crate root exports the types ``Ballot``, ``Outcome``, ``Opts``, ``SelfTrust``, ``Prediction`` and ``Surprise``, and the helpers ``roster``, ``influence_matrix`` and ``influence_matrix_with``. Its settles are ``settle``, ``settle_anchored``, ``settle_with``, ``settle_exact``, ``settle_bounded``, ``settle_energy`` and ``settle_seldon``. Its readings are ``dawid_skene``, ``surprisingly_popular``, ``eigentrust``, ``fj_contraction_bound`` and ``fj_rounds_to_tol``; its parsers are ``ballots_from_json``, ``trust_from_json``, ``anchors_from_json`` and ``predictions_from_json``. ``exact`` holds ``fixed_point``, ``social_power``, ``effective_voters`` and ``Unsettled``, the reason a fixed point could not be read off. ``correlation`` holds the reading above and ``INDEPENDENCE_Z``. The Seldon module writes and reads the engine's files and links nothing under a copyleft licence.