NiceCXNetwork¶
The NiceCXNetwork
class provides a data model for working with NDEx networks
that are stored in CX format
Note
The term niceCX is CX with no duplicate aspects.
Methods are provided to add nodes, edges, node attributes, edge attributes, etc.
Once a NiceCXNetwork
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.
Methods¶
Example usage of the methods below can be found in the Jupyter notebook links here:
Tutorial Notebook Navigating NiceCXNetwork Notebook
Node methods¶
-
class
ndex2.nice_cx_network.
NiceCXNetwork
(**attr)[source]¶ -
create_node
(node_name=None, node_represents=None)[source]¶ Creates a new node with the corresponding name and represents (external id)
Warning
Version 3.3.1 and prior of this library had a bug that caused this method to behave incorrectly. Please upgrade to 3.3.2 or greater.
Example:
my_node = create_node(node_name='MAPK1, node_represents='1114208')
Parameters: Returns: Node ID
Return type:
-
get_node_attribute
(node, attribute_name)[source]¶ 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:
-
get_node_attribute_value
(node, attribute_name)[source]¶ 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)[source]¶ 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
()[source]¶ 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
-
set_node_attribute
(node, attribute_name, values, type=None, overwrite=False)[source]¶ 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
- overwrite (bool True means to overwrite node attribute named attribute_name) – If True node attribute matching ‘attribute_name’ is removed first otherwise code blindly adds attribute
Returns: None
Return type:
-
Edge methods¶
-
class
ndex2.nice_cx_network.
NiceCXNetwork
(**attr)[source] -
create_edge
(edge_source=None, edge_target=None, edge_interaction=None)[source] Create a new edge in the network by specifying source-interaction-target
Warning
Version 3.3.1 and prior of this library had a bug that caused this method to behave incorrectly. Please upgrade to 3.3.2 or greater.
Example:
my_edge = create_edge(edge_source=my_node, edge_target=my_node2, edge_interaction='up-regulates')
Parameters: - edge_source (int, dict (with
EDGE_ID
property)) – The source node of this edge, either its id or the node object itself. - edge_target (int, dict (with
EDGE_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: - edge_source (int, dict (with
-
get_edge_attribute
(edge, attribute_name)[source] 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:
-
get_edge_attribute_value
(edge, attribute_name)[source] 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:
-
get_edge_attributes
(edge)[source] 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
()[source] 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
-
set_edge_attribute
(edge, attribute_name, values, type=None)[source] 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:
-
Network methods¶
-
class
ndex2.nice_cx_network.
NiceCXNetwork
(**attr)[source] -
get_context
()[source] 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
()[source] Get the network name
Returns: Network name Return type: string
-
get_network_attribute
(attribute_name)[source] Get the value of a network attribute
Parameters: attribute_name (string) – Attribute name Returns: Network attribute object Return type: dict
-
get_network_attribute_names
()[source] Creates a a generator that gets network attribute names.
Returns: attribute name via a generator Return type: string
-
get_opaque_aspect
(aspect_name)[source] 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
-
set_context
(context)[source] Set the @context information of the network. This information maps namespace prefixes to their defining URIs
Example:
from ndex2.nice_cx_network import NiceCXNetwork net = NiceCXNetwork() net.set_context({'pmid': 'https://www.ncbi.nlm.nih.gov/pubmed/'})
Parameters: context (dict or list) – dict where key is name and value is URI or list of those dict objects Raises: NDExError – If context is not of type list
ordict
Returns: None Return type: none
-
set_name
(network_name)[source] 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)[source] Set an attribute of the network
from ndex2.nice_cx_network import NiceCXNetwork net = NiceCXNetwork() net.set_network_attribute(name='networkType', values='Genetic interactions')
Parameters: Returns: None
Return type: none
-
set_opaque_aspect
(aspect_name, aspect_elements)[source] Set the aspect specified by aspect_name to the list of aspect elements. If aspect_elements is None, the aspect is removed.
Changed in version 3.5.0: Fixed bug where passing None in aspect_elements did NOT remove aspect. Code also now raises
NDExError
if input values are invalidfrom ndex2.nice_cx_network import NiceCXNetwork net = NiceCXNetwork() # to set an opaque aspect net.set_opaque_aspect('foo', [{'data': 'val'}]) # to remove an opaque aspect named 'foo' net.set_opaque_aspect('foo', None)
Parameters: Raises: NDExError – If aspect_name is None, or if aspect_elements is not None,
dict
, orlist
Returns: None
Return type: none
-
Miscellaneous methods¶
-
class
ndex2.nice_cx_network.
NiceCXNetwork
(**attr)[source] -
apply_style_from_network
(nicecxnetwork)[source] Applies Cytoscape visual properties from the network passed into this method. The style is pulled from
VISUAL_PROPERTIES
orCY_VISUAL_PROPERTIES
Parameters: nicecxnetwork (
NiceCXNetwork
) – Network to extract style fromRaises: - TypeError – If object passed in is NOT a
NiceCXNetwork
object or if object is None - NDExError – If
NiceCXNetwork
does not have any visual styles
Returns: None
Return type: - TypeError – If object passed in is NOT a
-
apply_template
(server, uuid, username=None, password=None)[source] 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.
Changed in version 3.5.0: Fixed bug where style from template was appended instead of replacing the existing style. In most cases, method now raises
NDExError
and subclasses instead of more genericException
from ndex2.nice_cx_network import NiceCXNetwork nice_cx = NiceCXNetwork() nice_cx.apply_template('public.ndexbio.org', '51247435-1e5f-11e8-b939-0ac135e8bacf')
Parameters: Raises: - NDExError – Raised if server or uuid not set or if metaData is not found in the network specified by uuid or some other server error
- NDExUnauthorizedError – If credentials not authorized to access network specified by uuid
- NDExNotFoundError – If network with uuid not found
Returns: None
Return type:
-
print_summary
()[source] Print a network summary
Returns: Network summary Return type: string
-
to_cx
(log_to_stdout=True)[source] Return the CX corresponding to the network.
Changed in version 3.5.0: Added log_to_stdout param which lets caller silence print statement Generating CX
Parameters: log_to_stdout (bool) – If True
then code will output to standard out Generating CXReturns: CX representation of the network Return type: CX (list of dict aspects)
-
to_cx_stream
()[source] 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
(mode='legacy')[source] Returns a NetworkX
Graph()
object or one of its subclasses based on the network. The mode parameter dictates how the translation occurs.This method currently supports the following mode values:
Warning
legacy mode has known bugs when networkx 2.0+ or greater is installed.
See the description on legacy mode below for more information.
Modes:
legacy:
If mode set to legacy then this method will behave as it has for all versions of NDEx2 Python Client 3.1.0 and earlier which varies depending on version of networkx installed as described here:
For networkx 2.0 and greater: (see
LegacyNetworkXVersionTwoPlusFactory
)For older versions of networkx the following class is used with the legacymode parameter set to True: (see
DefaultNetworkXFactory
)default:
If mode is default or None then this method uses
DefaultNetworkXFactory
regardless of networkx installed with legacymode set to FalseNote
default
mode is the preferred mode to useExamples:
# returns networkx graph using improved converter graph = nice_cx.to_networkx(mode='default') # returns networkx graph using legacy implementation graph = nice_cx.to_networkx(mode='legacy)
Parameters: mode (string) – Since translation to networkx can be done in many ways this mode lets the caller dictate the method. Raises: NDExError – If mode is not None, ‘legacy’, or ‘default’ Returns: Networkx graph Return type: networkx.Graph
ornetworkx.MultiGraph
-
to_pandas_dataframe
(dataconverter=<ndex2.util.PandasDataConverter object>, include_attributes=False)[source] Network edges exported as a
pandas.DataFrame
Changed in version 3.5.0: Added include_attributes and dataconverter parameters
The following columns will be added to the
pandas.DataFrame
:- source - Name of edge source node
- interaction - Interaction between source and target node
- target - Name of edge target node
If include_attributes parameter is set to
True
then:All edge attributes will be also added as separate columns with same name.
Attributes on source node will be added as a columns with
source_
prefixed to name.Attributes on target node will be added as columns with
target_
prefixed to name.Note
Values will converted based on CX data types. See
PandasDataConverter
for information on how conversion is performedfrom ndex2.nice_cx_network import NiceCXNetwork net = NiceCXNetwork() node_one = net.create_node('node1') node_two = net.create_node('node2') net.set_node_attribute(node_one, 'weight', 0.5, type='double') net.set_node_attribute(node_two, 'weight', 0.2, type='double') edge_one = net.create_edge(edge_source=node_one, edge_target=node_two, edge_interaction='binds') net.set_edge_attribute(edge_one, 'edgelabel', 'an edge') df = net.to_pandas_dataframe(include_attributes=True) # df is now a pandas dataframe print(df.head())
Output from above code block:
source interaction target edgelabel target_weight source_weight 0 node1 binds node2 an edge 0.2 0.5
Note
This method only processes nodes, edges, node attributes and edge attributes, but not network attributes or other aspects
Parameters: - dataconverter (
DataConverter
) – Object that converts CX data values to native data types. Default isPandasDataConverter
- include_attributes (bool) – If True then edge attributes are added to
pandas.DataFrame
, otherwise only source, target, and interaction are added
Raises: NDExInvalidParameterError – If include_attributes is not
None
or abool
Returns: Edge table with attributes
Return type:
-
update_to
(uuid, server=None, username=None, password=None, user_agent='', client=None)[source] Replace the network on NDEx server with matching NDEx uuid with this network.
Changed in version 3.4.0: This method was switched to named arguments and the server and account credentials can be passed in one of two ways.
Option 1) Set username and password parameters.
Option 2) Set client parameter with valid
Ndex2
objectNote
If client parameter is set, username, password, and server parameters are ignored.
Example:
import ndex2 nice_cx = ndex2.nice_cx_network.NiceCXNetwork() nice_cx.create_node('foo') # using production NDEx server nice_cx.update_to('2ec87c51-c349-11e8-90ac-525400c25d22', username=user_var, password=password_var) # if one needs to use alternate NDEx server nice_cx.update_to('2ec87c51-c349-11e8-90ac-525400c25d22', server='public.ndexbio.org', username=username_var, password=password_var) # Option 2, create Ndex2 client object ndex_client = ndex2.client.Ndex2(username=username_var, password=password_var) # using NDEx client object for connection nice_cx.update_to('2ec87c51-c349-11e8-90ac-525400c25d22', client=ndex_client)
Parameters: - uuid (str) – UUID of the network on NDEx.
- server (str) – The NDEx server to upload the network to. Leaving unset or None will use production.
- username (str) – The username of the account to store the network.
- password (str) – The password for the account.
- user_agent (str) – String to append to User-Agent field sent to NDEx REST service
- client (
Ndex2
) – NDEx2 object with valid credentials. If set server, username, and password parameters will be ignored.
Returns: Empty string
Return type:
-
upload_to
(server=None, username=None, password=None, user_agent='', client=None)[source] Upload this network as a new network on NDEx server.
Changed in version 3.4.0: This method was switched to named arguments and the server and account credentials can be passed in one of two ways.
Option 1) Set username and password parameters.
Option 2) Set client parameter with valid
Ndex2
objectNote
If client parameter is set, username, password, and server parameters are ignored
Example:
import ndex2 nice_cx = ndex2.nice_cx_network.NiceCXNetwork() nice_cx.create_node('foo') # using production NDEx server nice_cx.update_to(username=user_var, password=password_var) # if one needs to use alternate NDEx server nice_cx.update_to(server='public.ndexbio.org', username=username_var, password=password_var) # Option 2, create Ndex2 client object ndex_client = ndex2.client.Ndex2(username=username_var, password=password_var) # using NDEx client object for connection nice_cx.update_to(client=ndex_client)
Parameters: - server (str) – The NDEx server to upload the network to. Leaving unset or None will use production
- username (str) – The username of the account to store the network.
- password (str) – The password for the account.
- user_agent (str) – String to append to User-Agent field sent to NDEx REST service
- client (
Ndex2
) – NDEx2 object with valid credentials. If set server, username, and password parameters will be ignored.
Returns: The UUID of the network on NDEx.
Return type:
-
Supported data types¶
The following CX Data Types are supported in methods that accept type
Example:
import ndex2 net = ndex2.nice_cx_network.NiceCXNetwork() node_id = net.create_node('hi') net.set_node_attribute(node_id, 'somevalue', 0.5, type='double')
- string
- double
- boolean
- integer
- long
- list_of_string
- list_of_double
- list_of_boolean
- list_of_integer
- list_of_long
These constants are defined here: VALID_ATTRIBUTE_DATATYPES