register_estimator() adds an estimator function to the registry that
build_network() reads, so that build_network(data, method = name) calls
it the way it calls a built-in method; the package registers its fourteen
built-in methods with this function when it loads. A name already in the
registry is replaced, built-ins included, without a message.
list_estimators() shows what is
registered and remove_estimator() takes
an entry out.
A name that build_network() maps to a different built-in method (an
alias such as "tna" or "ebicglasso") is resolved to that method before
the registry is read, so an estimator registered under it is never called;
pick a name that is not an alias.
Arguments
- name
The name the estimator is called by, as
methodinbuild_network(): a single non-empty string. A name already registered is replaced. A name that is a method alias (such as"tna") is stored with a warning of classnestimate_alias_shadowed, becausebuild_network()resolves the alias to the built-in method and never calls the registered function.- fn
The estimator function. Its first argument is
data, and it must accept..., becausebuild_network()passes every setting by name. It returns a list withmatrix(the square numeric weight matrix),nodes(the node names, in the matrix's order) anddirected(TRUEorFALSE); see Details for the optional elements.- description
A short description of the estimator, a single string, shown by
list_estimators().- directed
Whether the estimator produces directed networks,
TRUEorFALSE.build_network()reads it to decide whetherlevel(the multilevel decomposition) is allowed: a directed estimator refuses it. The edges of the network follow thedirectedelementfnreturns, butbootstrap_network()reads this registered flag to build its edge tables, so the two should agree.
Details
build_network() calls the function as fn(data = data, ...), where ...
holds the params list, the further arguments given to build_network()
and a format setting, which is why fn must accept .... When actor
names a column of wide or association data (long data is prepared by
build_network() itself) and fn has an id_col argument (or, failing
that and for data that is not one-hot, an id argument), the actor
column is passed under that name unless params already sets it. Scaling,
thresholding and the edge list are then applied to the returned matrix,
as for a built-in method.
Besides matrix, nodes and directed, the returned list may hold
cleaned_data, the data frame the network was estimated from, which
build_network() splits into the network's data and metadata fields;
any other named element is copied onto the netobject, replacing a field
of the same name. A return value without matrix, nodes or directed
makes build_network() stop with an error.
Note
The idiographic package exports a function with the same
name. With both packages attached, the one attached last masks the
other; write Nestimate::register_estimator() to call this one.
Examples
my_fn <- function(data, ...) {
m <- cor(data)
diag(m) <- 0
list(matrix = m, nodes = colnames(m), directed = FALSE)
}
register_estimator("my_cor", my_fn, "Custom correlation", directed = FALSE)
df <- data.frame(A = rnorm(20), B = rnorm(20), C = rnorm(20))
net <- build_network(df, method = "my_cor")
remove_estimator("my_cor")