NiceCXNetwork module

The NiceCXNetwork class provides a data model for working with NDEx networks. Methods are provided to add nodes, edges, node attributes, edge attributes, etc. Once a NiceCXNetwork data object is populated it can be saved to the NDEx server by calling either upload_to() to create a new network or update_to() to update an existing network.

To see deprecated methods go to Deprecated NiceCXNetwork methods

Methods for building niceCX

see also this notebook

Node methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
create_node(node_name=None, node_represents=None)

Creates a new node with the corresponding name and represents (external id)

Example:

my_node = create_node(node_name='MAPK1, node_represents='1114208')
Parameters:
  • node_name (str) – Name of the node
  • node_represents (str) – Representation of the node (alternate identifier)
Returns:

Node ID
Return type:

int
set_node_attribute(node, attribute_name, values, type=None)

Set an attribute of a node, where the node may be specified by its id or passed in as a node dict.

Example:

set_node_attribute(my_node, 'Pathway', 'Signal Transduction / Growth Regulation')

or

set_node_attribute(my_node, 'Mutation Frequency', 0.007, type='double')

Parameters:
  • node (int or node dict with @id attribute) – Node to add the attribute to
  • attribute_name (string) – attribute name
  • values (list, string, int or double) – A value or list of values of the attribute
  • type (str) – The datatype of the attribute values, defaults is string. See Supported data types
  • cx_fragment (json) – CX fragment
Returns:

None
Return type:

None

Edge methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
create_edge(edge_source=None, edge_target=None, edge_interaction=None)

Create a new edge in the network by specifying source-interaction-target

Example:

my_edge = create_edge(edge_source=my_node, edge_target=my_node2, edge_interaction='up-regulates')
Parameters:
  • edge_source (int, dict (with @id property)) – The source node of this edge, either its id or the node object itself.
  • edge_target (int, dict (with @id property)) – The target node of this edge, either its id or the node object itself.
  • edge_interaction (string) – The interaction that describes the relationship between the source and target nodes
Returns:

Edge ID
Return type:

int
set_edge_attribute(edge, attribute_name, values, type=None)

Set the value(s) of attribute of an edge, where the edge may be specified by its id or passed in an object.

Example:

set_edge_attribute(0, 'weight', 0.5, type='double')

or

set_edge_attribute(my_edge, 'Disease', 'Atherosclerosis')

Parameters:
  • edge (int or edge dict with @id attribute) – Edge to add the attribute to
  • attribute_name (str) – Attribute name
  • values (list) – A value or list of values of the attribute
  • type (str) – The datatype of the attribute values, defaults to the python datatype of the values. See Supported data types
Returns:

None
Return type:

None

Network methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
set_context(context)

Set the @context information of the network. This information maps namespace prefixes to their defining URIs

Example:

set_context({'pmid': 'https://www.ncbi.nlm.nih.gov/pubmed/'})
Parameters:context (dict) – dict of name, URI pairs
Returns:None
Return type:none
set_name(network_name)

Set the network name

Example:

set_name('P38 Signaling')
Parameters:network_name (string) – Network name
Returns:None
Return type:None
set_network_attribute(name, values=None, type=None)

Set an attribute of the network

Example:

set_network_attribute(name='networkType', values='Genetic interactions')
Parameters:
  • name (string) – Attribute name
  • values (list, string, double or int) – The values of the attribute
  • type (str) – The datatype of the attribute values. See Supported data types
Returns:

None
Return type:

none
set_opaque_aspect(aspect_name, aspect_elements)

Set the aspect specified by aspect_name to the list of aspect elements. If aspect_elements is None, the aspect is removed.

Parameters:
  • aspect_name (string) – Name of the aspect
  • aspect_elements (list of dict) – Aspect element
Returns:

None
Return type:

none

Methods for accessing niceCX properties

see also this notebook

Node methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
get_node_attribute(node, attribute_name)

Get the node attribute of a node, where the node may be specified by its id or passed in as an object.

Example:

get_node_attribute(my_node, 'Pathway') # returns: {'@id': 0, 'n': 'diffusion-heat', 'v': 0.832, 'd': 'double'}
Parameters:
  • node (int or node dict with @id attribute) – node object or node id
  • attribute_name – attribute name
Returns:

the node attibute object or None if the attribute doesn’t exist
Return type:

dict
get_node_attribute_value(node, attribute_name)

Get the value(s) of an attribute of a node, where the node may be specified by its id or passed in as an object.

Example:

get_node_attribute_value(my_node, 'Pathway') # returns: 'Signal Transduction / Growth Regulation'
Parameters:
  • node (int or node dict with @id attribute) – node object or node id
  • attribute_name – attribute name
Returns:

the value of the attibute or None if the attribute doesn’t exist
Return type:

string
get_node_attributes(node)

Get the attribute objects of a node, where the node may be specified by its id or passed in as an object.

Example:

get_node_attributes(my_node) # returns: [{'po': 0, 'n': 'Pathway', 'v': 'Signal Transduction / Growth Regulation'}]
Parameters:node (int or node dict with @id attribute) – node object or node id
Returns:node attributes
Return type:list
get_nodes()

Returns an iterator over node ids as keys and node objects as values.

Example:

for id, node in nice_cx.get_nodes():

node_name = node.get('n')

node_represents = node.get('r')

Returns:iterator over nodes
Return type:iterator

Edge methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
get_edge_attribute(edge, attribute_name)

Get the edge attributes of an edge, where the edge may be specified by its id or passed in as an object.

Example:

get_edge_attribute(my_edge, 'weight')

# returns: {'@id': 0, 'n': 'weight', 'v': 0.849, 'd': 'double'}

Parameters:
  • edge (int or edge dict with @id attribute) – Edge object or edge id
  • attribute_name – Attribute name
Returns:

Edge attribute object
Return type:

list, string, int or double
get_edge_attribute_value(edge, attribute_name)

Get the value(s) of an attribute of an edge, where the edge may be specified by its id or passed in as an object.

Example:

get_edge_attribute_value(my_edge, 'weight')

# returns: 0.849

Parameters:
  • edge (int or edge dict with @id attribute) – Edge object or edge id
  • attribute_name – Attribute name
Returns:

Edge attribute value(s)
Return type:

list, string, int or double
get_edge_attributes(edge)

Get the attribute objects of an edge, where the edge may be specified by its id or passed in as an object.

Example:

get_edge_attributes(my_edge)

# returns: [{'@id': 0, 'n': 'weight', 'v': 0.849, 'd': 'double'}, {'@id': 0, 'n': 'Type', 'v': 'E1'}]

Parameters:edge (int or edge dict with @id attribute) – Edge object or edge id
Returns:Edge attribute objects
Return type:list of edge dict
get_edges()

Returns an iterator over edge ids as keys and edge objects as values.

Example:

for edge_id, edge_obj in nice_cx.get_edges():

print(edge_obj.get('i')) # print interaction

print(edge_obj.get('s')) # print source node id

Returns:Edge iterator
Return type:iterator

Network methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
get_context()

Get the @context information of the network. This information maps namespace prefixes to their defining URIs

Example:

{'pmid': 'https://www.ncbi.nlm.nih.gov/pubmed/'}
Returns:context object
Return type:dict
get_name()

Get the network name

Returns:Network name
Return type:string
get_network_attribute(attribute_name)

Get the value of a network attribute

Parameters:attribute_name (string) – Attribute name
Returns:Network attribute object
Return type:dict
get_opaque_aspect(aspect_name)

Get the elements of the aspect specified by aspect_name

Parameters:aspect_name (string) – the name of the aspect to retrieve.
Returns:Opaque aspect
Return type:list of aspect elements

Misc niceCX methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
apply_template(server, uuid, username=None, password=None)

Applies the Cytoscape visual properties of a network from the provided uuid to this network.

This allows the use of networks formatted in Cytoscape as templates to apply visual styles to other networks.

Example:

nice_cx.apply_template('public.ndexbio.org', '51247435-1e5f-11e8-b939-0ac135e8bacf')
Parameters:
  • server (string) – server host name (i.e. public.ndexbio.org)
  • username (string) – username (optional - used when accessing private networks)
  • password (string) – password (optional - used when accessing private networks)
  • uuid (string) – uuid of the styled network
Returns:

None
Return type:

None
print_summary()

Print a network summary

Returns:Network summary
Return type:string
to_cx()

Return the CX corresponding to the network.

Returns:CX representation of the network
Return type:CX (list of dict aspects)
to_cx_stream()

Returns a stream of the CX corresponding to the network. Can be used to post to endpoints that can accept streaming inputs

Returns:The CX stream representation of this network.
Return type:io.BytesIO
to_networkx()

Returns a NetworkX graph based on the network. Elements in the CartesianCoordinates aspect of the network are transformed to the NetworkX pos attribute. Node name is stored in the networkx node id. Node ‘represents’ is stored in the networkx node attribute ‘represents’

Example:

G = nice_cx.to_networkx() # G is now a networkx object
Returns:Networkx graph
Return type:networkx Graph()
to_pandas_dataframe()

Export the network as a Pandas DataFrame.

Example:

df = nice_cx.to_pandas_dataframe() # df is now a pandas dataframe

Note: This method only processes nodes, edges, node attributes and edge attributes, but not network attributes or other aspects

Returns:Pandas dataframe
Return type:Pandas dataframe
update_to(uuid, server, username, password)

Upload this network to the specified server to the account specified by username and password.

Example:

nice_cx.update_to('2ec87c51-c349-11e8-90ac-525400c25d22', 'public.ndexbio.org, username, password)
Parameters:
  • server (str) – The NDEx server to upload the network to.
  • username (str) – The username of the account to store the network.
  • password (str) – The password for the account.
Returns:

The UUID of the network on NDEx.
Return type:

str
upload_to(server, username, password)

Upload this network to the specified server to the account specified by username and password.

Example:

nice_cx.upload_to('http://public.ndexbio.org', username, password)
Parameters:
  • server (string) – The NDEx server to upload the network to.
  • username (string) – The username of the account to store the network.
  • password (string) – The password for the account.
Returns:

The UUID of the network on NDEx.
Return type:

string

Deprecated NiceCXNetwork methods

class ndex2.NiceCXNetwork.NiceCXNetwork(**attr)
add_edge(id=None, source=None, target=None, interaction=None)

Warning

This method has been deprecated. Please use create_edge()

add_node(id=None, name=None, represents=None)

Warning

This method has been deprecated. Please use create_node()

get_edge_attribute_objects(edge, attribute_name)

Warning

This method has been deprecated. Please use get_edge_attributes()

get_node_attribute_objects(node, attribute_name)

Warning

This method has been deprecated. Please use get_node_attribute()

get_summary()

Warning

This method has been deprecated. Please use print_summary()

set_provenance(provenance)

Warning

This method has been deprecated.

Supported data types

The following data types are supported in methods that accept type

Example:

set_edge_attribute(0, 'weight', 0.5, type='double')
  • string
  • double
  • boolean
  • integer
  • long
  • list_of_string
  • list_of_double
  • list_of_boolean
  • list_of_integer
  • list_of_long

Methods for creating niceCX from other data models

ndex2.create_nice_cx_from_raw_cx(cx)

Create a NiceCXNetwork from a CX json object. (see http://www.home.ndexbio.org/data-model)

Parameters:cx – a valid CX document
Returns:NiceCXNetwork
ndex2.create_nice_cx_from_file(path)

Create a NiceCXNetwork from a file that is in the CX format.

Parameters:path – the path of the CX file
Returns:NiceCXNetwork
ndex2.create_nice_cx_from_networkx(G)

Creates a NiceCXNetwork based on a networkx graph. The resulting NiceCXNetwork contains the nodes edges and their attributes from the networkx graph and also preserves the graph ‘pos’ attribute as a CX cartesian coordinates aspect. Node name is taken from the networkx node id. Node ‘represents’ is taken from the networkx node attribute ‘represents’

Parameters:G (networkx graph) – networkx graph
Returns:NiceCXNetwork
Return type:NiceCXNetwork
ndex2.create_nice_cx_from_pandas(df, source_field=None, target_field=None, source_node_attr=[], target_node_attr=[], edge_attr=[], edge_interaction=None, source_represents=None, target_represents=None)

Create a NiceCXNetwork from a pandas dataframe in which each row specifies one edge in the network.

If only the df argument is provided the dataframe is treated as ‘SIF’ format, where the first two columns specify the source and target node ids of the edge and all other columns are ignored. The edge interaction is defaulted to “interacts-with”

If both the source_field and target_field arguments are provided, the those and any other arguments refer to headers in the dataframe, controlling the mapping of columns to the attributes of nodes, and edges in the resulting NiceCXNetwork. If a header is not mapped the corresponding column is ignored. If the edge_interaction is not specified it defaults to “interacts-with”

Parameters:
  • df – pandas dataframe to process
  • source_field – header name specifying the name of the source node.
  • target_field – header name specifying the name of the target node.
  • source_node_attr – list of header names specifying attributes of the source node.
  • target_node_attr – list of header names specifying attributes of the target node.
  • edge_attr – list of header names specifying attributes of the edge.
  • edge_interaction – the relationship between the source node and the target node, defaulting to “interacts-with”
Returns:

NiceCXNetwork
ndex2.create_nice_cx_from_server(server, username=None, password=None, uuid=None)

Create a NiceCXNetwork based on a network retrieved from NDEx, specified by its UUID. If the network is not public, then username and password arguments for an account on the server with permission to access the network must be supplied.

Parameters:
  • server – the URL of the NDEx server hosting the network.
  • username – the user name of an account with permission to access the network.
  • password – the password of an account with permission to access the network.
  • uuid – the UUID of the network.
Returns:

NiceCXNetwork

Client access to NDEx server API

class ndex2.client.Ndex2(host=None, username=None, password=None, update_status=False, debug=False, user_agent='')

A class to facilitate communication with an NDEx server.

If host is not provided it will default to the NDEx public server. UUID is required

add_networks_to_networkset(set_id, networks)

Add networks to a network set. User must have visibility of all networks being added

Parameters:
  • set_id (basestring) – network set id
  • networks (list of strings) – networks that will be added to the set
Returns:

None
Return type:

None
create_networkset(name, description)

Creates a new network set

Parameters:
  • name (string) – Network set name
  • description (string) – Network set description
Returns:

URI of the newly created network set
Return type:

string
delete_network(network_id, retry=5)

Deletes the specified network from the server

Parameters:
  • network_id (string) – Network id
  • retry (int) – Number of times to retry if deleting fails
Returns:

Error json if there is an error. Blank
Return type:

string
delete_networks_from_networkset(set_id, networks, retry=5)

Removes network(s) from a network set.

Parameters:
  • set_id (basestring) – network set id
  • networks (list of strings) – networks that will be removed from the set
  • retry (int) – Number of times to retry
Returns:

None
Return type:

None
get_neighborhood(network_id, search_string, search_depth=1, edge_limit=2500)

Get the CX for a subnetwork of the network specified by UUID network_id and a traversal of search_depth steps around the nodes found by search_string.

Parameters:
  • network_id (str) – The UUID of the network.
  • search_string (str) – The search string used to identify the network neighborhood.
  • search_depth (int) – The depth of the neighborhood from the core nodes identified.
  • edge_limit (int) – The maximum size of the neighborhood.
Returns:

The CX json object.
Return type:

response object
get_neighborhood_as_cx_stream(network_id, search_string, search_depth=1, edge_limit=2500, error_when_limit=True)

Get a CX stream for a subnetwork of the network specified by UUID network_id and a traversal of search_depth steps around the nodes found by search_string.

Parameters:
  • network_id (str) – The UUID of the network.
  • search_string (str) – The search string used to identify the network neighborhood.
  • search_depth (int) – The depth of the neighborhood from the core nodes identified.
  • edge_limit (int) – The maximum size of the neighborhood.
  • error_when_limit (boolean) – Default value is true. If this value is true the server will stop streaming the network when it hits the edgeLimit, add success: false and error: “EdgeLimitExceeded” in the status aspect and close the CX stream. If this value is set to false the server will return a subnetwork with edge count up to edgeLimit. The status aspect will be a success, and a network attribute {“EdgeLimitExceeded”: “true”} will be added to the returned network only if the server hits the edgeLimit..
Returns:

The response.
Return type:

response object
get_network_as_cx_stream(network_id)

Get the existing network with UUID network_id from the NDEx connection as a CX stream.

Parameters:network_id (str) – The UUID of the network.
Returns:The response.
Return type:response object
get_network_ids_for_user(username)

Get the network uuids owned by the user

Parameters:username (str) – users NDEx username
Returns:list of uuids
get_network_set(set_id)

Gets the network set information including the list of networks

Parameters:set_id (basestring) – network set id
Returns:network set information
Return type:dict
get_network_summary(network_id)

Gets information about a network.

Parameters:network_id (str) – The UUID of the network.
Returns:Summary
Return type:dict
get_sample_network(network_id)

Gets the sample network

Parameters:network_id (string) – Network id
Returns:Sample network
Return type:list of dicts in cx format
get_task_by_id(task_id)

Retrieves a task by id

Parameters:task_id (string) – Task id
Returns:Task
Return type:dict
get_user_by_username(username)

Gets the user id by user name

Parameters:username (string) – User name
Returns:User id
Return type:string
get_user_network_summaries(username, offset=0, limit=1000)

Get a list of network summaries for networks owned by specified user. It returns not only the networks that the user owns but also the networks that are shared with them directly.

Parameters:
  • username (str) – the username of the network owner
  • offset (int) – the starting position of the network search
  • limit –
Returns:

list of uuids
Return type:

list
grant_network_to_user_by_username(username, network_id, permission)

Grants permission to network for the given user name

Parameters:
  • username (string) – User name
  • network_id (string) – Network id
  • permission (string) – Network permission
Returns:

Result
Return type:

dict
grant_networks_to_group(groupid, networkids, permission='READ')

Set group permission for a set of networks

Parameters:
  • groupid (string) – Group id
  • networkids (list) – List of network ids
  • permission (string) – Network permission
Returns:

Result
Return type:

dict
grant_networks_to_user(userid, networkids, permission='READ')

Gives read permission to specified networks for the provided user

Parameters:
  • userid (string) – User id
  • networkids (list of strings) – Network ids
  • permission (string (default is READ)) – Network permissions
Returns:

none
Return type:

none
make_network_private(network_id)

Makes the network specified by the network_id private.

Parameters:network_id (str) – The UUID of the network.
Returns:The response.
Return type:response object
make_network_public(network_id)

Makes the network specified by the network_id public.

Parameters:network_id (str) – The UUID of the network.
Returns:The response.
Return type:response object
save_cx_stream_as_new_network(cx_stream, visibility=None)

Create a new network from a CX stream.

Parameters:
  • cx_stream (BytesIO) – IO stream of cx
  • visibility (string) – Sets the visibility (PUBLIC or PRIVATE)
Returns:

Response data
Return type:

string or dict
save_new_network(cx, visibility=None)

Create a new network (cx) on the server

Parameters:
  • cx (list of dicts) – Network cx
  • visibility (string) – Sets the visibility (PUBLIC or PRIVATE)
Returns:

Response data
Return type:

string or dict
search_networks(search_string='', account_name=None, start=0, size=100, include_groups=False)

Search for networks based on the search_text, optionally limited to networks owned by the specified account_name.

Parameters:
  • search_string (str) – The text to search for.
  • account_name (str) – The account to search
  • start (int) – The number of blocks to skip. Usually zero, but may be used to page results.
  • size (int) – The size of the block.
  • include_groups –
Returns:

The response.
Return type:

response object
set_network_properties(network_id, network_properties)

Sets network properties

Parameters:
  • network_id (string) – Network id
  • network_properties (list) – List of NDEx property value pairs
Returns:
Return type:
set_network_system_properties(network_id, network_properties)

Set network system properties

Parameters:
  • network_id (string) – Network id
  • network_properties (dict of NDEx network property value pairs) – Network properties
Returns:

Result
Return type:

dict
set_read_only(network_id, value)

Sets the read only flag on the specified network

Parameters:
  • network_id (string) – Network id
  • value (bool) – Read only value
Returns:

Result
Return type:

dict
update_cx_network(cx_stream, network_id)

Update the network specified by UUID network_id using the CX stream cx_stream.

Parameters:
  • cx_stream – The network stream.
  • network_id (str) – The UUID of the network.
Returns:

The response.
Return type:

response object
update_network_group_permission(groupid, networkid, permission)

Updated group permissions

Parameters:
  • groupid (string) – Group id
  • networkid (string) – Network id
  • permission (string) – Network permission
Returns:

Result
Return type:

dict
update_network_profile(network_id, network_profile)

Updates the network profile Any profile attributes specified will be updated but attributes that are not specified will have no effect - omission of an attribute does not mean deletion of that attribute. The network profile attributes that can be updated by this method are: ‘name’, ‘description’ and ‘version’.

Parameters:
  • network_id (string) – Network id
  • network_profile (dict) – Network profile
Returns:
Return type:
update_network_user_permission(userid, networkid, permission)

Updated network user permission

Parameters:
  • userid (string) – User id
  • networkid (string) – Network id
  • permission (string) – Network permission
Returns:

Result
Return type:

dict