Ndex2 REST client¶

The Ndex2 class provides methods to interface with the NDEx REST Server API The Ndex2 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 instance.

Example creating anonymous connection:

import ndex2.client
anon_ndex=ndex2.client.Ndex2()

Example creating connection with username and password:

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

class ndex2.client.Ndex2(host=None, username=None, password=None, update_status=False, debug=False, user_agent='', timeout=30)[source]¶

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

Creates a connection to a particular NDEx server.

Parameters:

host (string) – The URL of the server.
username (string) – The username of the NDEx account to use. (Optional)
password (string) – The account password. (Optional)
update_status (bool) – If set to True tells constructor to query service for status
user_agent (string) – String to append to User-Agent header sent with all requests to server
timeout (float or tuple(float, float)) – The timeout in seconds value for requests to server. This value is passed to Request calls Click here for more information

add_networks_to_networkset(set_id, networks)[source]¶

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)[source]¶

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)[source]¶

Deletes the specified network from the server

Parameters:	network_id (string) – Network id retry (int) – Number of times to retry if deleting fails
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:	Error json if there is an error. Blank
Return type:	string

delete_networks_from_networkset(set_id, networks, retry=5)[source]¶

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

delete_networkset(networkset_id)[source]¶

Deletes the network set, requires credentials

Parameters:	networkset_id (str) – networkset UUID id
Raises:	NDExInvalidParameterError – for invalid networkset id parameter NDExUnauthorizedError – If no credentials or user is not authorized NDExNotFoundError – If no networkset with id passed in found NDExError – For any other error with contents of error in message
Returns:	None upon success

get_neighborhood(network_id, search_string, search_depth=1, edge_limit=2500)[source]¶

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)[source]¶

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)[source]¶

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_aspect_as_cx_stream(network_id, aspect_name)[source]¶

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

For a list of aspect names look at Core Aspects section of CX Data Model Documentation

Parameters:

network_id (str) – The UUID of the network.
aspect_name – The aspect NAME.

Returns:

The response.

Return type:

response object

get_network_ids_for_user(username)[source]¶

Get the network uuids owned by the user

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

get_network_set(set_id)[source]¶

Gets the network set information including the list of networks

Deprecated since version 3.2.0: Use get_networkset() instead.

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

get_network_summary(network_id)[source]¶

Gets information about a network.

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

get_networkset(set_id)[source]¶

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_sample_network(network_id)[source]¶

Gets the sample network

Parameters:	network_id (string) – Network id
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:	Sample network
Return type:	list of dicts in cx format

get_task_by_id(task_id)[source]¶

Retrieves a task by id

Parameters:	task_id (string) – Task id
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:	Task
Return type:	dict

get_user_by_username(username)[source]¶

Gets user information as a dict in format:

{'properties': {},
 'isIndividual': True,
 'userName': 'bsmith',
 'isVerified': True,
 'firstName': 'bob',
 'lastName': 'smith',
 'emailAddress': 'bob.smith@ndexbio.org',
 'diskQuota': 10000000000,
 'diskUsed': 3971183103,
 'externalId': 'f2c3a7ef-b0d9-4c61-bf31-4c9fcabe4173',
 'isDeleted': False,
 'modificationTime': 1554410147104,
 'creationTime': 1554410138498
}

Parameters:	username (string) – User name
Returns:	user information as dict
Return type:	dict

get_user_network_summaries(username, offset=0, limit=1000)[source]¶

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)[source]¶

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')[source]¶

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')[source]¶

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)[source]¶

Makes the network specified by the network_id private by invoking set_network_system_properties() with

{'visibility': 'PRIVATE'}

Parameters:	network_id (str) – The UUID of the network.
Raises:	NDExUnauthorizedError – If credentials are invalid or not set requests.exception.HTTPError – If there is some other error
Returns:	empty string upon success
Return type:	str

make_network_public(network_id)[source]¶

Makes the network specified by the network_id public by invoking set_network_system_properties() with

{'visibility': 'PUBLIC'}

Parameters:	network_id (str) – The UUID of the network.
Raises:	NDExUnauthorizedError – If credentials are invalid or not set requests.exception.HTTPError – If there is some other error
Returns:	empty string upon success
Return type:	str

save_cx_stream_as_new_network(cx_stream, visibility=None)[source]¶

