Hierarchical random graphs and progress

The type of a function that receives progress reports from long computations.

typedef og_error_t og_progress_handler_t(
    const char *message,
    og_real_t percent,
    void *data
);

Long computations (for example hrg_consensus and hrg_predict while they sample) report how far they are: a short text and a percentage from 0 to 100. Each thread has its own handler, installed with set_progress_handler. A handler that returns anything but OG_SUCCESS stops the computation that called it: the code travels back through the error mechanism, which releases the computation's temporary objects.

Parameters

• message What is running.
• percent How much is done, 0 to 100.
• data The caller's context; Open Graph's own functions pass NULL.

Returns

OG_SUCCESS to let the computation continue; any other code stops it with that code.

Checked

Same signature as igraph 1.0's type (message, percent, data).

C name

og_progress_handler_t

In notebooks

Og.ProgressHandler

igraph 1.0

igraph_progress_handler_t

See also

set_progress_handler, progress, progress_handler_stderr

The type of a function that receives status messages.

typedef og_error_t og_status_handler_t(const char *message, void *data);

Status messages say what a computation is doing, as text without a percentage. Each thread has its own handler, installed with set_status_handler. A handler that returns anything but OG_SUCCESS stops the computation that reported, as for progress handlers.

Parameters

• message The status text.
• data The caller's context; Open Graph's own functions pass NULL.

Returns

OG_SUCCESS to continue; any other code stops the computation with that code.

Checked

Same signature as igraph 1.0's type.

C name

og_status_handler_t

In notebooks

Og.StatusHandler

igraph 1.0

igraph_status_handler_t

See also

set_status_handler, status, status_handler_stderr

An HRG: a dendrogram with a connection probability at each internal node.

typedef struct og_hrg_t {
    og_vector_int_t left;
    og_vector_int_t right;
    og_vector_t prob;
    og_vector_int_t vertices;
    og_vector_int_t edges;
} og_hrg_t;

An HRG on n vertices is a binary tree (a dendrogram) whose n leaves are the vertices and whose n - 1 internal nodes carry probabilities; two vertices are joined with the probability of their lowest common ancestor. (Clauset, Moore and Newman, Nature 2008.)

Numbering: leaves are 0 to n - 1, internal nodes -1 to -(n - 1), and the root is -1. Entry k of each vector describes internal node -(k + 1). An HRG with no vertices has empty vectors; one with a single vertex cannot be told apart from it, so an HRG has 0 or at least 2 leaves. Initialise with hrg_init, release with hrg_destroy.

Parameters

• left Left child of each internal node (leaf ids >= 0, internal ids < 0).
• right Right child of each internal node.
• prob Connection probability of each internal node.
• vertices Number of leaves below each internal node.
• edges For an HRG fitted to a graph: the number of edges with one end under each child of the node.

Checked

Layout as igraph 1.0's type; the meaning of vertices and edges checked on 10 HRGs fitted by the igraph 1.0.1 C library (black box).

C name

og_hrg_t

In notebooks

Og.Hrg

igraph 1.0

igraph_hrg_t

See also

hrg_init, hrg_fit, from_hrg_dendrogram

Initialises an HRG with room for n vertices, all entries zero.

og_error_t og_hrg_init(og_hrg_t *hrg, og_int_t n);

The five vectors get n - 1 entries each (none when n is 0 or 1), all zero. Pass 0 when the size is not known yet: the fitting and creating functions resize the HRG themselves. Release it with hrg_destroy.

Parameters

• hrg The HRG to initialise (not yet initialised).
• n Number of vertices (leaves), >= 0.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL n is negative.
• OG_ENOMEM Not enough memory.

Complexity

O(n).

Checked

n - 1 zeroed entries; n = 0 or 1 gives empty vectors; EINVAL for n < 0 (tested).

C name

og_hrg_init

In notebooks

Og.HrgInit

igraph 1.0

igraph_hrg_init

See also

hrg_destroy, hrg_resize, hrg_size

