nwcommands 3.12.1

Menu change that 3.12.0 described but did not contain.

Changed

• Menu. With nwinstall, gui, the "Statistical Models" menu keeps its four core entries and has exactly one entry for each model package: "Stochastic actor-oriented model (nwsaom)" and "Exponential random graph model (nwergm)". The other dialogs of these packages (Bayesian estimation, several networks, multiplex, meta-analysis, describe, postestimation, simulation) are opened by buttons in the main dialogs of nwsaom 1.3.2 and nwergm 1.3.3. Before, all of them were listed in the menu one after the other.

nwcommands 3.12.0

The dialogs of the model packages are no longer one flat list in the menu.

Changed

• Menu layout. With nwinstall, gui, the "Statistical Models" menu keeps its four core entries (correlate, CUG, QAP, utility scores) and adds one submenu per model package: "Stochastic actor-oriented models (nwsaom)" (fit a model, several networks that change together, multiplex networks, Bayesian estimation, meta-analysis, describe the data, postestimation) and "Exponential random graph models (nwergm)" (fit a model, simulate networks, postestimation and goodness of fit). Entries and submenus appear only for dialogs that are installed. The Mata library is unchanged, so the model packages need no release.

nwcommands 3.11.1

Fixes for clashes between your own Stata matrices, scalars and variables and those of nwcommands, and one plot error. The Mata library is unchanged, so the four model packages need no release.

Fixed

• Commands no longer overwrite or delete your own Stata matrices, scalars and variables. nwcomponents, nwkcore, nwconcor, nwcommunity, nwmodularity, nwplot and nwqap used plain names for their working matrices and scalars (comp_id, comp_sizeid, block_id, core_id, comm_sizeid, components, communities, modularity, nsizerow, pvalues, permvar, reg_results and others). A matrix or scalar of yours with the same name was replaced, and often removed when the command finished (nwplot also created and dropped a variable _id). They now use private temporary names. The results in r() and e() are the same. The new test test_stata_userspace.do guards this.
• nwplot with components() stopped with error 3301 (subscript invalid) when the data set had more or fewer rows than the network has nodes (for example after you worked with a smaller network on the same data). The nodes of each component are now found from the network itself.

Known limitation

• When a command stops with an error half way, its private Mata variables (names starting with __nw) can stay until the next run or mata: mata clear. They never replace your own variables.

nwcommands 3.11.0

Fixes for clashes between your own Mata variables and the Mata variables of nwcommands. The Mata library is unchanged (the library hash is the same as in 3.10.0), so the four model packages need no release and work with 3.10.0 and with 3.11.0.

Changed

• The registry of networks is now the Mata global __nw (it was nw). This is visible only to scripts that address the registry directly: nw.nws.pdefs[1] must now be written __nw.nws.pdefs[1], and r(netobj) strings that a script stored before upgrading must be created again. Code that uses r(netobj), _nwsyntax or the nwtomata commands needs no change.

Fixed

• Commands no longer overwrite or delete your own Mata variables. About 30 commands (among them nwplot, nwcommunity, nwcomponents, nwkcore, nwconcor, nwcloseness, nwburt, nwqap, nwmixing, nwexpand, nwlattice, nwneighbor, nwutility, nwset, nwcorrelate, nwdendrogram) used short global Mata names such as Coord, M, temp, reach, far or comm_id for their own work. A variable of yours with the same name was replaced, and often deleted when the command finished. They now use private names (__nwplot_Coord and so on) and remove them again; several commands (nwtriads, nwmotifs, nwmixing, nwcug, nwdyadprob, nwfromedge, nwhierarchy, nwimport, nwload) also no longer leave temporary Mata variables behind. The new test test_mata_userspace.do guards this.
• A Mata variable called nw broke every command. The registry of all networks was the global Mata variable nw, so a user's own nw (a common name) replaced it and the next command stopped with "type mismatch: exp.exp: transmorphic found where struct expected" (cured only by mata: mata clear). The registry is now __nw. Scripts that address the registry directly (nw.nws.pdefs[1], r(netobj) strings stored for later) must say __nw.nws.pdefs[1]; code that goes through r(netobj) or _nwsyntax needs no change. The Mata library is unchanged.