Create a new network from a CX stream.

Parameters:	cx_stream (BytesIO) – IO stream of cx visibility (string) – Sets the visibility (PUBLIC or PRIVATE)
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:	Response data
Return type:	string or dict

save_new_network(cx, visibility=None)[source]¶

Create a new network (cx) on the server

Parameters:	cx (list of dicts) – Network cx visibility (string) – Sets the visibility (PUBLIC or PRIVATE)
Raises:	NDExInvalidCXError – For invalid CX data
Returns:	Response data
Return type:	string or dict

search_networks(search_string='', account_name=None, start=0, size=100, include_groups=False)[source]¶

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)[source]¶

Updates properties of network

Starting with version 2.5 of NDEx, any network properties not in the network_properties parameter are left unchanged.

Warning

name, description, version network attributes/properties cannot be updated by this method. Please use update_network_profile() to update these values.

The format of network_properties should be a list() of dict() objects in this format:

The predicateString field above is the network attribute/property name.

The dataType field above must be one of the following types

Regardless of dataType, value should be converted to str() or list() of str()

For more information please visit the underlying REST call documentation

Example to add two network properties (foo, bar):

Parameters:	network_id (str) – Network id network_properties (list or str) – List of NDEx property value pairs aka network properties to set on the network. This can also be a `str()` in JSON format
Raises:	Exception – If network_properties is not a `str()` or `list()` NDExUnauthorizedError – If credentials are invalid or not set requests.HTTPError – If there is an error with the request or if `name, version, description` is set in network_properties as a value to `predicateString`
Returns:	Empty string or `1`
Return type:	str or int

set_network_system_properties(network_id, network_properties, skipvalidation=False)[source]¶

Set network system properties on network with UUID specified by network_id

The network properties should be a dict() or a json string of a dict() in this format:

{'showcase': (boolean True or False),
 'visibility': (str 'PUBLIC' or 'PRIVATE'),
 'index_level': (str  'NONE', 'META', or 'ALL'),
 'readOnly': (boolean True or False)}

Note

Omit any values from dict() that you do NOT want changed

Definition of showcase values:

True - means network will display in her home page for other users and False hides the network for other users. where other users includes anonymous users

Definition of visibility values:

‘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

Definition of index_level values:

‘NONE’ - no index

‘META’ - only index network attributes

‘ALL’ - full index on the network

Definition of readOnly values:

True - means network is only readonly, False is NOT readonly

This method will validate network_properties matches above dict() unless skipvalidation is set to True in which case the code only verifies the network_properties is valid JSON

Parameters:	network_id (str) – Network id network_properties (dict or str) – Network properties as `dict()` or a JSON string of `dict()` adhering to structure above. skipvalidation – If `True`, only verify network_properties can be parsed/converted to valid JSON
Raises:	NDExUnsupportedCallError – If version of NDEx server is < 2 NDExUnauthorizedError – If credentials are invalid or not set NDExInvalidParameterError – If invalid data is set in network_properties parameter requests.exception.HTTPError – If there is some other error
Returns:	empty string upon success
Return type:	str

set_read_only(network_id, value)[source]¶

Sets the read only flag to value on the network specified by network_id

Parameters:	network_id (str) – Network id value (bool) – Must `True` for read only, `False` otherwise
Raises:	NDExUnauthorizedError – If credentials are invalid or not set NDExInvalidParameterError – If non bool is set in valid parameter requests.exception.HTTPError – If there is some other error
Returns:	empty string upon success
Return type:	str

update_cx_network(cx_stream, network_id)[source]¶

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.
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:	The response.
Return type:	response object

update_network_group_permission(groupid, networkid, permission)[source]¶

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)[source]¶

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

{
  "name": "string",
  "description": "string",
  "version": "string",
  "visibility": "string",
  "properties": [
    {
      "subNetworkId": "",
      "predicateString": "string",
      "dataType": "string",
      "value": "string"
    }
  ]
}

Parameters:	network_id (string) – Network id network_profile (dict) – Network profile
Raises:	NDExUnauthorizedError – If credentials are invalid or not set
Returns:
Return type:

update_network_user_permission(userid, networkid, permission)[source]¶

Updated network user permission

Parameters:	userid (string) – User id networkid (string) – Network id permission (string) – Network permission
Returns:	Result
Return type:	dict