Client Interface

Basics

Blackfynn

The client provides an interface to the Blackfynn platform, giving you the ability to retrieve, add, and manipulate data.

Blackfynn.datasets

Return all datasets for user for an organization (current context).

Blackfynn.organizations

Return all organizations for user.

Working with data

Blackfynn.get

Get any DataPackage or Collection object by ID.

Blackfynn.delete

Deletes items from the platform.

Blackfynn.update

Update an item on the platform.

Blackfynn.move

Moves item(s) from their current location to the destination.

Blackfynn Client Interface

class blackfynn.Blackfynn(profile=None, api_token=None, api_secret=None, jwt=None, host=None, streaming_host=None, concepts_host=None, env_override=True, **overrides)[source]

The client provides an interface to the Blackfynn platform, giving you the ability to retrieve, add, and manipulate data.

Parameters
  • profile (str, optional) – Preferred profile to use

  • api_token (str, optional) – Preferred api token to use

  • api_secret (str, optional) – Preferred api secret to use

  • host (str, optional) – Preferred host to use

  • streaming_host (str, optional) – Preferred streaming host to use

  • concepts_host (str, optional) – Preferred concepts service host to use

  • env_override (bool, optional) – Should environment variables override settings

  • **overrides (dict, optional) – Settings to override

Examples

Load the client library and initialize:

from blackfynn import Blackfynn

# note: no API token needed if environment variables are set
bf = Blackfynn()

Retrieve/modify items on the platform:

# get some dataset
ds = bf.get_dataset('my dataset')
print("Dataset {} has ID={}".format(ds.name, ds.id))

# list all first-level items in dataset
for item in ds:
    print("Item: {}".format(item))

# grab some data package
pkg = bf.get("N:package:1234-1234-1234-1234")

# modify a package's name
pkg.name = "New Package Name"

# add some property
pkg.set_property('Room', 'ICU-123')

# sync changes
pkg.update()

Note

To initialize your Blackfynn client without passing any arguments, ensure that your BLACKFYNN_API_TOKEN and BLACKFYNN_API_SECRET environment variables are properly set.

create(thing)[source]

Create a object on the platform.

create_dataset(name, description=None, automatically_process_packages=False)[source]

Create a dataset under the active organization.

Parameters

name (str) – The name of the to-be-created dataset

Returns

The created Dataset object

create_model_template(name=None, description=None, category=None, required=None, properties=None, template=None)[source]

Create a new model template belonging to the current organization.

Parameters
  • template (ModelTemplate) – A ModelTemplate object.

  • OR

  • name (str) – The name of the template

  • description (str, optional) – A description of the template

  • category (str) – The category of the template

  • required ([str], optional) – The names of the required template properties

  • properties (dict OR tuples) – The template properties

Example:

my_template = ModelTemplate(
    schema="http://schema.blackfynn.io/model/draft-01/schema",
    name="Patient",
    description="This is a patient.",
    category="Person",
    properties=dict(
        name=dict(
            type="string",
            description="Name"
        ),
        DOB=dict(
            type="string",
            format="date",
            description="Date of Birth"
        )
    ),
    required=["name"]
bf.create_model_template(my_template)

Example:

bf.create_model_template(
    name="Patient",
    description="This is a patient.",
    category="Person",
    required=["name"],
    properties=[("name", "string"), ("DOB", "date")]
)
Returns

The created ModelTemplate object.

datasets()[source]

Return all datasets for user for an organization (current context).

delete(*things)[source]

Deletes items from the platform.

Parameters

things (list) – ID or object of items to delete

Example:

# delete a package by passing in object
bf.delete(my_package)

# delete a package by ID
bf.delete('N:package:1234-1234-1234-1235')

# delete many things (mix of IDs and objects)
bf.delete(my_package, 'N:collection:1234-1234-1234-1235', another_collection)

Note

When deleting Collection, all child items will also be deleted.

delete_model_template(template_id)[source]

Deletes a model template from the platform.

Parameters

template_id (str) – The ID of the model template object.

get(id, update=True)[source]

Get any DataPackage or Collection object by ID.

Parameters

id (str) – The ID of the Blackfynn object.

Returns

Object of type/subtype DataPackage or Collection.

get_dataset(name_or_id)[source]

Get Dataset by name or ID.

Parameters

name_or_id (str) – the name or the ID of the dataset

Note

When using name, this method gnores case, spaces, hyphens, and underscores such that these are equivelent:

  • “My Dataset”

  • “My-dataset”

  • “mydataset”

  • “my_DataSet”

  • “mYdata SET”

get_model_template(template_id)[source]

Get a model template belonging to the current organization.

Parameters

template_id (str) – The ID of the model template object.

Returns

Object of type ModelTemplate.

get_model_templates()[source]

Get all of the model templates belonging to the current organization.

Returns

A list of objects of type ModelTemplate.

move(destination, *things)[source]

Moves item(s) from their current location to the destination.

Parameters
  • destination (object or str) – The ID of the destination. This must be of type type Collection or None. If destination is None, things will be moved to the top of their containing Dataset

  • things (list) – the IDs or objects to move.

organizations()[source]

Return all organizations for user.

search(query, max_results=10)[source]

Find an object on the platform.

Parameters
  • query (str) – query string to perform search.

  • max_results (int, optional) – the number of results to return

Example:

# find some items belonging to patient123
for result in  bf.search('patient123'):
    print("found:", result)
update(thing)[source]

Update an item on the platform.

Parameters

thing (object or str) – the ID or object to update

Example:

my_eeg = bf.get('N:package:1234-1234-1234-1234')
my_eeg.name = "New EEG Name"
bf.update(my_eeg)

Note

You can also call update directly on objects, for example:

my_eeg.name = "New EEG Name"
my_eeg.update()
validate_model_template(name=None, description=None, category=None, required=None, properties=None, template=None)[source]

Validate a model template schema.

Parameters
  • template (ModelTemplate) – A ModelTemplate object.

  • OR

  • name (str) – The name of the template

  • description (str, optional) – A description of the template

  • category (str) – The category of the template

  • required ([str], optional) – The names of the required template properties

  • properties (dict OR tuples) – The template properties

Example:

my_template = ModelTemplate(
    schema="http://schema.blackfynn.io/model/draft-01/schema",
    name="Patient",
    description="This is a patient.",
    category="Person",
    properties=dict(
        name=dict(
            type="string",
            description="Name"
        ),
        DOB=dict(
            type="string",
            format="date",
            description="Date of Birth"
        )
    ),
    required=["name"]
bf.validate_model_template(my_template)

Example:

bf.validate_model_template(
    name="Patient",
    category="Person",
    properties=[("name", "string"), ("Weight", "number")]
)
Returns

“True” or a list of validation errors

context

The current organizational context of the active client.

profile

The profile of the current active user.