Releases the memory of an HRG.

void og_hrg_destroy(og_hrg_t *hrg);

Destroys the five vectors. The HRG may be initialised again afterwards; calling it twice is safe.

Parameters

• hrg The HRG to release.

Returns

Nothing.

Complexity

O(1).

Checked

Safe to call twice (tested).

C name

og_hrg_destroy

In notebooks

Og.HrgDestroy

igraph 1.0

igraph_hrg_destroy

See also

hrg_init

Returns the number of vertices (leaves) of an HRG.

og_int_t og_hrg_size(const og_hrg_t *hrg);

Internal nodes plus one, or 0 when the HRG is empty. A size of 1 cannot be represented (it looks like 0).

Parameters

• hrg The HRG.

Returns

The number of leaves.

Complexity

O(1).

Checked

Internal nodes + 1, or 0 for empty vectors (igraph's value for the one-leaf corner was not observable).

C name

og_hrg_size

In notebooks

Og.HrgSize

igraph 1.0

igraph_hrg_size

See also

hrg_resize, hrg_init

Changes the number of leaves of an HRG.

og_error_t og_hrg_resize(og_hrg_t *hrg, og_int_t newsize);

Every vector gets newsize - 1 entries (none for 0 or 1). Existing entries are kept where they still fit and new entries are zero; each vector is zero-filled from its own former length, even when a caller left the five with different lengths. The memory for all five is reserved first, so on failure the HRG is unchanged.

Parameters

• hrg The HRG.
• newsize New number of leaves, >= 0.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL newsize is negative.
• OG_ENOMEM Not enough memory.

Complexity

O(newsize).

Checked

Keeps existing entries, zeroes new ones, unchanged on failure, vectors of unequal length handled (tested).

C name

og_hrg_resize

In notebooks

Og.HrgResize

igraph 1.0

igraph_hrg_resize

See also

hrg_init, hrg_size

Fits an HRG to a graph by Markov chain Monte Carlo over dendrograms.

og_error_t og_hrg_fit(
    const og_t *graph,
    og_hrg_t *hrg,
    og_bool_t start,
    og_int_t steps
);

Edge directions, self-loops and edge multiplicities are ignored. The likelihood of a dendrogram is the product over internal nodes r of p_r^E_r (1 - p_r)^(L_r R_r - E_r), where E_r counts the edges between r's two subtrees of L_r and R_r leaves; at the best p_r = E_r / (L_r R_r). The chain picks an internal node other than the root and rearranges the three subtrees around it and its parent, accepting by the Metropolis rule (Clauset, Moore and Newman, Nature 2008). hrg receives the most likely dendrogram met, starting one included, each internal node labelled with its maximum likelihood probability.

start true begins at the dendrogram already in hrg (a valid tree with the graph's number of vertices), false at a uniformly random dendrogram. steps > 0 runs exactly that many proposals. steps = 0 runs rounds of max(100000, 200 n) proposals, at least 25 n^2 in all, until the best log-likelihood has not grown by more than 1e-3 + 1e-6 |logL| for as many proposals as it took to reach it, and never more than max(50 n^2, 5000000): about 2.5 s for G(500, 2000) and 10 s for G(1000, 5000) on a current PC. Random numbers come from Open Graph's default generator.

Parameters

• graph The graph, at least 3 vertices.
• hrg Input (when start is true) and output: the fitted HRG.
• start true: start from the dendrogram in hrg; false: from a random one.
• steps Number of proposals, or 0 for the automatic stopping rule.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL The graph has fewer than 3 vertices.
• OG_EINVAL steps is negative.
• OG_EINVAL start is true and hrg is not a valid tree with the graph's number of leaves.
• OG_ENOMEM Not enough memory.

Complexity

Each proposal costs about the size of the smaller subtrees moved; steps = 0 stops after at least 25 n^2 and at most max(50 n^2, 5000000) proposals.

Checked

Own random draws. The exact maximum likelihood on all 51 enumerated small graphs (n <= 7) and 270 more checked by two independent enumerations. Against recorded steps = 0 fits of the igraph 1.0.1 C library: karate club, mean -75.2 over 10 seeds (best -73.32, the true maximum) against igraph's mean -94.13; on a 128-vertex planted hierarchy and G(500, 2000) every fit at least as good as igraph's. G(500, 2000) in 1.5-2.2 s against up to about 8 s for igraph.

C name

og_hrg_fit

In notebooks

Og.HrgFit

igraph 1.0

igraph_hrg_fit

See also

hrg_consensus, hrg_predict, hrg_sample, hrg_t

#include "og.h"
#include <stdio.h>

int main(void) {
    og_t g;
    og_hrg_t hrg;
    og_int_t k;
    og_famous(&g, "Zachary");
    og_rng_seed(og_rng_default(), 7);
    og_hrg_init(&hrg, 0);
    og_hrg_fit(&g, &hrg, false, 0);           /* automatic stopping rule */
    for (k = 0; k < og_hrg_size(&hrg) - 1; k++) {
        printf("node %" OG_PRId ": children %" OG_PRId " %" OG_PRId ", p = %.3f\n", -(k + 1),
               OG_VECTOR(hrg.left)[k], OG_VECTOR(hrg.right)[k], OG_VECTOR(hrg.prob)[k]);
    }
    og_hrg_destroy(&hrg);
    og_destroy(&g);
    return 0;
}

Builds the majority consensus tree of dendrograms sampled in proportion to their likelihood.

og_error_t og_hrg_consensus(
    const og_t *graph,
    og_vector_int_t *parents,
    og_vector_t *weights,
    og_hrg_t *hrg,
    og_bool_t start,
    og_int_t num_samples
);

The chain starts from a maximum likelihood fit (start false) or from the dendrogram in hrg (start true), runs until its log-likelihood stops trending, and then takes one sample every n proposals, num_samples in all. The consensus tree keeps every group of vertices found under one internal node in more than half of the samples.

parents gets, for the n vertices followed by the consensus tree's internal nodes, the parent's id (-1 for the root); weights gets, for each internal node in the same order, the number of samples that contained its group (num_samples for the root). Internal nodes are listed by group size, then by smallest vertex id, root last: igraph's numbering whenever both trees hold the same groups. hrg receives the chain's final dendrogram. Progress (0 to 100) is reported while sampling.

Parameters

• graph The graph, at least 3 vertices (directions, loops and multiplicities ignored).
• parents Output, may be NULL: parent of each vertex and internal node.
• weights Output, may be NULL: sample count of each internal node.
• hrg Input (when start is true) and output: the chain's last dendrogram.
• start true: start from hrg; false: start from a maximum likelihood fit.
• num_samples Number of dendrograms to sample, >= 1.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL The graph has fewer than 3 vertices, or num_samples < 1.
• OG_EINVAL start is true and hrg is not a valid tree with the graph's number of leaves.
• handler's code: The progress handler stopped the computation.
• OG_ENOMEM Not enough memory.

Complexity

The chain's equilibration plus num_samples x n proposals, plus counting the groups of every sample.

Checked

Group frequencies within 0.035 of the exact posterior on 8 enumerated graphs and within 0.04 of a third independent enumeration on six more. Against igraph's recorded consensus trees on 8 graphs: every group either side holds in at least 60% of samples is on both sides, and the parent vectors are identical, numbering included, on the 5 graphs where both hold the same groups.

C name

og_hrg_consensus

In notebooks

Og.HrgConsensus

igraph 1.0

igraph_hrg_consensus

See also

hrg_fit, hrg_predict

Draws one random graph from an HRG.

og_error_t og_hrg_sample(const og_hrg_t *hrg, og_t *sample);

The graph is undirected, without loops or multi-edges, on hrg_size(hrg) vertices; each pair of vertices is joined independently with the probability of its lowest common ancestor. Edges come sorted by (smaller, larger) endpoint. Pairs below each node are skipped geometrically (Batagelj and Brandes, 2005), so the time grows with the edges drawn rather than with n^2. The empty HRG gives the graph without vertices. Random numbers come from Open Graph's default generator.

Parameters

• hrg The HRG: a valid tree with probabilities in [0, 1].
• sample Output: the new graph (not initialised before the call).

Returns

OG_SUCCESS.

Errors

• OG_EINVAL hrg is not a valid tree, or a probability lies outside [0, 1].
• OG_ENOMEM Not enough memory.

Complexity

Expected O(n + m log m) for m edges drawn.

Checked

Pair frequencies within 5 standard deviations of the ancestor probability (12 and 9 leaves, 4,000-6,000 samples); edges sorted as igraph returns them; all-0 and all-1 probabilities; invalid trees and probabilities refused.

C name

og_hrg_sample

In notebooks

Og.HrgSample

igraph 1.0

igraph_hrg_sample

See also

hrg_game, hrg_fit

Draws one random graph from an HRG (hrg_sample with the arguments swapped).

og_error_t og_hrg_game(og_t *graph, const og_hrg_t *hrg);

Exactly hrg_sample(hrg, graph): the same graph for the same seed.

Parameters

• graph Output: the new graph (not initialised before the call).
• hrg The HRG: a valid tree with probabilities in [0, 1].

Returns

OG_SUCCESS.

Errors

• OG_EINVAL hrg is not a valid tree, or a probability lies outside [0, 1].
• OG_ENOMEM Not enough memory.

Complexity

As hrg_sample.

Checked

Same as hrg_sample.

C name

og_hrg_game

In notebooks

Og.HrgGame

igraph 1.0

igraph_hrg_game

See also

hrg_sample

Turns an HRG's dendrogram into a directed tree graph.

og_error_t og_from_hrg_dendrogram(
    og_t *graph,
    const og_hrg_t *hrg,
    og_vector_t *prob
);

Leaf i becomes vertex i and internal node -(k + 1) becomes vertex n + k. The edges are, for k = 0, 1, 2, ..., vertex n + k to its left child, then to its right child, so the graph has 2n - 1 vertices and 2n - 2 edges, directed from parent to child. prob, when given, gets each vertex's probability: NaN for the leaves, the node's probability for the internal vertices. This is the exact inverse of hrg_create.

Parameters

• graph Output: the tree (not initialised before the call).
• hrg The HRG: a valid tree.
• prob Output, may be NULL: one probability per vertex of the tree.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL hrg is not a valid tree.
• OG_ENOMEM Not enough memory.

Complexity

O(n).

Checked

Edge list (order included) and probabilities identical to the dendrograms of 3 HRGs fitted by the igraph 1.0.1 C library (6, 14 and 34 leaves); 200 random HRGs checked against the documented layout.

C name

og_from_hrg_dendrogram

In notebooks

Og.FromHrgDendrogram

igraph 1.0

igraph_from_hrg_dendrogram

See also

hrg_create, hrg_dendrogram

Builds an HRG from a directed binary tree graph and per-vertex probabilities.

og_error_t og_hrg_create(
    og_hrg_t *hrg,
    const og_t *graph,
    const og_vector_t *prob
);

The graph must be a directed binary tree: one root of in-degree 0, every other vertex of in-degree 1, internal vertices of out-degree 2, leaves of out-degree 0. Leaves are numbered 0, 1, ... in vertex id order, the root becomes -1 and the other internal vertices -2, -3, ... in vertex id order; an internal vertex's first out-edge (by edge id) leads to its left child. prob has one entry per vertex: the leaves' entries are ignored, the internal ones must lie in [0, 1]; NULL labels every node 0. The edges entries become round(prob x left leaves x right leaves), which gives back the counts of a fitted HRG. A graph with 0 or 1 vertex gives the empty HRG.

With these rules hrg_create is the exact inverse of from_hrg_dendrogram. How igraph numbers an arbitrary tree here could not be observed, so the numbering above is Open Graph's documented choice.

Parameters

• hrg Output: an initialised HRG, resized as needed.
• graph A directed binary tree.
• prob One probability per vertex, or NULL for all 0.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL The graph is undirected.
• OG_EINVAL The graph is not a binary tree with one root (wrong counts, two parents, wrong out-degree, not one tree).
• OG_EINVAL prob does not have one entry per vertex, or an internal probability lies outside [0, 1].
• OG_ENOMEM Not enough memory.

Complexity

O(n).

Checked

Gives back igraph's HRGs from igraph's own dendrogram graphs (3 dendrograms, 8 karate fits; vertex and edge counts equal) and 200 random HRGs; 40 relabelled and shuffled dendrograms give the same groups; malformed trees refused.

C name

og_hrg_create

In notebooks

Og.HrgCreate

igraph 1.0

igraph_hrg_create

See also

from_hrg_dendrogram, hrg_t

Scores the unconnected pairs of vertices as possible missing edges.

og_error_t og_hrg_predict(
    const og_t *graph,
    og_vector_int_t *edges,
    og_vector_t *prob,
    og_hrg_t *hrg,
    og_bool_t start,
    og_int_t num_samples,
    og_int_t num_bins
);

Dendrograms are sampled as in hrg_consensus. A pair's score is the mean, over num_samples dendrograms, of the probability at the pair's lowest common ancestor, each sampled value rounded to the nearest multiple of 1/num_bins (Clauset, Moore and Newman, Nature 2008). The candidates are every pair (i < j) not joined in the graph seen as simple and undirected, zero scores included.

edges gets the pairs, two vertex ids each, and prob their scores, sorted by decreasing score, ties by pair. hrg is used and returned as in hrg_consensus. Progress is reported while sampling. Memory grows with n^2.

Parameters

• graph The graph, at least 3 vertices (directions, loops and multiplicities ignored).
• edges Output, may be NULL: the candidate pairs, two ids each, best first.
• prob Output, may be NULL: the score of each pair.
• hrg Input (when start is true) and output: the chain's last dendrogram.
• start true: start from hrg; false: start from a maximum likelihood fit.
• num_samples Number of dendrograms to sample, >= 1.
• num_bins Probabilities are rounded to multiples of 1/num_bins; >= 1.

Returns

OG_SUCCESS.

Errors

• OG_FAILURE The graph has fewer than 3 vertices (the code igraph 1.0.1 gives here).
• OG_EINVAL num_samples < 1 or num_bins < 1.
• OG_EINVAL start is true and hrg is not a valid tree with the graph's number of leaves.
• handler's code: The progress handler stopped the computation.
• OG_ENOMEM Not enough memory.

Complexity

O(num_samples x n^2) time and O(n^2) memory.

Checked

Within 0.025 of the exact posterior (binned) on 8 enumerated graphs, and on six more for 1, 7 and 25 bins; within 0.03 of igraph's recorded scores on a path; held-out edges: AUC 0.900 against igraph's 0.904 on one test graph, 7.3 against 6.5 hits in the top 30 on the karate club. Candidate lists equal igraph's.

C name

og_hrg_predict

In notebooks

Og.HrgPredict

igraph 1.0

igraph_hrg_predict

See also

hrg_consensus, hrg_fit

Deprecated: from_hrg_dendrogram without the probabilities.

og_error_t og_hrg_dendrogram(og_t *graph, const og_hrg_t *hrg);

Same tree graph as from_hrg_dendrogram(graph, hrg, NULL). Kept for code ported from igraph; new code should call from_hrg_dendrogram.

Parameters

• graph Output: the tree (not initialised before the call).
• hrg The HRG: a valid tree.

Returns

OG_SUCCESS.

Errors

• OG_EINVAL hrg is not a valid tree.
• OG_ENOMEM Not enough memory.

Complexity

O(n).

Checked

Same as from_hrg_dendrogram.

C name

og_hrg_dendrogram

In notebooks

Og.HrgDendrogram

igraph 1.0

igraph_hrg_dendrogram

See also

from_hrg_dendrogram

Installs a progress handler for the calling thread, or removes it.

og_progress_handler_t *og_set_progress_handler(
    og_progress_handler_t *new_handler
);

The handler applies to the calling thread only; other threads keep theirs. None is installed by default, and NULL removes the current one. The previous handler is returned, so a caller can put it back when done.

Parameters

• new_handler The handler to install, or NULL for none.

Returns

The handler that was installed before (NULL when none was).

Complexity

O(1).

Checked

Per thread; NULL uninstalls; the previous handler is returned (tested).

C name

og_set_progress_handler

In notebooks

Og.Native.og_set_progress_handler

igraph 1.0

igraph_set_progress_handler

See also

progress_handler_t, progress, progress_handler_stderr

#include "og.h"
#include <stdio.h>

static og_error_t show(const char *message, og_real_t percent, void *data) {
    (void) data;
    fprintf(stderr, "\r%s: %3.0f%%", message, percent);
    return OG_SUCCESS;          /* any other code would stop the computation */
}

int main(void) {
    og_t g;
    og_hrg_t hrg;
    og_vector_int_t parents;
    og_vector_t weights;
    og_progress_handler_t *old = og_set_progress_handler(show);
    og_famous(&g, "Zachary");
    og_hrg_init(&hrg, 0);
    og_vector_int_init(&parents, 0);
    og_vector_init(&weights, 0);
    og_hrg_consensus(&g, &parents, &weights, &hrg, false, 1000);
    og_set_progress_handler(old);
    og_vector_destroy(&weights);
    og_vector_int_destroy(&parents);
    og_hrg_destroy(&hrg);
    og_destroy(&g);
    return 0;
}

A ready-made progress handler that prints to stderr.

og_error_t og_progress_handler_stderr(
    const char *message,
    og_real_t percent,
    void *data
);

Writes the message and the percentage with one decimal ("message 42.0%") as one line on stderr and flushes it. A NULL message prints as an empty text. Install it with set_progress_handler(progress_handler_stderr).

Parameters

• message What is running (may be NULL).
• percent How much is done, 0 to 100.
• data Not used.

Returns

Always OG_SUCCESS.

Complexity

O(length of the message).

Checked

Prints the message and percentage; always succeeds; NULL message accepted (tested).

C name

og_progress_handler_stderr

In notebooks

Og.Native.og_progress_handler_stderr

igraph 1.0

igraph_progress_handler_stderr

See also

set_progress_handler, progress_handler_t

Reports progress to the calling thread's progress handler.

og_error_t og_progress(const char *message, og_real_t percent, void *data);

Calls the handler installed for this thread with the arguments unchanged, and returns its code unchanged; without a handler it returns OG_SUCCESS at once. Library code normally uses the macro OG_PROGRESS(message, percent, data), which wraps this call in OG_CHECK: when the handler refuses, the error goes through the error handler (which frees the cleanup stack) and the calling function returns the handler's code.

Parameters

• message What is running.
• percent How much is done, 0 to 100.
• data Context passed to the handler.

Returns

OG_SUCCESS when there is no handler, otherwise the handler's return value.

Errors

• handler's code: The handler returned something other than OG_SUCCESS.

Complexity

O(1) plus the handler.

Checked

OG_SUCCESS without a handler, the handler's code otherwise; the OG_PROGRESS macro's refusal path frees the cleanup stack (tested). hrg_consensus and hrg_predict report 0 to 100 while sampling.

C name

og_progress

In notebooks

Og.Native.og_progress

igraph 1.0

igraph_progress

See also

progressf, set_progress_handler, status

Reports progress with a printf-style message.

og_error_t og_progressf(const char *message, og_real_t percent, void *data, ...) OG_PRINTF_LIKE(
    1,
    4
);

Formats message with the arguments after data, as printf does, and passes the text to the calling thread's progress handler. The text is cut at OG_PROGRESS_MESSAGE_MAX (1000) characters; a NULL template passes an empty text. Without a handler nothing is formatted and OG_SUCCESS is returned. The macro OG_PROGRESSF((message, percent, data, ...)), with the arguments in one parenthesised group, wraps it in OG_CHECK.

Parameters

• message printf template.
• percent How much is done, 0 to 100.
• data Context passed to the handler.
• ... Values for the template.

Returns

OG_SUCCESS when there is no handler, otherwise the handler's return value.

Errors

• handler's code: The handler returned something other than OG_SUCCESS.

Complexity

O(length of the text) plus the handler.

Checked

Template formatting, the 1000-character cut, the OG_PROGRESSF macro and a NULL template tested.

C name

og_progressf

igraph 1.0

igraph_progressf

See also

progress, statusf

Installs a status handler for the calling thread, or removes it.

og_status_handler_t *og_set_status_handler(
    og_status_handler_t *new_handler
);

Per thread, like set_progress_handler. None is installed by default; NULL removes the current one. The previous handler is returned.

Parameters

• new_handler The handler to install, or NULL for none.

Returns

The handler that was installed before (NULL when none was).

Complexity

O(1).

Checked

Per thread; NULL uninstalls; the previous handler is returned (tested).

C name

og_set_status_handler

In notebooks

Og.Native.og_set_status_handler

igraph 1.0

igraph_set_status_handler

See also

status_handler_t, status, status_handler_stderr

A ready-made status handler that writes to stderr.

og_error_t og_status_handler_stderr(const char *message, void *data);

Writes the message to stderr exactly as given (no newline is added) and flushes it. A NULL message writes nothing. Install it with set_status_handler(status_handler_stderr).

Parameters

• message The status text (may be NULL).
• data Not used.

Returns

Always OG_SUCCESS.

Complexity

O(length of the message).

Checked

Writes the message; NULL message accepted (tested).

C name

og_status_handler_stderr

In notebooks

Og.Native.og_status_handler_stderr

igraph 1.0

igraph_status_handler_stderr

See also

set_status_handler, status_handler_t

Reports a status message to the calling thread's status handler.

og_error_t og_status(const char *message, void *data);

Calls the handler installed for this thread and returns its code unchanged; without a handler it returns OG_SUCCESS. The macro OG_STATUS(message, data) wraps it in OG_CHECK, so a refusing handler stops the calling function and frees its temporary objects.

Parameters

• message The status text.
• data Context passed to the handler.

Returns

OG_SUCCESS when there is no handler, otherwise the handler's return value.

Errors

• handler's code: The handler returned something other than OG_SUCCESS.

Complexity

O(1) plus the handler.

Checked

The OG_STATUS macro's refusal path (stops and frees) tested.

C name

og_status

In notebooks

Og.Native.og_status

igraph 1.0

igraph_status

See also

statusf, set_status_handler, progress

Reports a status message with a printf-style template.

og_error_t og_statusf(const char *message, void *data, ...) OG_PRINTF_LIKE(
    1,
    3
);

Formats message with the arguments after data and passes the text to the calling thread's status handler, cut at OG_PROGRESS_MESSAGE_MAX (1000) characters; a NULL template passes an empty text. Without a handler it returns OG_SUCCESS. The macro OG_STATUSF((message, data, ...)) wraps it in OG_CHECK.

Parameters

• message printf template.
• data Context passed to the handler.
• ... Values for the template.

Returns

OG_SUCCESS when there is no handler, otherwise the handler's return value.

Errors

• handler's code: The handler returned something other than OG_SUCCESS.

Complexity

O(length of the text) plus the handler.

Checked

Template formatting, the 1000-character cut, the OG_STATUSF macro and a NULL template tested.

C name

og_statusf

igraph 1.0

igraph_statusf

See also

status, progressf