rest api documentation for the bpnet web service
TRANSCRIPT
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
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
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
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
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
Table 13: (continued)
Attribute Type Description
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
Table 13: (continued)
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
Table 13: (continued)
Attribute Type Description
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
Table 18: (continued)
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
Table 18: (continued)
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
Table 18: (continued)
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
Table 19: (continued)
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
Table 19: (continued)
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
Table 19: (continued)
Attribute Type Description
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
Table 19: (continued)
Attribute Type Description
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
Table 19: (continued)
Attribute Type Description
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
Table 23: (continued)
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
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“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
Table 24: (continued)
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
Table 24: (continued)
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
Table 24: (continued)
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
Table 25: (continued)
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
Table 26: (continued)
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
Table 26: (continued)
Attribute Type Description
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
Table 26: (continued)
Attribute Type Description
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
Table 26: (continued)
Attribute Type Description
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
Table 26: (continued)
Attribute Type Description
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
Attribute Type Description
36
Table 30: (continued)
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“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
Table 30: (continued)
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
Table 30: (continued)
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
Table 31: (continued)
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
Table 32: (continued)
Attribute Type Description
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
Table 32: (continued)
Attribute Type Description
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
Table 32: (continued)
Attribute Type Description
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
Table 32: (continued)
Attribute Type Description
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
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