NDEx2 Python Client

https://img.shields.io/travis/ndexbio/ndex2-client.svg https://img.shields.io/pypi/v/ndex2.svg https://coveralls.io/repos/github/ndexbio/ndex2-client/badge.svg?branch=master Documentation Status

Overview

The NDEx2 Python Client provides methods to access NDEx via the NDEx REST Server API. As well as methods for common operations on networks via the NiceCXNetwork class.

Jupyter Notebook Tutorials

To use these tutorials, clone the ndex-jupyter-notebooks repository to your local machine and start Jupyter Notebooks in the project directory.

For information on installing and using Jupyter Notebooks, go to jupyter.org

Requirements

The NDEx2 Python Client module works best with Python 3.6+ and the latest version of the PIP Python package manager for installation. Click here to download the PIP Python package.

Installation

The NDEx2 Python Client module can be installed from the Python Package Index (PyPI) repository using PIP:

pip install ndex2

If you already have an older version of the ndex2 module installed, you can use this command instead:

pip install --upgrade ndex2

License

See LICENSE.txt

NDEx2 Client Objects

The NDEx2 Client provides an interface to an NDEx server that is managed via a client object class. An NDEx2 Client object can be used to access an NDEx server either anonymously or using a specific user account. For each NDEx server and user account that you want to use in your script or application, you create an NDEx2 Client instance. In this example, a client object is created to access the public NDEx server.

import ndex2.client
anon_ndex=ndex2.client.Ndex2("http://public.ndexbio.org")

A client object using a specific user account can perform operations requiring authentication, such as saving networks to that account.

my_account="your account"
my_password="your password"
my_ndex=ndex2.client.Ndex2("http://public.ndexbio.org", my_account, my_password)

NDEx Client Object Methods:

Status

update_status()
  • Updates the client object status attribute with the status of the NDEx Server.

Users

get_user_by_username(username)
  • Returns a user object corresponding to the provided username
  • Error if this account is not found
  • If the user account has not been verified by the user yet, the returned object will contain no user UUID and the isVerified field will be false.

Network

save_new_network(cx)
  • Creates a new network from cx, a python dict in CX format.
save_cx_stream_as_new_network(cx_stream)
  • Creates a network from the byte stream cx_stream.
update_cx_network(cx_stream, network_id)
  • Updates network specified by network_id with the new content from the byte stream cx_stream.
  • Errors if the network_id does not correspond to an existing network on the NDEx Server which the authenticated user either owns or has WRITE permission.
  • Errors if the cx_stream data is larger than the maximum size allowed by the NDEx server.
delete_network(network_id)
  • Deletes the network specified by network_id.
  • There is no method to undo a deletion, so care should be exercised.
  • The specified network must be owned by the authenticated user.
get_network_summary(network_id)
  • Retrieves a NetworkSummary JSON object from the network specified by network_id and returns it as a Python dict.
  • A NetworkSummary object provides useful information about the network, a mixture of network profile information (properties expressed in special aspects of the network CX), network properties (properties expressed in the networkAttributes aspect of the network CX) and network system properties (properties expressing how the network is stored on the server, not part of the network CX).

Attribute

Description

Type

creationTme

Time at which the network was created

timeStamp

description

Text description of the network, same meaning as dc:description

string

edgeCount

The number of edge objects in the network

integer

errorMessage

If this network is not a valid CX network, this field holds the error message produced by the CX network validator.

string

externalId

UUID of the network

string

isDeleted

True if the network is marked as deleted

boolean

isReadOnly

True if the network is marked as readonly

boolean

isShowCase

True if the network is showcased

boolean

isValid

True if the network is a valid CX network

boolean

modificationTime

Time at which the network was last modified

timeStamp

name

Name or title of the network, not unique, same meaning as dc:title

string

nodeCount

The number of node objects in the network

integer

owner

The userName of the network owner

string

ownerUUID

The UUID of the networks owner

string

properties

List of NDExPropertyValuePair objects: describes properties of the networ

list

subnetworkIds

List of integers which are identifiers of subnetworks

list

uri

URI of the current network

string

version

Format is not controlled but best practice is to use a string conforming to Semantic Versioning

string

visibility

PUBLIC or PRIVATE. PUBLIC means it can be found or read by anyone, including anonymous users. PRIVATE is the default, means that it can only be found or read by users according to their permissions

string

warnings

List of warning messages produced by the CX network validator

list
  • The properties attribute in the above table represents a list of attributes where each attribute is a dictionary with the following fields:

Property Object Field

Description

Type

dataType

Type of the attribute

