REST API Documentation for the BPNet Web Service

REST API Documentation for the BPNet Web Service

September 2013

1 Introduction

BPNet is a program for the simulation and estimation of exponential random graph (or p∗) modelson bipartite networks. This document describes only the REST (Representational State Transfer) API(Application Programming Interface) for BPNet, which allows it to run as a web service from whichusers can request BPNet functions. Documentation for the BPNet program itself can be found along withthe original BPNet Windows application at http://sna.unimelb.edu.au/PNet. A descriptionof the concepts and algorithms implemented by BPNet is given in Wang et al. (2009); Wang (2013);a more general introduction to exponential random graph models for social networks can be found inRobins et al. (2007); Lusher et al. (2013).

The BPNet REST API uses JSON (JavaScript Object Notation) for its input data. All queries to theBPNet service use the HTTP POST method, supplying input information in a JSON object. The MIMEmedia type in the HTTP content-type should therefore be specified as application/json (seeRFC 4627). Note (as specified in RFC 4627) also that all strings in JSON must be enclosed in doublequote marks ("), not single quote marks (’), unlike JavaScript which can use either.

The output returned from the BPNet REST API may either be JSON or XML. This is requested bysetting the HTTP accept header to application/json for JSON or to application/xml forXML.

As well as the actual BPNet services, requested using the POST method as described above, theREST API also provides the capability, using the GET and PUT methods, to get or delete zip archivesof network files in Pajek format that are generated by simulation and goodness-of-fit requests.

The data type names used in this document are Java types. For example long is a 64-bit signedinteger, int is a 32-bit signed integer, float is a 32-bit floating point number and double is a 64-bitfloating point number.

2 Network data format

2.1 Preliminaries

A network (or graph) can be represented in several ways. Two common representations are matricesand adjacency lists. In addition, since a bipartite graph by definition contains two distinct sets of nodes,which have connections only between nodes where each node is in a different set, another representationfor these graphs is possible. This is the biadjacency matrix, which rather than being a square n×nmatrixfor n nodes, is a rectangular n×m matrix for n nodes in one class and m nodes in the other class. Therelationship between the biadjacency matrix for a bipartite graph and its adjacency matrix is

A =

(0 BBT 0

)(1)

1

http://sna.unimelb.edu.au/PNet

http://www.ietf.org/rfc/rfc4627.txt

where B is the n × m biadjacency matrix and A is the (m + n) × (m + n) adjacency matrix. Notethat this matrix is symmetric and therefore the graph is undirected: a biadjacency matrix specificationimplies that the bipartite graph is undirected since there is no ability in that specification to distinguishan edge a→ b from an edge b→ a. BPNet deals only with undirected bipartite graphs.

For example, consider a bipartite graph with 7 nodes, labelled 1, 2, 3, . . . , 7, with nodes 1, 2, 3, 4 inclass 0 and nodes 5, 6, 7 in class 1. If the edges are 1-5, 1-6, 2-6, 2-7, 3-7 and 4-5 then the biadjacencymatrix is:

B =

1 1 00 1 10 0 11 0 0

(2)

and therefore the adjacency matrix is:

A =

0 0 0 0 1 1 00 0 0 0 0 1 10 0 0 0 0 0 10 0 0 0 1 0 01 0 0 1 0 0 01 1 0 0 0 0 00 1 1 0 0 0 0

(3)

The adjacency list could be specified as:

1: 5,6

2: 6,7

3: 7

4: 5

5: 1,4

6: 1,2

7: 2,3

for the full adjacency matrix, or as:

1: 5,6

2: 6,7

3: 7

4: 5

where only edges from class 0 to class 1 nodes are shown, since the rest are redundant (since the matrixis undirected).

The BPNet REST API allows network spedifictions in two distrinct formats. One uses edge lists,where each edge is specified by the identifiers of the two nodes it is adjacent to. The other uses adjacencylists, as described above.

2

2.2 JSON network data specification (NetworkX format)

The network data format is designed so that it is exactly the format produced by the NetworkX json.dumps(json graph adjacency data())functions, see http://networkx.lanl.govparticularly: http://networkx.lanl.gov/reference/readwrite.json_graph.html.

This format has been extended by adding various lists for attributes in each node as this data isrequired by BPNet, but this is accommodated in NetworkX since it can handle any data type beingadded as key/value pairs in the graph dictionary structure. In addition other arbitrary node and edgeproperties may be supplied in the JSON input but will be ignored by BPNet. Hence arbitrary furtherinformation such as geocoding or other node or edge properties can be included in the JSON but willnot result in an error and will be ignored when there is no corresponding field defined here.

As an example of the JSON format, the following graph has four nodes labelled 1,2,3, and 4, andhas the following edges: 1-2 and 1-3 (only; 4 is a singleton node):

1 {"directed": false,2 "graph": [],3 "nodes": [{"id": 1}, {"id": 2}, {"id": 3}, {"id": 4}],4 "adjacency": [[{"id": 2}, {"id": 3}], [{"id": 1}], [{"id": 1}], []],5 "multigraph": false}

The fields are described in detail in Table 1, but essentially nodes is a list of nodes, and adjacencyis a list of lists where the list at position i in the list is the list of nodes adjacent to the node at position iin the nodes list.

The id and bipartite node attributes are defined by NetworkX and are required for each node.All other attributes (such as those in Table 3 are defined by BPNet and are optional. The edges definedin the adjacency lists use only the mandatory id attribute which identifies one of the two nodes that theedge connects (the other is defined by its position in the adjacency list). Arbitrary other attributes areallowed as well as id for an edge, but as BPNet does not use edge attributes these are ignored.

Table 1: Network attributes

Attribute Type Descriptiondirected boolean If specified, must be false for bipartite graphs; only undirected

bipartite graphs are supportedgraph list of list of string Optional list of (key,value) attributes attached to this network. Not

used except to attach comments as strings, but specified in theNetworkX JSON format.

nodes list of nodes Each node must have the id attribute specifying a unique identi-fier for that node (across all nodes in both classes in the network)and the bipartite identifier specifying whether the node is inclass 0 or 1. It may optionally have BPNet attribute values speci-fied using the attributes in Table 3.

adjacency list of list of edges Adjacency lists. Each element in the outer list is itself a list, corre-sponding to a node in the nodes list (in the same position in thelist), of nodes to which that node is adjacent. That is, if the nodelist is [1,2,3] the adjacency list is [ [nodes connected to 1], [nodesconnected to 2], [nodes connected to 3] ].

multigraph boolean Allow parallel edges. Must be false if specified; multigraphsare not supported.

3

http://networkx.lanl.gov

http://networkx.lanl.gov/reference/readwrite.json_graph.html

http://networkx.lanl.gov/reference/readwrite.json_graph.html

Table 2: Node attribute name specification

Attribute Type DescriptionbinaryAttributesA list of string names of the binary attributes for bipartite=0 nodes onlybinaryAttributesP list of string names of the binary attributes for bipartite=1 nodes onlybinaryAttributesAP list of string names of the binary attributes for both classescontinuousAttributesA list of string names of the continuous attributes for bipartite=0 nodes

onlycontinuousAttributesP list of string names of the continuous attributes for bipartite=1 nodes

onlycontinuousAttributesAP list of string names of the continuous attributes for both classescategoricalAttributesA list of string names of the categorical attributes for bipartite=0 nodes

onlycategoricalAttributesP list of string names of the categorical attributes for bipartite=1 nodes

onlycategoricalAttributesAP list of string names of the categorical attributes for both classes

Each node can have any number of binary, continuous, and categorical attributes. For BPNet, eachnode must have the same attributes specified. The names of the attributes are in a corresponding listoutside the network specification (in the request data to BPNet, which contains the network specifica-tion), so as not to have all the names duplicated in each node. The attributes used for specification ofthese names are shown in Table 2. Note that there are sets of attributes for A (bipartite = 0) nodes, forP (bipartite = 1) and for A&P (both) nodes, so not all nodes need have the same corresponding attributelists (except in the last case). However all A nodes must have the same set (consisting of all A attributesand then all A&P attributes), and similarly for P (bipartite=1) nodes: each will have all P and then allA&P attributes. Note that the attributes just described here are attributes used by BPNet, they are notJSON attributes in the sense of being named before the colon in the JSON syntax. This format is usedto facilitate the use of the Spring 3 REST API and Jackson JSON processing as used by AURIN (sinceusing JSON attributes would require naming the attributes in the REST processing code in advance, butthese names are specified only at runtime in each request). The node attributes are listed in Table 3. Notethat edges have these same names reserved, but edge attributes are not supported in BPNet.

Table 3: Node attributes

Attribute Type DescriptionbinaryAttributeValues list of boolean values of the binary attributes for this nodecontinuousAttributeValues list of float values of the continuous attributes for this nodecategoricalAttributeValues list of int values of the categorical attributes for this node

This structure is completely general. Hence we do not specify bipartite graphs by a biadjacency ma-trix (or some sort of bipartite adjacency list, although that would be more efficient), but by the NetworkXconvention of having a bipartite attribute which is 0 or 1 to indicate which of the two classes a nodebelongs to. For BPNet these correspond to the A and P class respectively. For example, the bipartitenetwork represented by the JSON in Figure 1 has nodes 1,2,3 and 4 in class 0 and nodes 5, 6 and 7 inclass 1, with edges 1-5, 1-6, 2-6, 2-7, 3-7, and 4-5. This is the example network from Section 2.1.

For a network with n class 0 nodes and m class 1 nodes, the full specification of the adjacency listshas n+m edge lists, one for each of the n+m total nodes. But since a biadjacency matrix only specifiesundirected bipartite graphs, a more compact specification is possible where only the edge lists for the nclass 0 nodes, or alternatively the m class 1 nodes, are specified. Hence the previous example can alsobe more compactly represented (with the adjacency list containing only the edges adjacent to nodes ofbipartite class 0) with the JSON shown in Figure 2.

4

1 {"directed": false,2 "graph": [["example", "bipartite"]],3 "nodes": [{"bipartite": 0, "id": 1}, {"bipartite": 0, "id": 2},4 {"bipartite": 0, "id": 3}, {"bipartite": 0, "id": 4},5 {"bipartite": 1, "id": 5}, {"bipartite": 1, "id": 6},6 {"bipartite": 1, "id": 7}],7 "adjacency": [[{"id": 5}, {"id": 6}],8 [{"id": 6}, {"id": 7}],9 [{"id": 7}],

10 [{"id": 5}],11 [{"id": 1}, {"id": 4}],12 [{"id": 1}, {"id": 2}],13 [{"id": 2}, {"id": 3}]],14 "multigraph": false}

Figure 1: Example JSON data for a small network

1 {"directed": false,2 "graph": [["example", "bipartite"]],3 "nodes": [{"bipartite": 0, "id": 1}, {"bipartite": 0, "id": 2},4 {"bipartite": 0, "id": 3}, {"bipartite": 0, "id": 4},5 {"bipartite": 1, "id": 5}, {"bipartite": 1, "id": 6},6 {"bipartite": 1, "id": 7}],7 "adjacency": [[{"id": 5}, {"id": 6}],8 [{"id": 6}, {"id": 7}],9 [{"id": 7}],

10 [{"id": 5}]],11 "multigraph": false}

Figure 2: More compact JSON representation of a network

5

1 {2 "nodes": [{"bipartite":0, "id":"person6"},3 {"bipartite":0, "id":"person7"},4 {"bipartite":0, "id":"person8"},5 {"bipartite":0, "id":"person9"},6 {"bipartite":0, "id":"person10"},7 {"bipartite":0, "id":"person11"},8 {"bipartite":0, "id":"person12"},9 {"bipartite":1, "id":"place3", "geodata":{"x":123.4,"y":464.3}},

10 {"bipartite":1, "id":"place4", "geodata":{"x":134.34,"y":234.234}}11 ],12 "adjacency": [[{"id":"place3"}, {"id":"place4"}],13 [{"id":"place3"}],14 [],15 [],16 [],17 [],18 []19 ]}

Figure 3: Network data in JSON with string node identifiers

Similarly, it can be specified with edges lists for the m class 1 nodes only (which in this case wouldhave been smaller since n = 4 and m = 3). Note that that would require rearranging the nodes list sothat the bipartite class 1 nodes are first in the nodes list, however.

Note that the node identifiers need not be integers, they can be any strings as long as each node hasa unique identifier. Internally a private mapping to contiguous integers will be created to index the rowsand columns when building an adjacency matrix.

The JSON shown in Figure 3 uses strings for node identifiers, specifies only the edge lists for the bi-partite class 1 (place) nodes, and includes some other attributes (“geodata”) that will be ignored byBPNet, as well as omitting attributes that aren’t necessary and default to false (directed andmultigraph).

Using the NetworkX JSON adjacency graph format allows networks to be conveniently manipulatedusing the NetworkX package in the Python programming language. For example, Figure 4 shows howto load a network in this format and manipulate it. Note that the JSON being loaded has the actual graphcontained as the value of the network attribute of the JSON data, which is where BPNet requests storetheir network data, as described in Table 18 for example.

Figure 5 shows how to create a graph using the NetworkX Python package and convert it to theJSON format used in the BPNet REST interface. This graph is the example graph used in Section 2.1.

2.3 JSON network data specification (JSONGraph format)

The JSONGraph data format is similar to that described at http://code.google.com/p/jsdot/wiki/JSONGraph (and not one of the many similar formats in use).

In this format the nodes are specified in the nodes attribute as an array with a name (identfier)attribute which is required, and optionally attributes attribute which contains any number of things,but for us the only required one is bipartite (0 or 1). (In the NetworkX format, each node had anid rather than name attribute for the identifier, and bipartite is an attribute at the same level ratherthan nested inside an attributes attribute).

The main differnce from the NetworkX format however is that rather than the adjacency informationas adjacency lists in adjacency there is instead an edges attribute which which is an array of edges,each of which is speciifed by src and dst for the source and destination nodes.

6

http://code.google.com/p/jsdot/wiki/JSONGraph

http://code.google.com/p/jsdot/wiki/JSONGraph

1 >>> import json2 >>> import networkx as nx3 >>> js = json.loads(open("/Users/stivalaa/Documents/GitHub/MelNet/BPNet-REST/

examples/JSON/jsonrest.json").read())4 >>> len(js["network"]["nodes"])5 21006 >>> len(js["network"]["adjacency"])7 16268 >>> from networkx.readwrite import json_graph9 >>> g = json_graph.adjacency_graph(js["network"])

10 >>> nx.is_connected(g)11 False12 >>> nx.is_bipartite(g)13 True14 >>> nx.density(g)15 0.001373896866988815516 >>>17 >>> from networkx.algorithms import bipartite18 >>> nodesA = set(n for n,d in g.nodes(data=True) if d[’bipartite’]==0)19 >>> nodesP = set(g) - nodesA20 >>> len(nodesA)21 162622 >>> len(nodesP)23 47424 >>> list(nodesA)[:10]25 [u’person123’, u’person122’, u’person121’, u’person120’, u’person127’, u’person126’

, u’person125’, u’person124’, u’person129’, u’person128’]26 >>> list(nodesP)[:10]27 [u’place151’, u’place150’, u’place153’, u’place152’, u’place155’, u’place154’, u’

place157’, u’place156’, u’place159’, u’place158’]28 >>> B = bipartite.biadjacency_matrix(g, list(nodesA))29 >>> import numpy30 >>> numpy.shape(B)31 (1626, 474)32 >>> bipartite.average_clustering(g)33 0.424579354455253

Figure 4: Loading a network in JSON format with the NetworkX Python package

7

1 >>> import json2 >>> import networkx as nx3 >>> from networkx.readwrite import json_graph4 >>> g = nx.Graph()5 >>> g.add_nodes_from([1,2,3,4],bipartite=0)6 >>> g.add_nodes_from([5,6,7],bipartite=1)7 >>> g.add_edges_from([(1,5),(1,6),(2,6),(2,7),(3,7),(4,5)])8 >>> nx.is_bipartite(g)9 True

10 >>> nx.is_connected(g)11 True12 >>> from networkx.algorithms import bipartite13 >>> (nodesA, nodesP) = bipartite.sets(g)14 >>> bipartite.closeness_centrality(g, nodesA)15 {1: 0.6923076923076923, 2: 0.6923076923076923, 3: 0.42857142857142855, 4:

0.42857142857142855, 5: 0.5, 6: 0.6666666666666666, 7: 0.5}16 >>> import numpy17 >>> bipartite.biadjacency_matrix(g, list(nodesA))18 matrix([[ 1., 1., 0.],19 [ 0., 1., 1.],20 [ 0., 0., 1.],21 [ 1., 0., 0.]])2223 >>> nx.adjacency_matrix(g)24 matrix([[ 0., 0., 0., 0., 1., 1., 0.],25 [ 0., 0., 0., 0., 0., 1., 1.],26 [ 0., 0., 0., 0., 0., 0., 1.],27 [ 0., 0., 0., 0., 1., 0., 0.],28 [ 1., 0., 0., 1., 0., 0., 0.],29 [ 1., 1., 0., 0., 0., 0., 0.],30 [ 0., 1., 1., 0., 0., 0., 0.]])3132 >>> json.dumps(json_graph.adjacency_data(g))33 ’{"directed": false, "graph": [], "nodes": [{"bipartite": 0, "id": 1}, {"bipartite

": 0, "id": 2}, {"bipartite": 0, "id": 3}, {"bipartite": 0, "id": 4}, {"bipartite": 1, "id": 5}, {"bipartite": 1, "id": 6}, {"bipartite": 1, "id": 7}],"adjacency": [[{"id": 5}, {"id": 6}], [{"id": 6}, {"id": 7}], [{"id": 7}], [{"id": 5}], [{"id": 1}, {"id": 4}], [{"id": 1}, {"id": 2}], [{"id": 2}, {"id": 3}]],"multigraph": false}’

Figure 5: Writing a network in JSON format with the NetworkX Python package

8

As an example of the JSONGraph format, the following graph has four nodes labelled 1,2,3, and 4,and has the following edges: 1-2 and 1-3 (only; 4 is a singleton node):

1 {"directed": false,2 "nodes": [{"id": 1}, {"id": 2}, {"id": 3}, {"id": 4}],3 "edges": [{"src":1, "dst":2}, {"src":1, "dst":3}]4 }

This structure is completely general. Hence we do not specify bipartite graphs by a biadjacencymatrix (or some sort of bipartite adjacency list, although that would be more efficient), but by the con-vention of having a bipartite attribute which is 0 or 1 to indicate which of the two classes a nodebelongs to. For BPNet these correspond to the A and P class respectively. For example, the followingbipartite network has nodes 1,2,3 and 4 in class 0 and nodes 5, 6 and 7 in class 1, with edges 1-5, 1-6,2-6, 2-7, 3-7, and 4-5:

1 {"directed": false,2 "attributes": {"label": "example bipartite graph"},3 "nodes": [{"attributes":{"bipartite": 0}, "name": 1},4 {"attributes":{"bipartite": 0}, "name": 2},5 {"attributes":{"bipartite": 0}, "name": 3},6 {"attributes":{"bipartite": 0}, "name": 4},7 {"attributes":{"bipartite": 1}, "name": 5},8 {"attributes":{"bipartite": 1}, "name": 6},9 {"attributes":{"bipartite": 1}, "name": 7}],

10 "edges": [{"src":1, "dst":5},11 {"src":1, "dst":6},12 {"src":2, "dst":6},13 {"src":2, "dst":7},14 {"src":3, "dst":7},15 {"src":4, "dst":5}16 ]17 }

Note that the node identifiers need not be integers, they can be any strings as long as each node hasa unique identifier. Internally a private mapping to contiguous integers will be created to index the rowsand columns when building an adjacency matrix.

For undirected graphs, an edge between nodes x and y can be specified with src=x and dst=y, orsrc=y and dst=x, or both.

The fields are described in Table 4. The name and bipartite attributes are required for eachnode, and src and dst are required attributes for each edge.

Table 4: JSONGraph attributes

Attribute Type Descriptiondirected boolean If specified, must be false for bipartite graphs; only undirected bipartite

graphs are supportednodes list of nodes Descibed in Table 5. Each node must have the name attribute specifying

a unique identifier for that node (across all nodes in both classes in thenetwork) and the bipartite identifier specifying whether the node is inclass 0 or 1.

edges list of edges Descibed in Table 6. Each edge is specified by src and dst node name.attributes map arbitrary attribute:value pairs, not used by BPNet.

9

Table 5: JSONGraph node attributes

Attribute Type Descriptionname String Unique identifier for this node.attributes map Arbitrary attribute:value pairs. Those defined by BPNet are described in Table 7.

Any other attributes are used by BPNet as the attributes for the node.

Table 6: JSONGraph edge attributes

Attribute Type Descriptionsrc String Source node for this edge.dst String Destination node for this edge.attributes map Arbitrary attribute:value pairs. Not used by BPNet.

Table 7: JSONGraph node attributes attributes

Attribute Type Descriptionbipartite int 0 or 1 giving the bipartite class for the node. Required.label String Optional descriptive string.geometry Object Optional geometry (GeoJSON) data for the node. Not used by BPNet.

Each node can have any number of binary (Boolean), continuous, and categorical attributes. ForBPNet, each node must have the same attributes specified. Note that there are sets of attributes for A(bipartite = 0) nodes, for P (bipartite = 1) and for A&P (both) nodes, so not all nodes need have thesame corresponding sets of attributes (except in the last case). However all A nodes must have the sameset (consisting of all A attributes and all A&P attributes), and similarly for P (bipartite=1) nodes: eachwill have all P and all A&P attributes. Predefined attributes known by BPNet are described in Table 7.Any other attributes are used by BPNet as the attributes for the node. The type (binary, continuous orcategorical) of an attribute is determined by its value. A binary attribute must have a value of eithertrue or false. A continuous attribute must be specified as a floating point number for example 1.2.A categorical attribute must be specified by an integer. Note that this means that continuous attributesthat happen to have an integer value must be specified with a decimal point, for example 1.0 rather than1, as the latter will be interpreted as an integer and therefore categorical rather than continuous.

3 Dyadic covariates

Although edge attributes are not used in BPNet, so-called dyadic covariates can be used to specifyattributes not of nodes, but of pairs of nodes. Note that, although this might seem an appropriate usefor edge attributes in the input network specification, this is not the case as the network specificationincludes only edges for actual ties in the network, while dyadic covariates are defined between each pairof nodes.

Dyadic covariates are therefore specified separately, in one of two alternate forms.In the first form, dyadic covariates are specified as a list of src and dst node pairs along with a

continuous value of the dyadic covariate between the two nodes. They are not directed, so src and dstare interchangeable. The format of dyadic covariate specification is shown in Table 8 and Table 9.

10

Table 8: Dyadic covariate object

Attribute Type Descriptionsrc String Node 1 identifier for this dyadic covariate.dst String Node 2 identifier for this dyadic covariate.continuousValue double Value of the dyadic covariate.

Table 9: Dyadic covariates specification

Attribute Type DescriptioncovariateName String Name of the dyadic covariate.covariates List of dyadic covariate objects Each element of the list is a dyadic covarite as

specified in Table 8. Note that every pair of nodesmust have a covariate value specified.

In the second form, dyadic covariates are specified in JSONgraph format (see Section 2.3), usingonly the edge attributes; the nodes are defined in the supplied input graph (which may be specified eitherin NetworkX or JSONgraph format).

4 Missing values

Sometimes, values may be missing for some attributes. For all attribute values (continuous, categorical,and binary node attributes, and dyadic attributes), a value may be specified as null to indicate that thatvalue is missing. Note that values are assumed to be missing at random, that is, are not correlated withthe non-missing values or other attributes. If this assumption does not hold, estimated values for therelevant attribute parameters may not be valid.

5 Services

Note, in the following, <URI> represents the base URI of the BPNet web service, for example http://bpnet.aurin.org.au:8080/bpnet_rest/.

As well as the network structure described in Section 2, another two data types are common to allthe BPNet requests. These types describe the structural parameters and actor attribute parameters to beestimated or simulated, and are described in Table 10 and Table 13 When the JSONGraph format isused for specifying the network structure, the “named attribute request object” (Table 15) is used ratherthan the “attribute request object” (Table 14) as attributes can then be referred to by name rather than bylist position as used in the NetworkX format. In those tables, the “markov request object” is describedin Table 11, the “highorder request object” is described in Table 12, the “attribute request object” isdescribed in Table 14 and the “named attribute request object” is described in Table 15.

Similarly, the “named dyadic covariate parameter request object” (Table 16) is used to request dyadiccovariate parmeters by name rather than position in list when dyadic covariates are specified in JSON-graph format using dyadicCovariatesJSONgraph rather than dyadicCovariates.

Table 10: Structural parameter attributes

Attribute Type DescriptionmarkovL markov request object Edge (density)

11

http://bpnet.aurin.org.au:8080/bpnet_rest/

http://bpnet.aurin.org.au:8080/bpnet_rest/

Table 10: (continued)

Attribute Type Description

markovSa2 markov request object Two-star for class A (2-A-star)

markovSp2 markov request object Two-star for class P (2-P-star)

markovSa3 markov request object Three-star for class A (3-A-star)

markovSp3 markov request object Three-star for class P (3-P-star)

markovL3 markov request object Three-path

markovC4 markov request object Four-cycle

highOrderKSa highorder request object alternating k-star for classA (k-A-star)

highOrderKSp highorder request object alternating k-star for classP (k-P-star)

highOrderKCa highorder request object alternating A cycles

highOrderKCp highorder request object alternating P cycles

highOrderKCa2 highorder request object same as KCa but allowsdifferent lambda

highOrderKCp2 highorder request object same as KCp but allowsdifferent lambda

12

Table 11: Markov parameter attributes (markov request object)

Attribute Type Descriptionrequested boolean true to request this parameter. Default falsevalue double initial value of the parameter. Default 0

Table 12: Higher-order parameter attributes (highorder request ob-ject)

Attribute Type Descriptionrequested boolean true to request this parameter. Default falsevalue double initial value of the parameter. Default 0lambda float The value of λ controls the amount of centralization based on high degree

nodes. Default 2.0

Table 13: Actor attribute parameter attributes

Attribute Type Descriptionactor attribute parameters (A)

binaryattrRA 1 list of [named] attribute request object

attrTscA 1 list of [named] attribute request object

attrTsoA1 1 list of [named] attribute request object

attrTsoA2 1 list of [named] attribute request object

attrC4A1 1 list of [named] attribute request object

attrC4A2 1 list of [named] attribute request object

continuous

attrRAc 1 list of [named] attribute request object

13



attrTscAc 1 list of [named] attribute request object

attrTsoAcs 1 list of [named] attribute request object

attrTsoAcd 1 list of [named] attribute request object

attrC4Acs 1 list of [named] attribute request object

attrC4Acd 1 list of [named] attribute request object

categorical

attrMatching 2PathA 1 list of [named] attribute request object

attrMismatching 2PathA 1 list of [named] attribute request object

attrMatching 4CycleA 1 list of [named] attribute request object

attrMismatching 4CycleA 1 list of [named] attribute request object

14


Attribute Type Descriptionactor attribute parameters (P)

binaryattrRP 1 list of [named] attribute request object

attrTscP 1 list of [named] attribute request object

attrTsoP1 1 list of [named] attribute request object

attrTsoP2 1 list of [named] attribute request object

attrC4P1 1 list of [named] attribute request object

attrC4P2 1 list of [named] attribute request object

continuous

attrRPc 1 list of [named] attribute request object

attrTscPc 1 list of [named] attribute request object

attrTsoPcs 1 list of [named] attribute request object

attrTsoPcd 1 list of [named] attribute request object

15



attrC4Pcs 1 list of [named] attribute request object

attrC4Pcd 1 list of [named] attribute request object

categorical

attrMatching 2PathP 1 list of [named] attribute request object

attrMismatching 2PathP 1 list of [named] attribute request object

attrMatching 4CycleP 1 list of [named] attribute request object

attrMismatching 4CycleP 1 list of [named] attribute request object

actor attribute parameters (A&P)binary

attrRAP 1 list of [named] attribute request objectcontinuous

attrRAPc 1 list of [named] attribute request object

Table 14: Actor attribute parameter attributes used when the graphis specified by the network object in NetworkX format (attributerequest object)

Attribute Type Descriptionrequested boolean true to request this parameter. Default falsevalue double initial value of the parameter. Default 0

16

Table 15: Actor attribute parameter attributes used when the graphis specified by the graph object in JSONgraph format (namedattribute request object)

Attribute Type DescriptionattributeName String name of the attributerequested boolean true to request this parameter. Default falsevalue double initial value of the parameter. Default 0

Table 16: Dyadic covariate parameter attributes usedwhen the dyadic covariates are specified by thedyadicCovariatesJSONgraph object in JSONgraphformat (named dyadic covariate parameter object)

Attribute Type DescriptioncovariateName String name of the dyadic covariaterequested boolean true to request this parameter. Default falsevalue double initial value of the parameter. Default 0

Successful responses for each service are described in the following sections, and are returned as thedata with HTTP status code 200 (OK). Error responses return the data described in Table 17 with HTTPstatus code 400 (bad request) or 500 (internal server error) as appropriate.

Table 17: Error response data

Attribute Type DescriptionrequestId long request identifier as supplied in the request that generated this error responsemessage string describes the error (for example “bad network specification”)details string further details of the error (for example “bad continuous attribute list length for

node id ’person6”’)

5.1 Estimate

The estimation function of BPNet is requested by using the POST method to URI <URI>/service/estimate with the data described in Table 18.

Table 18: Estimation request attributes

Attribute Type DescriptionrequestId long Identifier for this request. BPNet

does not use this except that re-sponses will contain the same re-questId as their corresponding re-quests.

requestProcessor string Versioning information. Must be“BPNet” (default value)

requestType string Versioning information. Must be“estimate” (default value)

requestVersion string Versioning information. Must “1.0”(default value)

17

<URI>/service/estimate

<URI>/service/estimate


Attribute Type Descriptionnetwork object The network structure in NetworkX

format as described in Section 2.2graph object The network structure in JSON-

Graph format as described in Sec-tion 2.3. Only one of network andgraph may be specified.

attributeNames object The names of node attributes asdescribed in Table 2. Not usedif graph is specified instead ofnetwork: for the JSONgraph for-mat attribute names are attributes inthe attributes attribute in thegraph nodes.

dyadicCovariates List of dyadic covariates Each element of ths list is a dyanmiccovariate specification object as de-scribed in Table 9.

dyadicCovariatesJSONgraph object The dyadic covariates specified us-ing only the edge attributes of aJSONgraph object (Section 2.3). Ei-ther dyadicCovariates or dyadicCo-variatesJSONgraph can be specified,but not both.

structuralParameters object The structural parameter settings de-scribed in Table 10

18


Attribute Type DescriptionattributeParameters object If network is used then

attributeParametersmust be used; if graphis used instead thennamedAttributeParametersmust be used. The actor attributeparameter settings described inTable 13. If network is usedrather than graph then note thateach parameter is a list — thiscorresponds to the list of attributenames in attributeNames for thetype of attribute in question. Forexample if there are two binaryattributes for class A nodes thenbinaryAttributesA in attributeNameshas a list of the two names for thoseattributes and each of the binaryattributes for class A nodes in thisobject (attrRA 1, attrTScA 1, andso on) must have a correspondinglist of length two to indicate whichattribute parameters of that type torequest. If graph is used ratherthan network than each parameteris still a list but attributes are namedin the “named attribute request ob-ject” rather than using the “attributerequest object” and having the listposition significant.

dyadicCovariateParameters list of parameter requests The order of the list correspondsto the dyadicCovariates list.Each element is a parameter requestobject described in Table 11, indi-cating whether or not to request thecorresponding dyadic covariate to beestimated.

namedDyadicCovariateParameter list List of named dyadic covariate pa-rameter objects (Table 16) specify-ing the dyadic covariate parametersto request. Used instead of dyadic-CovariateParameters when specify-ing dyadic covariates using JSON-graph format in dyadicCovariatesJ-SONgraph instead of dyadicCovari-ates.

19


Attribute Type DescriptionstructuralZeros object structural zero lists: same format as

adjacency list, but each entry in thislist corresponds to a 1 in the BPNetstructural zero file meaning that thatedge (tie) is changeable. So an edgenot present here corresponds to 0 inthe structural zero file meaning thetie is fixed. Default null meaningthere are no structural zeros and allties are changeable

fixGraphDensity boolean fix graph density. Default falsenumberOfSubphases int number of sub-phases. Default 5gainingFactor double a-value, halved after each sub-phase.

Default 0.01multiplicationFactor int larger means estimation takes longer

but may help convergence for largegraphs. Default 10

numIterationsPhase3 int In phase 3 graphs are simulated us-ing parameters estimated in phase 2to get t-statistics. This is the numberof steps in that simulation. Default500

numEstimationRuns int Number of estimation runs. Default1

Figure 6 shows the JSON data for an estimation request for the network in Figure 3 in which theMarkov parameters L and Sa2 are requested, the latter being supplied with an initial value of 1.0. Fig-ure 7 shows the JSON data for a more complex estimation request, which includes attribute data. Fig-ure 8 shows the JSON data for an estimation request with the network specified in JSONGraph ratherthan NetworkX format, and including dyadic covariates. Figure 9 shows the same request, but usingdyadicCovariatesJSONgraph to specify the dyadic covariates using a JSONgraph object and referring tothem in the request by name rather than list position.

The response from an estimation request is the data described in Table 19. In that table the “pa-rameter response object” is described in Table 20, the “attribute parameter response object” is describedin Table 21, and the “dyadic covariate response object” is described in Table 22. Note that each of theattribute parameters is returned as an array of attribute parameter response objects. This is because theremay be multiple attributes, named according to the attributeNames object in the estimation request(with values specified as in the node attributes of the network object in the request). The sequence ofreturned attribute parameters should not be relied upon to line up with the attribute names as specifiedin the request: instead, each attribute parameter response object contains an attributeName fielddescribing the attribute to which it applies.

Table 19: Estimation response attributes

Attribute Type DescriptionisDegenerate boolean true if the model is degen-

erate, in which case the pa-rameters estimated are notvalid

20


Attribute Type DescriptionmarkovL parameter response object Edge (density)markovSa2 parameter response object Two-star for class A (2-A-

star)markovSp2 parameter response object Two-star for class P (2-P-

star)markovSa3 parameter response object Three-star for class A (3-A-

star)markovSp3 parameter response object Three-star for class P (3-P-

star)markovL3 parameter response object Three-pathmarkovC4 parameter response object Four-cyclehighOrderKSa parameter response object alternating k-star for class A

(k-A-star)highOrderKSp parameter response object alternating k-star for class P

(k-P-star)highOrderKCa parameter response object alternating A cycleshighOrderKCp parameter response object alternating P cycleshighOrderKCa2 parameter response object same as KCa but allows dif-

ferent lambdahighOrderKCp2 parameter response object same as KCp but allows dif-

ferent lambdaactor attribute parameters (A)

binary

attrRA 1 attribute response object array

attrTscA 1 attribute response object array

attrTsoA1 1 attribute response object array

attrTsoA2 1 attribute response object array

attrC4A1 1 attribute response object array

attrC4A2 1 attribute response object array

21


Attribute Type Descriptioncontinuous

attrRAc 1 attribute response object array

attrTscAc 1 attribute response object array

attrTsoAcs 1 attribute response object array

attrTsoAcd 1 attribute response object array

attrC4Acs 1 attribute response object array

attrC4Acd 1 attribute response object arraycategorical

attrMatching 2PathA 1 attribute response object array

attrMismatching 2PathA 1 attribute response object array

attrMatching 4CycleA 1 attribute response object array

22



attrMismatching 4CycleA 1 attribute response object arrayactor attribute parameters (P)

binary

attrRP 1 attribute response object array

attrTscP 1 attribute response object array

attrTsoP1 1 attribute response object array

attrTsoP2 1 attribute response object array

attrC4P1 1 attribute response object array

attrC4P2 1 attribute response object arraycontinuous

attrRPc 1 attribute response object array

attrTscPc 1 attribute response object array

attrTsoPcs 1 attribute response object array

23



attrTsoPcd 1 attribute response object array

attrC4Pcs 1 attribute response object array

attrC4Pcd 1 attribute response object arraycategorical

attrMatching 2PathP 1 attribute response object array

attrMismatching 2PathP 1 attribute response object array

attrMatching 4CycleP 1 attribute response object array

attrMismatching 4CycleP 1 attribute response object arrayactor attribute parameters (A&P)

binary

attrRAP 1 attribute response object arraycontinuous

24



attrRAPc 1 attribute response object arrayDyadic covariates (continuous only)

dyadicCovariateParameters dyadic covariate response object array The dyadic covariate param-eter gives an indication ofthe influence of the rele-vant dyadic covariate (an at-tribute of each pair of nodes)on the probability of a tieforming between two nodes.

network statisticsnetworkStatistics object The network statistics object

described in Table 23versioning and informational

requestId long Request identifier as sup-plied in the request that gen-erated this response.

responseGenerator string Versioning information: thename of the process thatgenerated this response.“BPNet”

responseType string Versioning information: thetype of response generated:“estimate”

responseVersion string Versioning information: theversion of this object. “1.0”

bpnetVersion string Versioning information: theversion of the BPNet soft-ware that created the datain this object. Currently“2.0.1”

estimationTime long elapsed time of the estima-tion procedure in millisec-onds

Only parameters that were requested (that is, present in the estimation request data with the requestedattribute having value true), will be present in the response object.

The network statistics returned in the response are shown in Table 23. Note that the distributionsin that data (for example degreeDistributionA) are arrays indexed from 0 . . . n where n is thenumber of nodes of the other type (for example, type P for degreeDistributionA), since themaximum possible degree of a node in a bipartite graph is the number of nodes of the other type.So degreeDistributionA[0] is the number of type A nodes with degree 0, and so on up todegreeDistributionA[n] which is the number of type A nodes with degree n where n is thenumber of nodes of type P.

25

1 {"network": {2 "nodes": [{"bipartite":0, "id":"person6"},3 {"bipartite":0, "id":"person7"},4 {"bipartite":0, "id":"person8"},5 {"bipartite":0, "id":"person9"},6 {"bipartite":0, "id":"person10"},7 {"bipartite":0, "id":"person11"},8 {"bipartite":0, "id":"person12"},9 {"bipartite":1, "id":"place3", "geodata":{"x":123.4,"y":464.3}},

10 {"bipartite":1, "id":"place4", "geodata":{"x":134.34,"y":234.234}}11 ],12 "adjacency": [[{"id":"place3"}, {"id":"place4"}],13 [{"id":"place3"}],14 [],15 [],16 [],17 [],18 []19 ]},20 "structuralParameters":{"markovSa2":{"requested":"true", "value":1.0},21 "markovL":{"requested":true}}22 }

Figure 6: Example JSON data for an estimation request

Table 20: Parameter response attributes (parameter response ob-ject)

Attribute Type Descriptionestimate double estimated parameter valuestderr double standard error of the estimated valuet ratio double (observed value - sample mean) / standard deviationsignificant boolean true if |estimate| > 2× standard errorcount int count of this structure in the network. This field is valid even if the model is

degenerate (and the other fields are therefore invalid)

Table 21: Actor attribute parameter response attributes (attributeparameter response object)

Attribute Type DescriptionattributeName string name of the attributeestimate double estimated parameter valuestderr double standard error of the estimated valuet ratio double (observed value - sample mean) / standard deviationsignificant boolean true if |estimate| > 2× standard errorcount double attribute weighted count of this structure in the network. This field is valid

even if the model is degenerate (and the other fields are therefore invalid)

Table 22: Dyadic covariate parameter response attributes (dyadiccovariate response object)

Attribute Type DescriptioncovariateName string name of the dyadic covariateestimate double estimated parameter valuestderr double standard error of the estimated valuet ratio double (observed value - sample mean) / standard deviationsignificant boolean true if |estimate| > 2× standard errorcount double weighted count of this structure in the network. This field is valid even

if the model is degenerate (and the other fields are therefore invalid)

Table 23: Network statistics object

Attribute Type DescriptiongraphDensity double ratio of #edges to #possible edgesdegreeDistributionA int array degree distribution of class 0 (A) nodesdegreeDistributionP int array degree distribution of class 1 (P) nodesdegreeDistributionAstddev int array standard deviation of degree dist AdegreeDistributionSkewA double array skewness of degreeDistributionAdegreeDistributionPstddev double standard devitation of degree dist PdegreeDistributionSkewP double skewness of degreeDistributionPmeanDegree double mean degree of graphglobalClusteringCoefficient double global clustering coefficienttwoPathDistributionA int array 2-path distr. of each class 0 (A) node

26


Attribute Type DescriptiontwoPathDistributionP int array 2-path distr. of each class 1 (P) node

Figure 10 shows the JSON data for a response from the estimation service when sent the requestdata from Figure 6.

5.2 Simulate

The simulation function of BPNet is requested by using the POST method to URI <URI>/service/simulate with the data described in Table 24. The simulation function simulates a series of randomnetworks generated by the supplied structural parameters. As such, it does not take a network spec-ification as input, only the parameters and the numbers of the two classes of nodes, along with anyattributes.

Note that the structuralZeros are in a different format in the simulate request than they are inthe estimate and goodness-of-fit requests. In the simulate request the structural zeros are specified as anentire network object just as a network itself is, while in the other two request types they are specifiedby adjacency lists only. This is because the simulate request does not have a network object in it (nonetwork is specified for a simulation), unlike the other request types. Hence the structural zeros need anentire network specification, rather than just adjacency lists which can refer to the nodes in the networkobject.

Table 24: Simulation request attributes




requestType string Versioning information. Must be“simulate” (default value)

requestVersion string Versioning information. Must“1.0” (default value)

numberOfNodesA int Number of class A (bipartite=0)nodes

numberOfNodesP int Number of class P (bipartite=1)nodes

attributeNames object The names of node attributes asdescribed in Table 2

27

<URI>/service/simulate

<URI>/service/simulate


Attribute Type DescriptionattributeValues object array An array of the values of node at-

tributes as described in Table 3.As there is no network specifi-cation for the simulate request,node attribute values are speci-fied here rather than within thenodes themselves. Each elementin the array corresponds to theattribute for one node, with allA nodes first followed by all Pnodes. Hence this array musthave length numberOfNodesA +numberOfNodesP.

structuralParameters object The structural parameter settingsdescribed in Table 10

attributeParameters object The actor attribute parameter set-tings described in Table 13. Notethat each parameter is a list —this corresponds to the list of at-tribute names in attributeNamesfor the type of attribute in ques-tion. For example if there aretwo binary attributes for class Anodes then binaryAttributesA inattributeNames has a list of thetwo names for those attributes andeach of the binary attributes forclass A nodes in this object (at-trRA 1, attrTScA 1, and so on)must have a corresponding list oflength two to indicate which at-tribute parameters of that type torequest

dyadicCovariateParameters list of parameter requests The order of the list correspondsto the dyadicCovariateslist. Each element is a parameterrequest object described in Table11, indicating whether or not torequest the corresponding dyadiccovariate to be estimated.

28


Attribute Type DescriptionnamedDyadicCovariateParameter list List of named dyadic covariate pa-

rameter objects (Table 16) speci-fying the dyadic covariate param-eters to request. Used instead ofdyadicCovariateParameters whenspecifying dyadic covariates us-ing JSONgraph format in dyadic-CovariatesJSONgraph instead ofdyadicCovariates.

dyadicCovariates list of dyadic covariates Each element of ths list is a dyan-mic covariate specification objectas described in Table 9.

dyadicCovariateNodes Network object The Simulation request does notcontain a network specification,so to specify dyadic covariatesthe nodes need to be specified.When using dyadicCovariates in-stead of dyadicCovariatesJSON-graph, this is done by specifingonly the nodes attribute in theNetwork object described in Ta-ble 1.

dyadicCovariatesJSONgraph object The dyadic covariates specifiedusing the a JSONgraph object(Section 2.3). Either dyadic-Covariates or dyadicCovariatesJ-SONgraph can be specified, butnot both. When using dyadic-CovaritesJSONgraph instead ofdyadicCovariates, nodes are spec-ified in this JSONgraph object,with dyadic covariates specified asedge attributes.

structuralZeros object Structural zeros in the format ofthe network structure described inSection 2. Each edge in this net-work corresponds to a 1 in theBPNet structural zero file mean-ing that that edge (tie) is change-able. So an edge not present herecorresponds to 0 in the structuralzero file meaning the tie is fixed.Default null meaning there areno structural zeros and all ties arechangeable

fixGraphDensity boolean fix graph density. Default falsestartingDensity float initial graph density in [0, 1]. De-

fault 0.0

29


Attribute Type DescriptionreturnSampleGraphs boolean return sample graphs in simula-

tion response. Default falsereturnSampleGraphsAsURL boolean Return sample graphs as a URL

to a zip file of Pajek format graphfiles in sampleGraphsURL. De-fault false

returnSampleGraphStats boolean return statistics for sampledgraphs. Default false

returnSampleDegreeDistributions boolean return degree distributions forsampled graphs. Default false

returnSampleClusteringCoefficients boolean return global clustering coeffi-cient of sampled graphs. Defaultfalse

burnIn int Number of iterations to burn-in.Default 100000

numberOfIterations int Number of iterations in simulation(after burn-in). Default 1000000

numberOfSamplesToReturn int number of samples to return. Thisvalue is the number of samplesused for graph statistics, and thenumber of elements returned insampleStatistics etc. fields in Sim-ulationResponse. Default 1000

numberOfSampleGraphsToReturn int The number of sample graphobjects to return, if returnSam-pleGraphs or returnSampleGraph-sURL is true. This is the num-ber of graph objects returned insampleGraphs and sampleGraph-sJSONgraph in the SimulationRe-sponse object, if returnSample-Graphs is true, and in the con-tents of the zip if if returnSample-GraphsAsURL is true. Must be ≤numberofSamplesToRetrun and≤10. Default 10

The response from a simulation request is the data described in Table 25. In that table, the “networkstatistics object” is described in Table 23, the “parameter statistics object” is described in Table 26 andthe “degree distributions” object is described in Table 27. In Table 26, fields of type count consistsimply of an int attribute named count, which is the count of the relevant structure in the sampledgraph, and the “simulation attribute object” is described in Table 28.

Table 25: Simulation response data

Attribute Type DescriptionstartStatistics network statistics object Statistics of starting graphstartParameterStatistics parameter statistics object Parameter statistics of starting graphendStatistics network statistics object Statistics of ending graph

30


Attribute Type DescriptionendParameterStatistics parameter statistics object Parameter statistics of ending graphsampleParameterStatistics array of parameter statistics Structural and actor attribute parame-

ter statistics of each sampled graphsampleStatistics array of network statistics Network statistics of each sam-

pled graph, if returnSampleGraph-Stats was set to true in request

sampleDegreeDistributions array of degree distributions Degree distributions of each sampledgraph, if returnSampleDegreeDistri-butions was set to true in request

sampleClusteringCoefficients array of double Global clustering coefficient of eachsampled graph, if returnSampleClus-teringCoefficients was set to true inrequest

sampleGraphs array of network objects A network object (see Section 2) foreach of the sampled graphs, if return-SampleGraphs was set to true

sampleGraphsJSONgraph array of JSONgraph objects A JSONgraph object (see Section 2.3)for each of the sampled graphs, if re-turnSampleGraphs was set to true.This is exactly the same data as sam-pleGraphs, but in JSONgraph format.

sampleGraphsURL String URL of zip archive of sampled graphsin Pajek format, to be used in aGET request to download data toclient. Only set if returnSample-GraphsAsURL is set to true in therequest

requestId long Request identifier as supplied in therequest that generated this response.

responseGenerator string Versioning information: the name ofthe process that generated this re-sponse. “BPNet”

responseType string Versioning information: the type ofresponse generated: “simulate”

responseVersion string Versioning information: the versionof this object. “1.0”

bpnetVersion string Versioning information: the versionof the BPNet software that created thedata in this object. Currently “2.0.1”

simulationTime long elapsed time of the simulation proce-dure in milliseconds

Table 26: Parameter statistics attributes

Attribute Type DescriptionmarkovL count Edge (density)markovSa2 count Two-star for class A (2-A-

star)

31


Attribute Type DescriptionmarkovSp2 count Two-star for class P (2-P-

star)markovSa3 count Three-star for class A (3-A-

star)markovSp3 count Three-star for class P (3-P-

star)markovL3 count Three-pathmarkovC4 count Four-cyclehighOrderKSa count alternating k-star for class A

(k-A-star)highOrderKSp count alternating k-star for class P

(k-P-star)highOrderKCa count alternating A cycleshighOrderKCp count alternating P cycleshighOrderKCa2 count same as KCa but allows dif-

ferent lambdahighOrderKCp2 count same as KCp but allows dif-

ferent lambdaactor attribute parameters (A)

binary

attrRA 1 simulation attribute object array

attrTscA 1 simulation attribute object array

attrTsoA1 1 simulation attribute object array

attrTsoA2 1 simulation attribute object array

attrC4A1 1 simulation attribute object array

attrC4A2 1 simulation attribute object arraycontinuous

32



attrRAc 1 simulation attribute object array

attrTscAc 1 simulation attribute object array

attrTsoAcs 1 simulation attribute object array

attrTsoAcd 1 simulation attribute object array

attrC4Acs 1 simulation attribute object array

attrC4Acd 1 simulation attribute object arraycategorical

attrMatching 2PathA 1 simulation attribute object array

attrMismatching 2PathA 1 simulation attribute object array

attrMatching 4CycleA 1 simulation attribute object array

33



attrMismatching 4CycleA 1 simulation attribute object arrayactor attribute parameters (P)

binary

attrRP 1 simulation attribute object array

attrTscP 1 simulation attribute object array

attrTsoP1 1 simulation attribute object array

attrTsoP2 1 simulation attribute object array

attrC4P1 1 simulation attribute object array

attrC4P2 1 simulation attribute object arraycontinuous

attrRPc 1 simulation attribute object array

attrTscPc 1 simulation attribute object array

attrTsoPcs 1 simulation attribute object array

34



attrTsoPcd 1 simulation attribute object array

attrC4Pcs 1 simulation attribute object array

attrC4Pcd 1 simulation attribute object arraycategorical

attrMatching 2PathP 1 simulation attribute object array

attrMismatching 2PathP 1 simulation attribute object array

attrMatching 4CycleP 1 simulation attribute object array

attrMismatching 4CycleP 1 simulation attribute object arrayactor attribute parameters (A&P)

binary

attrRAP 1 simulation attribute object arraycontinuous

35



attrRAPc 1 simulation attribute object arrayDyadic covariates (continuous only)

dyadicCovariateParameters dyadic covariate response object array Array of dyadic covariatesimulation response objectsas described in Table 29.

Table 27: Degree distributions object

Attribute Type DescriptiondegreeDistributionA int array degree distribution of class 0 (A) nodesdegreeDistributionP int array degree distribution of class 1 (P) nodesdegreeDistributionAstddev int array standard deviation of degree dist AdegreeDistributionSkewA double array skewness of degreeDistributionAdegreeDistributionPstddev double standard devitation of degree dist PdegreeDistributionSkewP double skewness of degreeDistributionP

Table 28: Simulation attribute object

Attribute Type DescriptionattributeName string name of the attributecount double attribute weight count of this attribute structure in the sampled graph

Table 29: Simulation dyadic covariate object

Attribute Type DescriptioncovariateName string name of the dyadic covariatecount double weighted count of this dyadic covariate’s values in the sampled graph

5.3 Goodness-of-fit

The goodness-of-fit (GoF) function of BPNet is requested by using the POST method to URI <URI>/service/gof with the data described in Table 30. The goodness-of-fit function computes statisticsthat indicate the goodness of fit of the parameter values specified in the structural and attribute parameterobjects (as computed by the estimation procedure) to a population of networks randomly generated fromthose parameters. Typically when using goodness-of-fit, all parameters are requested, with the parametervalues set to the estimated values for those that have estimates, and the others set to 0.

Table 30: Goodness-of-fit request attributes


36

<URI>/service/gof

<URI>/service/gof





requestType string Versioning information. Must be“gof” (default value)

requestVersion string Versioning information. Must“1.0” (default value)

network object The network structure in Net-workX format as described in Sec-tion 2.2

graph object The network structure in JSON-Graph format as described in Sec-tion 2.3. Only one of networkand graph may be specified.

attributeNames object The names of node attributes asdescribed in Table 2. Not usedif graph is specified instead ofnetwork: for the JSONgraphformat attribute names are at-tributes in the attributes at-tribute in the graph nodes.

dyadicCovariates List of dyadic covariates Each element of ths list is a dyan-mic covariate specification objectas described in Table 9.

dyadicCovariatesJSONgraph object The dyadic covariates specifiedusing only the edge attributesof a JSONgraph object (Sec-tion 2.3). Either dyadicCovari-ates or dyadicCovariatesJSON-graph can be specified, but notboth.

structuralParameters object The structural parameter settingsdescribed in Table 10

37


Attribute Type DescriptionattributeParameters object If network is used then

attributeParametersmust be used; if graphis used instead thennamedAttributeParametersmust be used. The actor attributeparameter settings described inTable 13. If network is usedrather than graph then note thateach parameter is a list — thiscorresponds to the list of attributenames in attributeNames for thetype of attribute in question. Forexample if there are two binaryattributes for class A nodes thenbinaryAttributesA in attribute-Names has a list of the two namesfor those attributes and each ofthe binary attributes for class Anodes in this object (attrRA 1,attrTScA 1, and so on) must havea corresponding list of lengthtwo to indicate which attributeparameters of that type to request.If graph is used rather thannetwork than each parameteris still a list but attributes arenamed in the “named attributerequest object” rather than usingthe “attribute request object” andhaving the list position significant.

dyadicCovariateParameters list of parameter requests The order of the list correspondsto the dyadicCovariateslist. Each element is a parameterrequest object described in Table11, indicating whether or not torequest the corresponding dyadiccovariate to be estimated.

namedDyadicCovariateParameter list List of named dyadic covariate pa-rameter objects (Table 16) speci-fying the dyadic covariate param-eters to request. Used instead ofdyadicCovariateParameters whenspecifying dyadic covariates us-ing JSONgraph format in dyadic-CovariatesJSONgraph instead ofdyadicCovariates.

38


Attribute Type DescriptionstructuralZeros object structural zero lists: same format

as adjacency list, but each entry inthis list corresponds to a 1 in theBPNet structural zero file mean-ing that that edge (tie) is change-able. So an edge not present herecorresponds to 0 in the structuralzero file meaning the tie is fixed.Default null meaning there areno structural zeros and all ties arechangeable

fixGraphDensity boolean fix graph density. Default falsereturnSampleGraphs boolean return sample graphs. Default

falsereturnSampleGraphsAsURL boolean Return sample graphs as a URL

to a zip file of Pajek format graphfiles in sampleGraphsURL. De-fault false

returnSampleGraphStats boolean return statistics for sampledgraphs. Default false

returnSampleDegreeDistributions boolean return degree distributions forsampled graphs. Default false

returnSampleClusteringCoefficients boolean return global clustering coeffi-cient of sampled graphs. Defaultfalse

burnIn int Number of iterations to burn-in.Default 100000

numberOfIterations int Number of iterations in simulation(after burn-in). Default 1000000

numberOfSamplesToReturn int number of samples to return. Thisvalue is the number of samplesused for graph statistics, and thenumber of elements returned insampleStatistics etc. fields inGofResponse. Default 1000

numberOfSampleGraphsToReturn int The number of sample graph ob-jects to return, if returnSample-Graphs is true. This is the num-ber of graph objects returned insampleGraphs and sampleGraph-sJSONgraph in the GofResponseobject, if returnSampleGraphs istrue, and the number of graphs inthe zip file contents in returnSam-pleGraphsAsURL is true. Must be≤ numberofSamplesToRetrun and≤ 10. Default 10

The response from a goodness-of-fit request is the data described in Table 31. In that table, the “net-

39

1 {"network": {2 "nodes": [{"bipartite":0, "id":"person6",3 "binaryAttributeValues":[true,false],4 "continuousAttributeValues":[31,1.1,11],5 "categoricalAttributeValues":[0]},6 {"bipartite":0, "id":"person7",7 "categoricalAttributeValues":[1],8 "binaryAttributeValues":[false,false],9 "continuousAttributeValues":[32,1.2,12]},

10 {"bipartite":0,"categoricalAttributeValues":[0],11 "id":"person8",12 "binaryAttributeValues":[true,false],13 "continuousAttributeValues":[33,1.3,13]},14 {"bipartite":0, "id":"person9",15 "categoricalAttributeValues":[2],16 "binaryAttributeValues":[true,false],17 "continuousAttributeValues":[34,1.4,14]},18 {"bipartite":0,"id":"person10",19 "binaryAttributeValues":[true,false],20 "continuousAttributeValues":[35,1.5,15],21 "categoricalAttributeValues":[0]},22 {"bipartite":0, "id":"person11",23 "binaryAttributeValues":[true,false],24 "continuousAttributeValues":[36,1.6,16],25 "categoricalAttributeValues":[0]},26 {"bipartite":0, "id":"person12",27 "binaryAttributeValues":[false,false],28 "continuousAttributeValues":[37.5,1.7,17],29 "categoricalAttributeValues":[1]},30 {"bipartite":1, "id":"place3",31 "continuousAttributeValues":[1000,18],32 "geodata":{"x":123.4,"y":464.3},33 "binaryAttributeValues":[true,false]},34 {"bipartite":1, "id":"place4",35 "continuousAttributeValues":[2000,19],36 "geodata":{"x":134.34,"y":234.234},37 "binaryAttributeValues":[false,false]}38 ],39 "adjacency": [[{"id":"place3"}, {"id":"place4"}],40 [{"id":"place3"}],[],[],[], [],[]41 ]},42 "structuralParameters":{"markovSa2":{"requested":"true", "value":1.0},43 "markovL":{"requested":1}},44 "attributeNames":{"continuousAttributesA":["age","magic"],45 "continuousAttributesP":["elevation"],46 "binaryAttributesP":["underground"],47 "binaryAttributesA":["student"],48 "binaryAttributesAP":["invisible"],49 "categoricalAttributesA":["gender"],50 "continuousAttributesAP":["specialness"]},51 "attributeParameters":{"attrRP_1":[{"requested":false}],52 "attrRA_1":[{"requested":false}],53 "attrRAP_1":[{"requested":false}],54 "attrRAc_1":[{"requested":true},{"requested":true}],55 "attrRPc_1":[{"requested":false}],56 "attrRAPc_1":[{"requested":true}]}57 }

Figure 7: Example JSON for an estimation request, with binary, continuous, and categorical attributes

40

1 { "graph": {2 "nodes": [{ "name":"person6",3 "attributes":{"bipartite":0}},4 {"name":"person7",5 "attributes":{"bipartite":0}},6 {"name":"person8",7 "attributes":{"bipartite":0}},8 {"name":"person9",9 "attributes":{"bipartite":0}},

10 {"name":"person10",11 "attributes":{"bipartite":0}},12 {"name":"person11",13 "attributes":{"bipartite":0}},14 {"name":"person12",15 "attributes":{"bipartite":0}},16 {"name":"place3",17 "attributes":{"bipartite":1}},18 {"name":"place4",19 "attributes":{"bipartite":1}}20 ],21 "edges": [ {"src":"person6", "dst":"place3"},22 {"src":"person6", "dst":"place4"},23 {"src":"person7", "dst":"place4"}24 ]25 },26 "structuralParameters":{"markovSa2":{"requested":"true", "value":1.0},27 "markovL":{"requested":1}28 },29 "dyadicCovariateParameters":[{"requested":true, "value":0.0}],30 "dyadicCovariates": [31 {"covariateName":"distance",32 "covariates": [33 {"src":"person6", "dst":"place3", "continuousValue":0.1},34 {"src":"person6", "dst":"place4", "continuousValue":0.2},35 {"src":"person7", "dst":"place3", "continuousValue":0.3},36 {"src":"person7", "dst":"place4", "continuousValue":0.4},37 {"src":"person8", "dst":"place3", "continuousValue":0.5},38 {"src":"person8", "dst":"place4", "continuousValue":0.6},39 {"src":"person9", "dst":"place3", "continuousValue":0.7},40 {"src":"person9", "dst":"place4", "continuousValue":0.8},41 {"src":"person10", "dst":"place3", "continuousValue":0.9},42 {"src":"person10", "dst":"place4", "continuousValue":1.0},43 {"src":"person11", "dst":"place3", "continuousValue":1.1},44 {"src":"person11", "dst":"place4", "continuousValue":1.2},45 {"src":"person12", "dst":"place3", "continuousValue":1.3},46 {"src":"person12", "dst":"place4", "continuousValue":1.4}47 ] } ] }

Figure 8: Example JSON data for an estimation request with JSONGraph network format and includingdyadic covariates.

41

1 { "graph": {2 "nodes": [{ "name":"person6",3 "attributes":{"bipartite":0}},4 {"name":"person7",5 "attributes":{"bipartite":0}},6 {"name":"person8",7 "attributes":{"bipartite":0}},8 {"name":"person9",9 "attributes":{"bipartite":0}},

10 {"name":"person10",11 "attributes":{"bipartite":0}},12 {"name":"person11",13 "attributes":{"bipartite":0}},14 {"name":"person12",15 "attributes":{"bipartite":0}},16 {"name":"place3",17 "attributes":{"bipartite":1}},18 {"name":"place4",19 "attributes":{"bipartite":1}}20 ],21 "edges": [ {"src":"person6", "dst":"place3"},22 {"src":"person6", "dst":"place4"},23 {"src":"person7", "dst":"place4"}24 ]25 },26 "structuralParameters":{"markovSa2":{"requested":"true", "value":1.0},27 "markovL":{"requested":1}28 },29 "namedDyadicCovariateParameters":[{"covariateName":"distance",30 "requested":true, "value":0.0}],31 "dyadicCovariatesJSONgraph":32 {"edges": [33 {"src":"person6", "dst":"place3", "attributes":{"distance":0.1}},34 {"src":"person6", "dst":"place4", "attributes":{"distance":0.2}},35 {"src":"person7", "dst":"place3", "attributes":{"distance":0.3}},36 {"src":"person7", "dst":"place4", "attributes":{"distance":0.4}},37 {"src":"person8", "dst":"place3", "attributes":{"distance":0.5}},38 {"src":"person8", "dst":"place4", "attributes":{"distance":0.6}},39 {"src":"person9", "dst":"place3", "attributes":{"distance":0.7}},40 {"src":"person9", "dst":"place4", "attributes":{"distance":0.8}},41 {"src":"person10", "dst":"place3", "attributes":{"distance":0.9}},42 {"src":"person10", "dst":"place4", "attributes":{"distance":1.0}},43 {"src":"person11", "dst":"place3", "attributes":{"distance":1.1}},44 {"src":"person11", "dst":"place4", "attributes":{"distance":1.2}},45 {"src":"person12", "dst":"place3", "attributes":{"distance":1.3}},46 {"src":"person12", "dst":"place4", "attributes":{"distance":1.4}}47 ] } }

Figure 9: Example JSON data for an estimation request with JSONGraph network format and includingdyadic covariates, specified using JSONgraph format and referred to by name in namedDyadicCovari-ateParameters.

42

1 {"EstimationResponse": {2 "responseGenerator": "BPNet",3 "responseType": "estimate",4 "responseVersion": "1.0",5 "bpnetVersion": "2.0.1",6 "markovL": {7 "estimate": -2.2441211221643482,8 "stderr": 0.9755163167461093,9 "t_ratio": -0.06987194588446222,

10 "significant": true,11 "count": 312 },13 "markovSa2": {14 "estimate": 2.9273901783716028,15 "stderr": 2.0174070128279835,16 "t_ratio": -0.05235434667102132,17 "significant": false,18 "count": 119 },20 "isDegenerate": false,21 "estimationTime": 106,22 "networkStatistics": {23 "graphDensity": 0.21428571428571427,24 "degreeDistributionA": [25 5,26 1,27 128 ],29 "degreeDistributionP": [30 0,31 1,32 1,33 0,34 0,35 0,36 0,37 038 ],39 "degreeDistributionAstddev": 0.7284313590846835,40 "degreeDistributionSkewA": 1.3577270894181974,41 "degreeDistributionPstddev": 0.5,42 "degreeDistributionSkewP": 0,43 "meanDegree": 0.3333333333333333,44 "globalClusteringCoefficient": 0,45 "twoPathDistributionA": [46 20,47 1,48 049 ],50 "twoPathDistributionP": [51 0,52 1,53 0,54 0,55 0,56 0,57 0,58 059 ]60 }61 }62 }

Figure 10: Example JSON data from an estimation response43

work statistics object” is described in Table 23, the “parameter statistics object” is described in Table 26,the “degree distributions” object is described in Table 27, the “GoF statistics object” is described inTable 32, the “GoF parameter object” is described in Table 33 and the “GoF attribute parameter object”is described in Table 34.

Table 31: Goodness-of-fit (GoF) response

Attribute Type DescriptionstartStatistics network statistics object Network statistics of the starting

(supplied) graphstartParameterStatistics parameter statistics object Parameter statistics of the starting

(supplied) graphsampleParameterStatistics array of parameter statistics Structural and actor attribute parame-

ter statistics of each sampled graphsampleStatistics array of network statistics Network statistics of each sam-

pled graph, if returnSampleGraph-Stats was set to true in request

sampleDegreeDistributions array of degree distributions Degree distributions of each sampledgraph, if returnSampleDegreeDistri-butions was set to true in request

sampleClusteringCoefficients array of double Global clustering coefficient of eachsampled graph, if returnSampleClus-teringCoefficients was set to true inrequest

sampleGraphs array of network objects A network object (see Section 2) foreach of the sampled graphs, if return-SampleGraphs was set to true

sampleGraphsJSONgraph array of JSONgraph objects A JSONgraph object (see Section 2.3)for each of the sampled graphs, if re-turnSampleGraphs was set to true.This is exactly the same data as sam-pleGraphs, but in JSONgraph format.

sampleGraphsURL String URL of zip archive of sampled graphsin Pajek format, to be used in aGET request to download data toclient. Only set if returnSample-GraphsAsURL is set to true in therequest

gofStatistics GoF statistics object The goodness-of-fit statistics com-puted

degreeDistributionAstddev GoF parameter object standard deviation of degree distribu-tion of class A nodes

degreeDistributionSkewA GoF parameter object skewness of degree distribution ofclass A nodes

degreeDistributionPstddev GoF parameter object standard deviation of degree distribu-tion of class P nodes

degreeDistributionSkewP GoF parameter object skewness of degree distribution ofclass P nodes

globalClusteringCoefficient GoF parameter object global clustering coefficient

44


Attribute Type DescriptionacceptanceRate double The acceptance rate is the ratio of ac-

cepted simulation tie changes to alltie changes within each simulationinterval between every two sampledgraphs

mahalanobisDistance double Mahalanobis distance between orig-inal parameters and parameters ofsampled graphs

mahalanobisDistanceSquared double square of Mahalanobis distancerequestId long Request identifier as supplied in the

request that generated this response.responseGenerator string Versioning information: the name of

the process that generated this re-sponse. “BPNet”

responseType string Versioning information: the type ofresponse generated: “gof”

responseVersion string Versioning information: the versionof this object. “1.0”

bpnetVersion string Versioning information: the versionof the BPNet software that created thedata in this object. Currently “2.0.1”

gofTime long elapsed time of the goodness-of-fitprocedure in milliseconds

Table 32: GoF statistics object

Attribute Type DescriptionmarkovL GoF parameter object Edge (density)markovSa2 GoF parameter object Two-star for class A (2-A-star)markovSp2 GoF parameter object Two-star for class P (2-P-star)markovSa3 GoF parameter object Three-star for class A (3-A-star)markovSp3 GoF parameter object Three-star for class P (3-P-star)markovL3 GoF parameter object Three-pathmarkovC4 GoF parameter object Four-cyclehighOrderKSa GoF parameter object alternating k-star for class A (k-

A-star)highOrderKSp GoF parameter object alternating k-star for class P (k-

P-star)highOrderKCa GoF parameter object alternating A cycleshighOrderKCp GoF parameter object alternating P cycleshighOrderKCa2 GoF parameter object same as KCa but allows different

lambdahighOrderKCp2 GoF parameter object same as KCp but allows different

lambdaactor attribute parameters (A)

binary

attrRA 1 GoF parameter object array

45



attrTscA 1 GoF parameter object array

attrTsoA1 1 GoF parameter object array

attrTsoA2 1 GoF parameter object array

attrC4A1 1 GoF parameter object array

attrC4A2 1 GoF parameter object arraycontinuous

attrRAc 1 GoF parameter object array

attrTscAc 1 GoF parameter object array

attrTsoAcs 1 GoF parameter object array

attrTsoAcd 1 GoF parameter object array

46



attrC4Acs 1 GoF parameter object array

attrC4Acd 1 GoF parameter object arraycategorical

attrMatching 2PathA 1 GoF parameter object array

attrMismatching 2PathA 1 GoF parameter object array

attrMatching 4CycleA 1 GoF parameter object array

attrMismatching 4CycleA 1 GoF parameter object arrayactor attribute parameters (P)

binary

attrRP 1 GoF parameter object array

attrTscP 1 GoF parameter object array

attrTsoP1 1 GoF parameter object array

47



attrTsoP2 1 GoF parameter object array

attrC4P1 1 GoF parameter object array

attrC4P2 1 GoF parameter object arraycontinuous

attrRPc 1 GoF parameter object array

attrTscPc 1 GoF parameter object array

attrTsoPcs 1 GoF parameter object array

attrTsoPcd 1 GoF parameter object array

attrC4Pcs 1 GoF parameter object array

48



attrC4Pcd 1 GoF parameter object arraycategorical

attrMatching 2PathP 1 GoF parameter object array

attrMismatching 2PathP 1 GoF parameter object array

attrMatching 4CycleP 1 GoF parameter object array

attrMismatching 4CycleP 1 GoF parameter object arrayactor attribute parameters (A&P)

binary

attrRAP 1 GoF parameter object arraycontinuous

attrRAPc 1 GoF parameter object arrayDyadic covariates (continuous only)

dyadicCovariateParameters GoF dyadic covariate object array The object is described in Table35. The dyadic covariate param-eter gives an indication of the in-fluence of the relevant dyadic co-variate (an attribute of each pairof nodes) on the probability of atie forming between two nodes.

49

Table 33: GoF parameter object

Attribute Type Descriptionobserved double observed parameter value in the supplied graphmean double mean parameter value in sampled graphsstddev double standard deviation of the parameter values in sampled graphst ratio double (observed value - sample mean) / standard deviation

Table 34: GoF attribute parameter object

Attribute Type DescriptionattributeName string name of the attributeobserved double observed parameter value in the supplied graphmean double mean parameter value in sampled graphsstddev double standard deviation of the parameter values in sampled graphst ratio double (observed value - sample mean) / standard deviation

Table 35: GoF dyadic covariate parameter object

Attribute Type DescriptioncovariateName string name of the dyadic covariateobserved double observed parameter value in the supplied graphmean double mean parameter value in sampled graphsstddev double standard deviation of the parameter values in sampled graphst ratio double (observed value - sample mean) / standard deviation

5.4 Get zip archive of graphs

Downloading sampled graphs in a zip archive is done by using the GET method to URI <URI>/files/<name> where <name> is the name of the zip archive of graphs in Pajek format to get. This URI isexactly that returned in the sampleGraphsURL field SimulationResponse (Table 25) or GofResponse(Table 31) objects.

The response is binary data with content-type application/zip, the zip archive containing thesampled graphs in Pajek format (sampled graphs in a .paj file, and bipartite partition in a .clu file).

This request should be followed by a DELETE request to the same URI (as described in the followingsection) to delete the archive from the server.

5.5 Delete zip archive of graphs

Deleting a zip archive after it is obtained using the GET method is done by using the DELETE methodto the same URI. That is, to URI <URI>/files/<name> where <name> is the name of the ziparchive of graphs in Pajek format that was previously downloaded. This URI is exactly that returned inthe sampleGraphsURL field SimulationResponse (Table 25) or GofResponse (Table 31) objects.

There is no content in the response to this request — success is denoted simply by HTTP status 204(NO CONTENT).

50

<URI>/files/<name>

<URI>/files/<name>

<name>

<URI>/files/<name>

<name>

6 Examples

This example shows the curl command being used to send an estimation request, and its response.

$ curl -X POST -Hcontent-type:application/json-Haccept:application/json --data ’{"network" : {"directed": false,"graph": [["example", "bipartite"]], "nodes": [{"bipartite": 0, "id":1}, {"bipartite": 0, "id": 2}, {"bipartite": 0, "id": 3},{"bipartite": 0, "id": 4}, {"bipartite": 1, "id": 5}, {"bipartite":1, "id": 6}, {"bipartite": 1, "id": 7}], "adjacency": [[{"id": 5},{"id": 6}], [{"id": 6}, {"id": 7}], [{"id": 7}], [{"id": 5}], [{"id":1}, {"id": 4}], [{"id": 1}, {"id": 2}], [{"id": 2}, {"id": 3}]],"multigraph":false},"structuralParameters":{"markovL":{"requested":true}},"numberOfSubphases":3 }’http://localhost:8080/aurin-MelNet-BPNet-REST/service/estimate

{"EstimationResponse":{"responseGenerator":"BPNet","responseType":"estimate","responseVersion":"1.0","bpnetVersion":"2.0.1","isDegenerate":false,"markovL":{"estimate":-0.014073577834639429,"stderr":0.5877351787009722,"t_ratio":0.0058773517870095975,"significant":false,"count":6},"estimationTime":19,"networkStatistics":{"graphDensity":0.5,"degreeDistributionA":[0,2,2,0],"degreeDistributionP":[0,0,3,0,0],"degreeDistributionAstddev":0.5,"degreeDistributionSkewA":0.0,"degreeDistributionPstddev":0.0,"degreeDistributionSkewP":"NaN","meanDegree":0.8571428571428571,"globalClusteringCoefficient":0.0,"twoPathDistributionA":[3,3,0,0],"twoPathDistributionP":[1,2,0,0,0]}}}

7 Data conversion

To facilitate the use of existing BPNet configuration settings and data with the new BPNet REST API,two Python scripts are provided. The first, bpnetsetting2json.py, reads the BPNet configurationfile setting.txt and its associated data, and writes the JSON for the correspondign BPNet RESTrequest to the standard output. The second, json2bpnetsetting.py, reads the JSON for a BP-Net REST request on standard intput, and writes the corresponding BPNet setting.txt file and itsassociated data files to a specified directory.

7.1 bpentsetting2json.py: convert BPNet configuration to BPNet REST API JSONstring

Usage: bpnetsetting2json.py bpnetSettingFile

bpnetSettingFile is the setting.txt file created by the BPNet Windows GUI.

The JSON string for the BPNet REST API request corresponding to the BPNet settings is written to thestandard output stream.

The following example shows the usge of the script, with its JSON output:

$ ../scripts/bpnetsetting2json.pyexamples/BPNet_sessions/estimate/small_bipartite/setting.txt

{"network": {"graph": [["description", "bipartite"],["comment","generated by bpnetsetting2json.py from BPNet config file

51

’examples/BPNet_sessions/estimate/small_bipartite/setting.txt’network file’examples/BPNet_sessions/estimate/small_bipartite/small_bipartite.txt’on 12Feb2013 11:52:23"]],"nodes": [{"bipartite": 0, "id": 1},{"bipartite": 0, "id": 2}, {"bipartite": 0, "id": 3}, {"bipartite":0, "id": 4}, {"bipartite": 0, "id": 5}, {"bipartite": 1, "id": 6},{"bipartite": 1, "id": 7}, {"bipartite": 1, "id": 8}, {"bipartite":1, "id": 9}, {"bipartite": 1, "id": 10}, {"bipartite": 1, "id": 11}],"adjacency":[[{"id": 6},{"id": 7}],[{"id": 6},{"id": 7},{"id":8}],[{"id": 6},{"id": 7},{"id": 8},{"id": 9}],[{"id": 7},{"id":8},{"id": 9},{"id": 10},{"id": 11}],[{"id": 11}],[{"id": 1},{"id":2},{"id": 3}],[{"id": 1},{"id": 2},{"id": 3},{"id": 4}],[{"id":2},{"id": 3},{"id": 4}],[{"id": 3},{"id": 4}],[{"id": 4}],[{"id":4},{"id":5}]]},"structuralParameters":{"markovL":{"requested":true,"value":0.0},"markovSa2":{"requested":true,"value":0.0},"markovSp2":{"requested":true,"value":0.0},"markovSa3":{"requested":true,"value":0.0},"markovSp3":{"requested":false,"value":0.0},"markovL3":{"requested":false,"value":0.0},"markovC4":{"requested":false,"value":0.0},"highOrderKSa":{"requested":true,"value":0.0,"lambda":2.0},"highOrderKSp":{"requested":true,"value":0.0,"lambda":2.0},"highOrderKCa":{"requested":true,"value":0.0,"lambda":2.0},"highOrderKCp":{"requested":false,"value":0.0,"lambda":2.0},"highOrderKCa2":{"requested":false,"value":0.0,"lambda":3.0},"highOrderKCp2":{"requested":false,"value":0.0,"lambda":3.0}},"attributeParameters":{},"numberOfSubphases":5,"numEstimationRuns":1,"fixGraphDensity":false,"gainingFactor":0.01,"multiplicationFactor":20,"numIterationsPhase3":500}

The following example shows the json2bpnetsetting.py script run on the same input, thistime using the curl command to send the JSON that it creates to the BPNet web service, with the JSONoutput from the web service formatted with the json pp command:

$ ../scripts/bpnetsetting2json.pyexamples/BPNet_sessions/estimate/small_bipartite/setting.txt |curl -X POST -Hcontent-type:application/json -Haccept:application/json--data @- http://localhost:8080/aurin-MelNet-BPNet-REST/service/estimate |json_pp

{"EstimationResponse" : {

"highOrderKSa" : {"count" : 13,"stderr" : 1.28641448600065,"significant" : true,"t_ratio" : 0.036444006283477,"estimate" : -13.5339101204743

},"markovSa3" : {

"count" : 15,"stderr" : 0.825055070326505,"significant" : true,"t_ratio" : 0.0220849418811391,"estimate" : -2.72102932455495

},

52

"responseGenerator" : "BPNet","highOrderKSp" : {

"count" : 11,"stderr" : 3.31016342679732,"significant" : false,"t_ratio" : -0.00182552094035139,"estimate" : -0.0297906009803559

},"isDegenerate" : false,"bpnetVersion" : "2.0.1","highOrderKCa" : {

"count" : 16,"stderr" : 1.46285226470315,"significant" : false,"t_ratio" : 0.0434939553362854,"estimate" : 0.516629001518306

},"markovL" : {

"count" : 15,"stderr" : 3.16613583632693,"significant" : false,"t_ratio" : 0.0364882519524786,"estimate" : 2.99810049078323

},"responseType" : "estimate","estimationTime" : 240,"networkStatistics" : {

"degreeDistributionAstddev" : 1.4142135623731,"twoPathDistributionP" : [

2,8,3,2,0,0

],"degreeDistributionPstddev" : 0.957427107756338,"degreeDistributionA" : [

0,1,1,1,1,1,0

],"graphDensity" : 0.5,"globalClusteringCoefficient" : 0.507042253521127,"degreeDistributionSkewP" : 0,"degreeDistributionSkewA" : 0,"degreeDistributionP" : [

0,1,2,2,

53

1,0

],"meanDegree" : 1.36363636363636,"twoPathDistributionA" : [

3,2,3,2,0,0,0

]},"markovSa2" : {

"count" : 20,"stderr" : 1.56522535784292,"significant" : true,"t_ratio" : 0.0353566036998016,"estimate" : 9.51672420659228

},"markovSp2" : {

"count" : 14,"stderr" : 1.59462855459982,"significant" : false,"t_ratio" : -0.0215576019314695,"estimate" : -0.00402239753311309

},"responseVersion" : "1.0"

}}

7.2 json2bpentsetting.py: convert BPNet REST API JSON string to BPNet set-ting files

Usage: json2bpetsetting.py [-o] [-t type] bpnetSettingDirectory

-o : overwrite files in the bpnetSettingDirectory. If not specified, will exit without writing if files inthatdirectory exist.

-t type : specfiy the request type: estimate, simulate or gof. Must be specified if requestTypeis not present in the JSON input.

bpnetSettingDirectory is the directory in which to write the BPNet setting.txt and associated datafiles created from the input JSON.

JSON data for a BPNet REST API request is read from the standard input, and the correspondingBPNet setting.txt and associated files are written to the specified directory. The BPNet WindowsGUI can then be used with this data.

The following example shows thejson2bpnetsetting.py script being used to create BPNetsettings files from BPNet REST API JSON data:

$ cat examples/JSON/estimate/attrexample.json{

"network": {

54

"nodes": [{"bipartite":0, "id":"person6","binaryAttributeValues":[true,false],"continuousAttributeValues":[31,1.1,11],"categoricalAttributeValues":[0]

},{"bipartite":0, "id":"person7","categoricalAttributeValues":[1],"binaryAttributeValues":[false,false],"continuousAttributeValues":[32,1.2,12]

},{"bipartite":0,"categoricalAttributeValues":[0],"id":"person8","binaryAttributeValues":[true,false],"continuousAttributeValues":[33,1.3,13]

},{"bipartite":0, "id":"person9","categoricalAttributeValues":[2],"binaryAttributeValues":[true,false],"continuousAttributeValues":[34,1.4,14]

},{"bipartite":0,"id":"person10","binaryAttributeValues":[true,false],"continuousAttributeValues":[35,1.5,15],"categoricalAttributeValues":[0]

},{"bipartite":0, "id":"person11","binaryAttributeValues":[true,false],"continuousAttributeValues":[36,1.6,16],"categoricalAttributeValues":[0]

},{"bipartite":0, "id":"person12","binaryAttributeValues":[false,false],"continuousAttributeValues":[37.5,1.7,17],"categoricalAttributeValues":[1]

},{"bipartite":1, "id":"place3","continuousAttributeValues":[1000,18],"geodata":{"x":123.4,"y":464.3

},"binaryAttributeValues":[true,false]

},{"bipartite":1, "id":"place4","continuousAttributeValues":[2000,19],"geodata":{"x":134.34,"y":234.234},"binaryAttributeValues":[false,false]

}],

"adjacency": [[{"id":"place3"}, {"id":"place4"}],[{"id":"place3"}],[],[],[],[],[]

]},"attributeNames":{"continuousAttributesA":["age","magic"],

55

"continuousAttributesP":["elevation"],"binaryAttributesP":["underground"],"binaryAttributesA":["student"],"binaryAttributesAP":["invisible"],"categoricalAttributesA":["gender"],"continuousAttributesAP":["specialness"]

},

"structuralParameters":{"markovSa2":{"requested":"true", "value":1.0},"markovL":{"requested":1}},

"attributeParameters":{"attrRP_1":[{"requested":false}],"attrRA_1":[{"requested":false}],"attrRAP_1":[{"requested":false}],"attrRAc_1":[{"requested":true},{"requested":true}],"attrRPc_1":[{"requested":true}],"attrRP_1":[{"requested":false}],"attrRAPc_1":[{"requested":true}]

}}

$ cat examples/JSON/estimate/attrexample.json |../scripts/json2bpnetsetting.py -t estimate /var/tmp/attrexample_bpnet

$ ls -l /var/tmp/attrexample_bpnettotal 36-rw-rw-r-- 1 alex alex 28 Feb 12 12:25 binaryAttributesAP.txt-rw-rw-r-- 1 alex alex 22 Feb 12 12:25 binaryAttributesA.txt-rw-rw-r-- 1 alex alex 16 Feb 12 12:25 binaryAttributesP.txt-rw-rw-r-- 1 alex alex 21 Feb 12 12:25 categoricalAttributesA.txt-rw-rw-r-- 1 alex alex 39 Feb 12 12:25 continuousAttributesAP.txt-rw-rw-r-- 1 alex alex 61 Feb 12 12:25 continuousAttributesA.txt-rw-rw-r-- 1 alex alex 20 Feb 12 12:25 continuousAttributesP.txt-rw-rw-r-- 1 alex alex 28 Feb 12 12:25 network.txt-rw-rw-r-- 1 alex alex 1895 Feb 12 12:25 setting.txt

$ cat /var/tmp/attrexample_bpnet/network.txt1 11 00 00 00 00 00 0

ReferencesD. Lusher, J. Koskinen, and G. Robins, editors. Exponential Random Graph Models for Social Networks. Num-

ber 35 in Structural Analysis in the Social Sciences. Cambridge University Press, New York, 2013.

G. Robins, P. Pattison, Y. Kalish, and D. Lusher. An introduction to exponential random graph (p∗) models forsocial networks. Social Networks, 29:173–191, 2007.

P. Wang. Exponential random graph model extensions: Models for multiple networks and bipartite networks. InLusher et al. (2013), chapter 10, pages 115–129.

56

P. Wang, K. Sharpe, G. L. Robins, and P. E. Pattison. Exponential random graph (p∗) models for affiliationnetworks. Social Networks, 31:12–25, 2009.

57

REST API Documentation for the BPNet Web Service

Documents

Transcript of REST API Documentation for the BPNet Web Service