nwcommands 3.10.0

Layouts that use the tie values, faster and wider similarity and null-model commands (native plug-in generation 12), and tests of the native kernels that run without Stata. The Mata library is unchanged (the four model packages need no release). The macOS plug-in is rebuilt; the Linux and Windows plug-ins come from the CI build after the push.

Results that change (read before you re-run old scripts)

• Plots of valued networks get different node positions by default. nwplot (default layout(kk) and layout(frucht)) and nwmovie/nwmoviexy (each wave) now use the tie values as strengths, as igraph::plot() does for a graph with a weight attribute: strongly tied nodes lie closer together. kk: the ideal distance of two nodes is the shortest path with edge length 1/value; frucht: the attraction along a tie is multiplied by its value (layout_with_kk(weights=) takes edge lengths, so one passes 1/value; layout_with_fr(weights=) takes strengths). The values are divided by their mean first, so the unit of the values does not matter. Option binary restores the layouts of 3.9 and earlier (they are bit-identical for the same seed). Unvalued networks, two-mode networks, networks whose ties all have the same value, and the layouts mds, mdsclassical, hierarchy, bipartite, circle, grid are not affected.
• A signed network (a tie value that is not positive) keeps the unweighted layout and prints a note, as igraph::plot() does (igraph's layout_with_fr()/layout_with_kk() refuse non-positive weights; plot() warns and ignores the weights).
• nwmovie: binary is now also passed to the layout of the first network.
• nwcug on a two-mode network no longer stops with error 6088: it draws from four null models (see Added). One-mode networks are as before.
• nwcorrelate (and with it nwsimilar, type(pearson)) formed the n x n matrix four times (nwset, mat() evaluated its argument four times): 10.6 seconds at 5,000 nodes. It is formed once now; the numbers are the same.

Added

• Kernel 51: node-by-node similarities of nwsimilar (pearson, matches, jaccard, hamming, crossproduct), nwdissimilar (euclidean, manhatten, nonmatches, jaccard, hamming) and nwcorrelate, all contexts and valued or binary, directed or not: the cells come from the stored ties instead of dense matrix products. 5,000 nodes (10 ties per node): nwsimilar pearson 0.45 s (10.6 s before, 24 times faster), the other types 0.36 to 0.38 s (1.0 to 1.2 s before), nwdissimilar, type(manhatten) 0.37 s (about 25 minutes in Mata: it had no closed form and ran O(n^3) loops). Differences from the Mata code below 1e-13 (2,688 combinations in the development checks); a network with missing tie values and a platform with an older plug-in keep the Mata code. R: the definition written out in tools/verify_native390.R; igraph::similarity agrees on the pairs that are not adjacent.
• Kernel 52: nwcommunity, algorithm(dirtlpa), the label propagation LPAwb+ of Beckett (2016) in its repeated form DIRT_LPA+ (R: bipartite::DIRT_LPA_wb_plus), for two-mode networks; options reps() (default 10) and minmodules() (default 4) as reps and mini of the R function; reproducible with seed(); plug-in only (without a generation-12 plug-in the command stops with a message that asks for the update). Southern women: Barber's Q 0.3455 (the best known, as with Louvain); ftdirectors_se: 0.95110 in 12 seconds against 0.95101 for 100 starts of the Louvain search (0.2 seconds).
• Kernel 53 and nwcug for two-mode networks: condition(density|mode1degree|mode2degree|degrees) (equivalents: vegan::nullmodel r00, r0, c0, curveball; igraph::sample_bipartite(type = "gnm")), option trades(); the draws are made natively on the list of ties and written into one copy of the network. The null means and standard deviations agree with vegan::nullmodel (Southern women, NODF).
• Kernel 54: the sweeps of the weighted Kamada-Kawai layout of _nwwlayout (nwplot and nwmovie layout(kk) on valued networks) run natively: 2,000 nodes 0.74 s against 7.0 s in Mata, same start coordinates give the same layout (differences below 1e-14); the Mata code stays as the fallback.
• _nwwlayout.ado (internal): the weighted layouts. kk with values: shortest weighted paths and Gauss-Seidel stress majorization; the sweeps run in the plug-in (kernel 54, below), the Mata code is the fallback for a missing or older plug-in (about 1.5 s for 1,000 nodes and 18 s for 5,000 nodes in Mata).
• Dialog nwmovie: checkbox binary.
• Test cscripts/test_native390.do (fixtures cscripts/native390_fixture/, R script tools/verify_native390.R).
• Test: cscripts/test_wlayout.do.
• Tests of the native kernels without Stata (native/test/): test_kernels.c compiles the shipped kernels against a stand-in for the plugin interface and checks 170 cases (kernels 1 to 54): every kernel against results recorded from the macOS plugin (native/test/fixtures/golden.txt), against the R/igraph/bmotif fixtures of the cscripts, against textbook answers (stars, paths, rings, complete graphs), properties of the null-model draws (margins and counts exact), and large sparse cases of 20,000 to 100,000 nodes with sums or cell numbers above 2^31. make -C native test runs it anywhere with a C compiler.
• The workflow .github/workflows/test-kernels.yml runs the harness on Linux (gcc, with sanitizers), macOS (clang) and Windows (MSVC cl) for every push or pull request that touches native/, and uploads the compiler warnings. It builds and commits nothing.

Changed

• The Windows plugin is compiled with optimisation (/O2); it was built without it, so the Windows kernels ran as unoptimised code. Results are unchanged.

Fixed

• 64-bit counters in the native kernels (Windows). The C kernels counted nodes, ties, indices, offsets and products of them in long, which is 32 bits in the Windows build (MSVC) and 64 bits on macOS and Linux. All 1,245 uses are now a 64-bit type (nwint, native/nwtypes.h), so a value above 2^31 can no longer wrap on Windows only. No result changes on macOS or Linux (the kernels of generation 11 are bit-identical); within the documented limit of 100,000 nodes no wrong result was found on Windows either, the change closes the latent cases (the diagnostic counters of very long searches, bit-set offsets above about 370,000 nodes, result sizes above 2^31 cells). Also: the Windows build uses the compiler's own bit-scan instruction for the lowest set bit, the headers include what they use (<time.h>, <stdlib.h>, <string.h>), and a malformed argument string no longer dereferences a null pointer.

Notes

• nwsimilar, type(pearson) ignores context() (it calls nwcorrelate with its default, the outgoing ties); unchanged.
• nwsimilar, type(hamming) counts the left-out positions i and j as matches (two per profile); unchanged, documented in the R script.

nwcommands 3.9.2

The "Network Analysis" menu is set up once, whatever you run and however often. Only nwinstall (ado, help file, dialog) and its tests changed: no command, result, Mata library or plug-in differs from 3.9.1 (the four model packages need no release).

Results that change (read before you re-run old install scripts)

• nwinstall never writes the menu line twice. The line nwinstall, usermenu is kept at most once in profile.do: the older nwinstall, downloadoff (and spellings with other spacing or a quietly) count as the same line, and extra copies already in the file are dropped when you run gui, all or everything (the rest of the file is kept byte for byte). A menu line of another origin (your own window menu ... "Network Analysis" line, nw_menu, a menu line in another profile.do that Stata reads) stops nwinstall from adding a second menu; it names the line and the file. Before, running nwinstall, gui after a hand-written menu line gave two menus.
• The menu is rebuilt from an empty User menu, so running nwinstall twice in one session shows each entry once (before: twice). This clears other entries you added to the User menu in that session.
• nwinstall, gui, all and everything print one line about the menu ("installed", or "already set up in ...").
• nwinstall, remove now also uninstalls the numbered packages (nwcommands-ado1, -hlp1, -dlg1, ...); before it only tried the unnumbered names of the old layout and left the files behind.

Added

• nwinstall, everything (and all) set up the menu and the dialog boxes permanently (this was already so in 3.9.1; the help and the website now say it). New option nogui (dialog: checkbox) leaves the menu and the profile.do line out. models and modelpkg() alone never touch the menu.
• nwinstall, dupcheck reports dialog files (.dlg) that exist in more than one folder of the ado path and says which copy Stata uses; nothing is deleted. all, dialog and localcopy run it at the end. It returns r(ndup).
• A menu that cannot be built (batch run, Stata without menus) is a note, not an error: an install in a do-file or CI run goes on.
• Test: cscripts/test_nwinstall_gui.do; cscripts/test_nwinstall_everything.do extended (one line after everything twice, nogui, remove).

nwcommands 3.9.1

Added

• The short install address https://nwcommands.org/net/: net install nwcommands, from(https://nwcommands.org/net/) replace. The deploy workflow copies the starter package (stata.toc with the starter entry, nwcommands.pkg and the files it lists) into net/ of the website after the site build (tools/make_net_dir.sh; test: tools/test_net_dir.sh). The GitHub address keeps working and nwinstall still fetches the rest from GitHub. The install lines in the README, help files, error messages and the website show the short address first.
• tools/release_preflight.py checks that the deploy workflow copies the starter and, with --post, that https://nwcommands.org/net/stata.toc is reachable.

No command, result, Mata library or plug-in changes.

nwcommands 3.9.0

Plot appearance: nwplot, nwmovie and nwplotmatrix now show what a valued, signed or two-mode network is made of, and nwturnover is right on two-mode networks. Only the ado and help files changed: no new plugin generation, no change of the Mata library (the four model packages need no release).

Results that change (read before you re-run old analyses)

• nwplot draws the tie values of a valued network as edge widths by default (before: all edges the same width unless edgesize(<network>) was given). The widths run from 1 to 4 units (largest absolute value widest, at most 15 width classes; ties of equal value keep the default width). binary gives the old picture. Colours never follow the values unless edgecolor() is given. edgesize() keeps its 1 to 8 range. nwmovie inherits the change (and passes binary on).
• nwplot draws a signed network (valued, negative ties) with positive ties solid navy and negative ties dashed cranberry, and a legend (before: all ties the same colour, a negative tie looked like a positive one). The width follows the absolute value. nosign gives the old colours; an own edgecolor() wins. A negative edgesize() value no longer makes the plot fail.
• nwplot of a two-mode network draws the two modes with different symbols and colours and a legend (circle and diamond; before: one symbol and colour for all nodes) unless color() or symbol() is given.
• nwplotmatrix has a colour legend (value classes; "no tie" and "tie" on a binary network) by default (legend(off) as before) and, on a two-mode network, puts the nodes of one mode next to each other (unless sortby() or group() is given) with a line between the modes.
• nwturnover on two-mode networks no longer counts the cells inside a mode (they are structurally missing, but were read as ties present in both networks, so stable, formed and dissolved ties and the Jaccard index were wrong); only ties between the modes count.

Added

• nwplot: options binary and nosign (dialog: tab "More options"); stored results r(edgewidth), r(signcolor), r(modesymbols). nwmovie: options binary and nosign, passed to nwplot. Test: cscripts/test_plotfix.do.
• nwaltergen: wmean prints one note on a signed network (weights with their signs). nwdyadprob: density() with neither a weight network nor mat() stops with r(198) and a message (was a raw r(3499)).

Fixed

• nwplot ... if ..., edgesize(<network>) failed (a mistyped temporary network name); it works.

Speed (no change in results)

• nwgeodesic ..., force on an unvalued network took 37 s at 600 nodes because option force sent it to the Mata Dijkstra routine; it now uses the same hop-count routine as the call without force (0.03 s at 600 nodes, 1.2 s at 5,000). The distances are identical (checked on 90 combinations of binary, valued, directed and disconnected networks and options against 3.8.0). The Mata library did not change.

nwcommands 3.8.0

Two-mode dispatch, and the bipartite motifs of bmotif. Plugin generation 11 (native counting of bipartite motifs). The Mata library did not change, so the four model packages need no new release (they do not call the commands that changed and still require nwcommands 3.6.0 or later). A platform whose plugin has not been rebuilt yet (Linux, Windows before the CI build) has no nw2motifs/nwmotifs on a two-mode network, the rest works as before.

Results that change (read before you re-run old analyses)

• A network declares itself two-mode when it is created, and a command that has a two-mode form of the same concept now uses that form on a two-mode network without being asked. The option onemode forces the one-mode computation on the bipartite graph (what igraph does with a bipartite graph). Calls on one-mode networks, and all calls with onemode, give exactly what 3.7.0 gave (checked bit for bit in cscripts/test_dispatch380.do). The commands:
  • nwcloseness and nwbetween on a two-mode network give the normalisations of Borgatti and Everett (1997) by default: closeness is the smallest possible farness of a node of its mode divided by its farness, betweenness is divided by the largest value a node of its mode can reach (before, the raw closeness (N-1)/farness and raw betweenness of the bipartite graph; those are onemode). twomode, the earlier way to ask for this, is still accepted as a synonym; onemode together with twomode is error 198. On a two-mode network standardize of nwbetween is this standardisation. r(bw_central) is computed from the raw scores whatever the option (before, with twomode, from the standardised scores).
  • nwmotifs on a two-mode network counts the bipartite motifs of Simmons et al. (2019, bmotif) and the positions of the nodes in them (the table and options of nw2motifs) instead of the 4-node census of the bipartite graph read as a one-mode graph, which is onemode. The options plot and name() have no two-mode form (error 198).
  • nwdegree and nwclustering on a two-mode network gave the two-mode result already (they handed the call to nw2degree and nw2clustering with a note). They now do it without the note and take all options of the two-mode form (raw for the count; level(), ra and replace for nwclustering); an option that has no two-mode form (isolates, standardize, in(), out(), outputoff; silent and symmetrize of nwclustering) is named in one note and ignored. onemode gives the degree (the number of ties) and the clustering coefficient (0) of the bipartite graph.
• Commands that already followed the rule are unchanged (nwcommunity and nwmodularity: the bipartite modularity of Barber, onemode for Newman; nwsimilar and nwdissimilar: nodes are compared with nodes of their own mode; nwspectral and nwrandomwalk: onemode reads the graph as a one-mode graph).

Changed

• nw2degree, nw2clustering and nw2motifs are aliases of nwdegree, nwclustering and nwmotifs: they keep their names, their options and their results (same variables, same r(), same messages; cscripts/test_dispatch380.do compares them with the 3.7.0 results), and they still stop with error 198 on a one-mode network. nw2project and nw2nested have no one-mode counterpart and keep their own names.
• The help files say in one wording what a command does with a two-mode network ("Two-mode: two-mode form by default ..."); the dialogs of the five commands have the new options (onemode, raw, ra, level). nwnetworktypes states the rule once.

Added

• nw2motifs, the bipartite motifs of a two-mode network (Simmons et al. 2019, bmotif; Baker et al. 2015; Stouffer et al. 2012): the 17 motifs of two to five nodes (44 with the option sixnode), their frequencies (r(motifs), with the four normalisations of bmotif::mcount through normalise) and, for every node, the number of times it holds each of the 46 (148) node positions, stored in variables (generate()) or a matrix (matrix()), with the twelve normalisations of bmotif::node_positions (posnorm()). Motif and position numbering are those of bmotif (table in the help file). The counting runs in the native plugin without matrices of the size of the network (the 5,092 + 455 directors: the motifs and positions up to five nodes in 0.04 s, up to six nodes in 0.05 s; bmotif::mcount and node_positions together need 54 s for the five-node set and cannot do six nodes on that network). Results equal bmotif::mcount and bmotif::node_positions (bmotif 2.0.2) on the toy network, the Southern women, the Swedish directors, a subsample of them and 34 random networks (4 of them larger), for the motif table and for every node (cscripts/test_nw2motifs.do, fixture cscripts/native380_fixture, made by tools/verify_native380.R). A valued network counts the ties above zero (the usual note); the weighted measures of bmotif are not offered. A plugin older than the command (or missing for the platform) stops the command with a message that tells how to update; there is no slow Mata fallback.
• nwmotifs counts the bipartite motifs on a two-mode network (see Results that change); nw2motifs is the same command under its older name.

nwcommands 3.7.0

Plugin generation 10 (native kernels for the two-mode and valued commands), valued closeness at any size, level labels of two-mode networks in files, and a few corrections. The Mata library did not change. The four model packages are released with it as patch releases (nwsaom 1.0.10, nwergm 1.2.3, nwdynam 1.1.3, nwrem 1.0.8; they still work with nwcommands 3.6.0). A platform whose plugin has not been rebuilt yet (Linux, Windows before the CI build) keeps the Mata code and gives the same results, slowly.

Results that change (read before you re-run old analyses)

• A valued network of more than 100 nodes no longer gets the hop-count closeness or distances silently. nwgeodesic (and through it nwcloseness) computed the distances of a valued network of more than 100 nodes on the unvalued network and only said so ("Calculated on unvalued network because network size exceeds 100"); nwcloseness never passed force on, so the weighted closeness was out of reach. They now compute the least-cost distances (cost 1/w^alpha, alpha(-1) = igraph's lengths) at any size with the native plugin; closeness, farness and nearness of such networks therefore differ from before (they used steps). A platform whose plugin is older stops with r(198) unless force (slow Mata routine) or binary (steps) is given. force of nwcloseness is passed on to nwgeodesic.
• nwshared on a directed network without the option undirected now stops with error 198 and a message, as its help file always said. 3.6.0 ran without the option and without a message. Add undirected (the network is symmetrized first) to get the earlier result.
• The native bipartite Louvain search of nwcommunity does not give the partition of the Mata search for the same seed (the two use different random generators and neighbour orders). With the new plugin the result is the same on every platform for a given seed; Barber's Q is the same on the Southern women (0.3455) and statistically the same on larger networks. nwpermute, swap draws differently for the same reason (see Added).

Added

• Native Dijkstra kernels for nwcloseness (sums and reachability without the n x n matrix: 1,000 nodes 0.15 s, 10,000 nodes 14 s) and nwgeodesic on valued networks; equal to the Mata distances and to igraph::closeness with lengths 1/w and w (reachable-nodes form).
• Native kernels in the core plugin: the bipartite (Barber) search of nwcommunity on two-mode networks (27 times faster on the 5,092 + 455 directors: 2.4 s to 0.09 s), the weighted walk of nwpagerank, the maximum-weight matching of nwmatching on valued networks (Hungarian method; the 455 + 5,092 case of the directors takes 0.2 s, the Mata routine cannot do it), the tie swapping of nwpermute, swap (works on the list of ties, no n x n matrix) and the weighted betweenness of nwbetween on valued networks (1,000 nodes: 0.13 s instead of 111 s; 10,000 nodes 15 s). Results equal the Mata routines (PageRank and betweenness to 1e-9, the matching exactly up to 1,500 nodes in the larger mode and with the same total value above), and R: igraph::page_rank, igraph::betweenness with lengths 1/w, igraph::max_bipartite_match with weights (all in cscripts/test_native370.do).
• The random starting orders of the two-mode search of nwcommunity and the exchanges of nwpermute, swap come from a generator of their own that is seeded from set seed (or seed()): the same seed gives the same result on every platform with the new plugin. They are therefore not the same draws as in the Mata code; Barber's Q is the same on the Southern women (0.3455) and statistically the same on the directors.

Fixed

• nwexport and nwimport keep the level labels of a two-mode network (for example "women" / "events"): Pajek gets a comment line before *Vertices (Pajek ignores it), GML the graph attributes nwmodelabel1 and nwmodelabel2, the edge list the labels in the mode columns instead of 1 and 2. UCINET DL has no place for them (a file read back has the labels "rows" and "columns"). Test: cscripts/test_small370.do.
• nwimport, type(ucinet): a rectangular matrix with the same number of rows and columns (nr= and nc= given, for example 3 women by 3 events) was read as a one-mode network and failed; it is now read as a two-mode network.
• nwshared: the documented requirement of undirected on a directed network is now enforced (see Results that change); help, test and the network-types tables say so.
• nwinduced error message for a directed network no longer points to an internal file.
• Website pages and logs show "plugin build" instead of "plugin protocol" in the output of nwsaom version.
• nwmixing printed stray "invalid name" lines before the table (fixed in 3.6.0, see below); test_small370.do repeats the check.