string

predicateString

Name of the attribute.

string

value

Value of the attribute

string

subNetworkId

Subnetwork Id of the attribute

string
  • Errors if the network is not found or if the authenticated user does not have READ permission for the network.
  • Anonymous users can only access networks with visibility = PUBLIC.
get_network_as_cx_stream(network_id)
  • Returns the network specified by network_id as a CX byte stream.
  • This is performed as a monolithic operation, so it is typically advisable for applications to first use the getNetworkSummary method to check the node and edge counts for a network before retrieving the network.
set_network_system_properties(network_id, network_system_properties)
  • Sets the system properties specified in network_system_properties data for the network specified by network_id.
  • Network System properties describe the network’s status on the NDEx server but are not part of the corresponding CX network object.
  • As of NDEx V2.0 the supported system properties are:
    • readOnly: boolean
    • visibility: PUBLIC or PRIVATE.
    • showcase: boolean. Controls whether the network will display on the homepage of the authenticated user. Returns an error if the user does not have explicit permission to the network.
    • network_system_properties format: {property: value, …}, such as:
      • {“readOnly”: True}
      • {“visibility”: “PUBLIC”}
      • {“showcase”: True}
      • {“readOnly”: True, “visibility”: “PRIVATE”, “showcase”: False}.
make_network_private(network_id)
  • Sets visibility of the network specified by network_id to private.
  • This is a shortcut for setting the visibility of the network to PRIVATE with the set_network_system_properties method:
    • set_network_system_properties(network_id, {“visibility”: “PRIVATE”}).
make_network_public(network_id)
  • Sets visibility of the network specified by network_id to public
  • This is a shortcut for setting the visibility of the network to PUBLIC with the set_network_system_properties method:
    • set_network_system_properties(network_id, {“visibility”: “PUBLIC”}).
set_read_only(network_id, value)
  • Sets the read-only flag of the network specified by network_id to value.
  • The type of value is boolean (True or False).
  • This is a shortcut for setting readOnly for the network by the set_network_system_properties method:
    • set_network_system_properties(network_id, {“readOnly”: True})
    • set_network_system_properties(network_id, {“readOnly”: False}).
update_network_group_permission(group_id, network_id, permission)
  • Updates the permission of a group specified by group_id for the network specified by network_id.
  • The permission is updated to the value specified in the permission parameter, either READ, WRITE, or ADMIN.
  • Errors if the authenticated user making the request does not have WRITE or ADMIN permissions to the specified network.
  • Errors if network_id does not correspond to an existing network.
  • Errors if the operation would leave the network without any user having ADMIN permissions: NDEx does not permit networks to become ‘orphans’ without any owner.
grant_networks_to_group(group_id, network_ids, permission=”READ”)
  • Updates the permission of a group specified by group_id for all the networks specified in network_ids list
  • For each network, the permission is updated to the value specified in the permission parameter. permission parameter is READ, WRITE, or ADMIN; default value is READ.
  • Errors if the authenticated user making the request does not have WRITE or ADMIN permissions to each network.
  • Errors if any of the network_ids does not correspond to an existing network.
  • Errors if it would leave any network without any user having ADMIN permissions: NDEx does not permit networks to become ‘orphans’ without any owner.
update_network_user_permission(user_id, network_id, permission)
  • Updates the permission of the user specified by user_id for the network specified by network_id.
  • The permission is updated to the value specified in the permission parameter. permission parameter is READ, WRITE, or ADMIN.
  • Errors if the authenticated user making the request does not have WRITE or ADMIN permissions to the specified network.
  • Errors if network_id does not correspond to an existing network.
  • Errors if it would leave the network without any user having ADMIN permissions: NDEx does not permit networks to become ‘orphans’ without any owner.
grant_network_to_user_by_username(username, network_id, permission)
  • Updates the permission of a user specified by username for the network specified by network_id.
  • This method is equivalent to getting the user_id via get_user_by_name(username), and then calling update_network_user_permission with that user_id.
grant_networks_to_user(user_id, network_ids, permission=”READ”)
  • Updates the permission of a user specified by user_id for all the networks specified in network_ids list.
update_network_profile(network_id, network_profile)
  • Updates the profile information of the network specified by network_id based on a network_profile object specifying the attributes to update.
  • 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’.
