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
upload_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)
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
-
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: dict
-
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: None
-
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
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: int
- 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: list, string, int or double
-
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: list, string, int or double
-
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: None
-
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_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:
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)[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
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)[source]¶ 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
-
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: None
- 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 provideduuid 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
-
to_cx
()[source]¶ Return the CX corresponding to the network.
Returns: 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
For backwards compatibility mode is set to legacy but there are known bugs in this implementation 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() # returns networkx graph using legacy implementation graph = nice_cx.to_networkx()
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
()[source]¶ 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, user_agent='')[source]¶ - 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.
- user_agent (string) – String to append to User-Agent field sent to NDEx REST service
Returns: The UUID of the network on NDEx.
Return type: str
-
upload_to
(server, username, password, user_agent='')[source]¶ - 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.
- user_agent (string) – String to append to User-Agent field sent to NDEx REST service
Returns: The UUID of the network on NDEx.
Return type: string
-
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
These constants are defined here: VALID_ATTRIBUTE_DATATYPES