Project Description

# **NDEx2 Client v1.0**

## **Overview**

The NDEx2 Client v1.0 Python module provides methods to access NDEx via the NDEx Server API. It also provides methods for common operations on networks. It includes the NiceCX network object class for convenient NDEx access and as a data model for applications.

The NDEx2 Client 1.0 module requires Python 3.6+ and the latest version of the PIP Python package manager for installation. [Click here](https://pypi.python.org/pypi/pip) to download the PIP Python package.

## **Installing the NDEx2 Client Module**

The NDEx2 Client 1.0 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

## **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.clientanon_ndex=ndex2.client.Ndex("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.Ndex("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).

<table> <tr> <td>Attribute</td> <td>Description</td> <td>Type</td> </tr> <tr> <td>creationTme</td> <td>Time at which the network was created</td> <td>timeStamp</td> </tr> <tr> <td>description</td> <td>Text description of the network, same meaning as dc:description</td> <td>string</td> </tr> <tr> <td>edgeCount</td> <td>The number of edge objects in the network</td> <td>integer</td> </tr> <tr> <td>errorMessage</td> <td>If this network is not a valid CX network, this field holds the error message produced by the CX network validator.</td> <td>string</td> </tr> <tr> <td>externalId</td> <td>UUID of the network</td> <td>string</td> </tr> <tr> <td>isDeleted</td> <td>True if the network is marked as deleted</td> <td>boolean</td> </tr> <tr> <td>isReadOnly</td> <td>True if the network is marked as readonly</td> <td>boolean</td> </tr> <tr> <td>isShowCase</td> <td>True if the network is showcased</td> <td>boolean</td> </tr> <tr> <td>isValid</td> <td>True if the network is a valid CX network</td> <td>boolean</td> </tr> <tr> <td>modificationTime</td> <td>Time at which the network was last modified</td> <td>timeStamp</td> </tr> <tr> <td>name</td> <td>Name or title of the network, not unique, same meaning as dc:title</td> <td>string</td> </tr> <tr> <td>nodeCount</td> <td>The number of node objects in the network</td> <td>integer</td> </tr> <tr> <td>owner</td> <td>The userName of the network owner</td> <td>string</td> </tr> <tr> <td>ownerUUID</td> <td>The UUID of the networks owner</td> <td>string</td> </tr> <tr> <td>properties</td> <td>List of NDExPropertyValuePair objects: describes properties of the networ</td> <td>list</td> </tr> <tr> <td>subnetworkIds</td> <td>List of integers which are identifiers of subnetworks</td> <td>list</td> </tr> <tr> <td>uri</td> <td>URI of the current network</td> <td>string</td> </tr> <tr> <td>version</td> <td>Format is not controlled but best practice is to use a string conforming to Semantic Versioning</td> <td>string</td> </tr> <tr> <td>visibility</td> <td>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</td> <td>string</td> </tr> <tr> <td>warnings</td> <td>List of warning messages produced by the CX network validator</td> <td>list</td> </tr></table>

* * * *

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

* 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.

* 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:

<table> <tr> <td>Attribute</td> <td>Description</td> <td>Type</td> </tr> <tr> <td>subNetworkId</td> <td>Optional identifier of the subnetwork to which the property applies.</td> <td>string</td> </tr> <tr> <td>predicateString</td> <td>Name of the attribute.</td> <td>string</td> </tr> <tr> <td>dataType</td> <td>Data type of this property. Its value has to be one of the attribute data types that CX supports.</td> <td>string</td> </tr> <tr> <td>value</td> <td>A string representation of the property value.</td> <td>string</td> </tr></table>

* * * *

* 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](http://www.home.ndexbio.org/network-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

* 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.

* **DEPRECATED**: the account_name is optional, but has been superseded by the search string field **userAdmin:account_name** If it is provided, the the search will be constrained to networks owned by that account.

* The start and size parameter are optional. The default values are start = 0 and size = 100.

* The optional include_groups argument defaults to false. It enables search to return a network where a group has permission to access the network and the user is a member of the group. if include_groups is true, the search will also return networks based on permissions from the authenticated user’s group memberships.

* The method find_networks is a deprecated alternate name for search_networks.