set_network_properties(network_id, network_properties)
  • Updates the NetworkAttributes aspect the network specified by network_id based on the list of NdexPropertyValuePair objects specified in network_properties.
  • This method requires careful use:
    • Many networks in NDEx have no subnetworks and in those cases the subNetworkId attribute of every NdexPropertyValuePair should not be set.
    • Some networks, including some saved from Cytoscape have one subnetwork. In those cases, every NdexPropertyValuePair should have the subNetworkId attribute set to the id of that subNetwork.
    • Other networks originating in Cytoscape Desktop correspond to Cytoscape “collections” and may have multiple subnetworks. Each subnetwork may have NdexPropertyValuePairs associated with it and these will be visible in the Cytoscape network viewer. The collection itself may have NdexPropertyValuePairs associated with it and these are not visible in the Cytoscape network viewer but may be set or read by specific Cytoscape Apps. In these cases, we strongly recommend that you edit these network attributes in Cytoscape rather than via this API unless you are very familiar with the Cytoscape data model.
  • NdexPropertyValuePair object has these attributes:

Attribute

Description

Type

subNetworkId

Optional identifier of the subnetwork to which the property applies.

string

predicateString

Name of the attribute.

string

dataType

Data type of this property. Its value has to be one of the attribute data types that CX supports.

string

value

A string representation of the property value.

string
  • Errors if the authenticated user does not have ADMIN permissions to the specified network.
  • Errors if network_id does not correspond to an existing network.
get_provenance(network_id)
  • Returns the Provenance aspect of the network specified by network_id.
  • See the document NDEx Provenance History for a detailed description of this structure and best practices for its use.
  • Errors if network_id does not correspond to an existing network.
  • The returned value is a Python dict corresponding to a JSON ProvenanceEntity object:
    • A provenance history is a tree structure containing ProvenanceEntity and ProvenanceEvent objects. It is serialized as a JSON structure by the NDEx API.
    • The root of the tree structure is a ProvenanceEntity object representing the current state of the network.
    • Each ProvenanceEntity may have a single ProvenanceEvent object that represents the immediately prior event that produced the ProvenanceEntity. In turn, linked to network of ProvenanceEvent and ProvenanceEntity objects representing the workflow history that produced the current state of the Network.
    • The provenance history records significant events as Networks are copied, modified, or created, incorporating snapshots of information about “ancestor” networks.
    • Attributes in ProvenanceEntity:
      • uri : URI of the resource described by the ProvenanceEntity. This field will not be set in some cases, such as a file upload or an algorithmic event that generates a network without a prior network as input
      • creationEvent : ProvenanceEvent. has semantics of PROV:wasGeneratedBy properties: array of SimplePropertyValuePair objects
    • Attributes in ProvenanceEvent:
      • endedAtTime : timestamp. Has semantics of PROV:endedAtTime
      • startedAtTime : timestamp. Has semantics of PROV:endedAtTime
      • inputs : array of ProvenanceEntity objects. Has semantics of PROV:used.
      • properties: array of SimplePropertyValuePair.
set_provenance(network_id, provenance)
  • Updates the Provenance aspect of the network specified by network_id to be the ProvenanceEntity object specified by provenance argument.
  • The provenance argument is intended to represent the current state and history of the network and to contain a tree-structure of ProvenanceEvent and ProvenanceEntity objects that describe the networks provenance history.
  • Errors if the authenticated user does not have ADMIN permissions to the specified network.
  • Errors if network_id does not correspond to an existing network.

Task

get_task_by_id(task_id)
  • Returns a JSON task object for the task specified by task_id.
  • Errors if no task found or if the authenticated user does not own the specified task.

NiceCX Objects

Nodes

create_node(name, represents=None)

Create a new node in the network, specifying the node’s name and optionally the id of the entity that it represents.

  • name: Name for the node
  • represents: The ID of the entity represented by the node. Best practice is to use IDs from standard namespaces and to define namespace prefixes in the network context.

add_node(node)

Add a node object to the network.

  • node: A node object (nicecxModel.cx.aspects.NodesElement)

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

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

  • node: node object or node id
  • attribute_name: attribute name
  • values: A value or list of values of the attribute
  • type: the datatype of the attribute values, defaults to the python datatype of the values.
  • subnetwork: the id of the subnetwork to which this attribute applies.

get_node_attribute(node, attribute_name, subnetwork=None)

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.

  • node: node object or node id
  • attribute_name: attribute name
  • subnetwork: the id of the subnetwork (if any) to which this attribute applies.

get_node_attribute_objects(node, attribute_name)

Get the attribute objects for a node attribute name, where the node may be specified by its id or passed in as an object. The node attribute objects include datatype and subnetwork information. An example of networks that include subnetworks are Cytoscape collections stored in NDEx.

  • node: node object or node id
  • attribute_name: attribute name

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.

  • node: node object or node id

