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, 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)[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.