Python-api client

Python-api client

The MOLGENIS python client API allows you to retrieve, create, update and delete entities from within python.

You can install the Python REST Client as a package with pip:

pip install molgenis-py-client

Now you can create a python script. To get started, you should import the Python client, connect to a molgenis server and login:

import molgenis.client
session = molgenis.client.Session("https://molgenis.mydomain.example/api/")
session.login("username","password")

Always put the import and molgenis.Session in your script to make the api work.

Overview example

import molgenis.client
session = molgenis.client.Session("https://molgenis.mydomain.example/api/")
session.login("username","password")
my_table = session.get("package_entityName")
print(my_table)

To get a full overview of all functions in the python client, you can look at the examples on GitHub.

Methods

login

session.login(username,password)

Login to the MOLGENIS REST API

Argument	Description	Required	Default
username	Username for a registered molgenis user	yes
password	Password for the user	yes

logout

session.logout()

Logout from the MOLGENIS REST API and destroy the session.

get_by_id

session.get_by_id("tableId", "rowId")

Retrieves a single entity row from an entity repository.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
id	The value for the idAttribute of the entity	yes
attributes	The list of attributes to retrieve	no	All attributes
expand	The attributes to expand	no	None

get

session.get("package_entityName")

Retrieves entities and returns the result in a dataframe.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
q	Query string in rsql/fiql format (see below)	no	None
start	The index of the first row to retrieve (zero indexed)	no	0
num	The maximum number of rows to return (max 10000)	no	100
attributes	The list of attributes to retrieve	no	All attributes
sortColumn	attributeName of the column to sort on	no	None
sortOrder	The order to sort in	no	None

Supported RSQL/FIQL query operators (see https://github.com/jirutka/rsql-parser)

Operator	Symbol
Logical AND	; or and
Logical OR	, or or
Group	( and )
Equal to	==
Less then	=lt= or <
Less then or equal to	=le= or <=
Greater than	=gt= or >
Greater tha or equal to	=ge= or >=

Argument can be a single value, or multiple values in parenthesis separated by comma. Value that doesn’t contain any reserved character or a white space can be unquoted, other arguments must be enclosed in single or double quotes.

Examples

session.get("celiacsprue")
session.get("celiacsprue", num = 100000, start = 1000)
session.get("celiacsprue", attributes = c("Individual", "celiac_gender"))
session.get("celiacsprue", q = "(celiac_weight>=80 and celiac_height<180) or (celiac_gender==Female)")
session.get("celiacsprue", q = "(celiac_weight>=80;celiac_height<180),(celiac_gender==Female)")

add

session.add('Person', firstName='Jan', lastName='Klaassen')

Creates a new instance of an entity (i.e. a new row of the entity data table) and returns the id.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
files	Dictionary containing file attribute values for the entity row. The dictionary should for each file attribute map the attribute name to a tuple Containing the file name and an input stream.	no	Empty dictionary
data	Dictionary mapping attribute name to non-file attribute value for the entity row, gets merged with the kwargs argument	no	Empty dictionary
**kwargs	Keyword arguments get merged with the data argument	no

Examples

session.add('Person', {'firstName': 'Jan', 'lastName':'Klaassen'})
session.add('Plot', files={'image': ('expression.jpg', open('~/first-plot.jpg','rb')),
        'image2': ('expression-large.jpg', open('/Users/me/second-plot.jpg', 'rb'))},
        data={'name':'IBD-plot'})

update_one

session.update_one("entityType", "id", "attribute", "newValue")

Updates a value of a specified attribute in a specified row in a specified entityType.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
id	The value for the idAttribute of the entity	yes
attr	Attribute to update	yes
value	New value of the attribute	yes

add_all

session.add_all(entity, entities)

Creates new instances of an entity (i.e. adds new rows to the entity data table) and returns the ids.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
entities	List of dictionaries with the attributes of the entities	yes

Example

update = [{'id': '157', 'type': 'gnome', 'year': '1998'},
          {'id': '158', 'type': 'fairy', 'year': '1998'},
          {'id': '159', 'type': 'unicorn', 'year': '1998'}]


session.add_all("demo_sightings", update)

delete

session.delete(entity, id)

Deletes row based on its id.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
id	Id of the entity that should be deleted	yes

delete_list

session.delete_list(entity, entities)

Deletes a number of rows based on a list of id's.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
entities	List of id's of entities that should be deleted	yes

upload_zip

session.upload_zip("pathtozipfile")

This function uploads a zip file based on the EMX format.

Argument	Description	Required	Default
meta_data_zip	A zip file containing an attribute, entities, packages file (tsv/csv) to specify the meta data and optionally data defined in the meta data files	yes

get_entity_meta_data

session.get_entity_meta_data(entity)

Retrieves the metadata for an entity repository.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes

get_attribute_meta_data

session.get_attribute_meta_data(entity, attribute)

Retrieves the metadata for a single attribute of an entity repository.

Argument	Description	Required	Default
entity	Fully qualified name of the entity	yes
attribute	Name of the attribute	yes