get_nodes()

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

Edges

create_edge(source, target, interaction)

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

  • source: The source node this edge, either its id or the node object itself.
  • target: The target node this edge, either its id or the node object itself.
  • interaction: The interaction that describes the relationship between the source and target nodes

add_edge(edge)

Add an edge object to the network.

  • edge: An edge object (nicecxModel.cx.aspects.EdgesElement)

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

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

  • name: attribute name
  • values: the values of the attribute
  • type: the datatype of the attribute values, defaults to the python datatype of the values.
  • subnetwork: the id of the subnetwork to which this attribute applies.

get_edge_attribute(edge, attribute_name, subnetwork=None)

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.

  • edge: edge object or edge id
  • attribute_name: attribute name
  • subnetwork: the id of the subnetwork (if any) to which this attribute was applied.

get_edge_attribute_objects(edge, attribute_name)

Get the attribute objects for an edge attribute name, where the edge may be specified by its id or passed in as an object. The edge attribute objects include datatype and subnetwork information. An example of networks that include subnetworks are Cytoscape collections stored in NDEx.

  • edge: node object or node id
  • attribute_name: attribute name

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.

  • edge: edge object or edge id

get_edges()

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

Network

get_name()

Get the network name

set_name(network_name)

Set the network name

getSummary()

Get a network summary

set_network_attribute(name=None, values=None, type=None, subnetwork_id=None)

Set an attribute of the network

  • name: attribute name
  • values: the values of the attribute
  • type: the datatype of the attribute values
  • subnetwork: the id of the subnetwork (if any) to which this attribute applies.

get_network_attribute(attribute_name, subnetwork_id=None)

Get the value of a network attribute

  • attribute_name: attribute name
  • subnetwork: the id of the subnetwork (if any) to which this attribute was applied.

get_network_attribute_objects(attribute_name)

Get the attribute objects for the network. The attribute objects include datatype and subnetwork information. An example of networks that include subnetworks are Cytoscape collections stored in NDEx.

get_network_attributes()

Get the attribute objects of the network.

get_metadata()

  • Get the network metadata

set_metadata()

  • Set the network metadata

getProvenance()

  • Get the network provenance as a Python dictionary having the CX provenance schema.

set_provenance(provenance)

  • Set the network provenance

get_context(context)

Get the @context aspect of the network, the aspect that maps namespace prefixes to their defining URIs

set_context()

Set the @context aspect of the network, the aspect that maps namespace prefixes to their defining URIs

get_opaque_aspect(aspect_name)

Get the elements of the aspect specified by aspect_name (nicecxModel.cx.aspects.AspectElement)

  • aspect_name: the name of the aspect to retrieve.

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. (nicecxModel.cx.aspects.AspectElement)

get_opaque_aspect_names()

  • Get the names of all opaque aspects

I/O

to_cx()

  • Return the CX corresponding to the network.

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

to_networkx()

Return a NetworkX graph based on the network. Elements in the CartesianCoordinates aspect of the network are transformed to the NetworkX pos attribute.

to_pandas_dataframe()

Export the network as a Pandas DataFrame.

Example: my_niceCx.upload_to(uuid=’34f29fd1-884b-11e7-a10d-0ac135e8bacf’, server=’http://test.ndexbio.org’, username=’myusername’, password=’mypassword’)

upload(ndex_server, username, password, update_uuid=None)

Upload the network to the specified NDEx server to the account specified by username and password, return the UUID of the network on NDEx.

Example: my_niceCx.upload_to(‘http://test.ndexbio.org’, ‘myusername’, ‘mypassword’)

  • server: The NDEx server to upload the network to.
  • username: The username of the account to store the network
  • password: The password for the account.
  • update_uuid: Instead of creating a new network, update the network that has this UUID with the content of this NiceCX object.

apply_template(server, username, password, uuid)

Get a network from NDEx, copy its cytoscapeVisualProperties aspect to this network.

  • server: The ndex server host of the network from which the layout will be copied
  • username: Optional username to enable access to a private network
  • password: Optional password to enable access to a private network
  • uuid: The unique identifier of the network from which the layout will be copied

to be undocumented…

**any method that works with CX JSON will be an undocumented function for internal use

addNode(json_obj=None)

Used to add a node to the network.

  • name: Name for the node
  • represents: The representation for the node. This can be used to store the normalized id for the node
  • json_obj: The cx representation of a node

add_edge_element(json_obj=None, edge) Low level function

  • json_obj: The cx representation of an edge

addNetworkAttribute(json_obj=None)