proknow.Collections

Collections

class proknow.Collections.Collections(proknow, requestor)

This class should be used to interact with the collections in a ProKnow organization. It is instantiated for you as an attribute of the proknow.Collections.Collections class.

create(name, description, type, workspaces)

Creates a new collection.

Parameters:

name (str) – The name of the collection.
description (str) – The description of the collection.
type (str) – The type of the collection (either “workspace” or “organization”).
workspaces (list) – A list of workspace ids. For workspace collections, there must be exactly one workspace id in this list.

Returns:

A representation of the created collection.

Return type:

proknow.Collections.CollectionItem

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example creates a new organization collection called “My Collection”:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.collections.create("My Collection", "", "organization", [])

This example creates a new workspace collection called “My Workspace Collection”:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.collections.create("My Workspace Collection", "", "workspace", [
    pk.workspaces.find(name="Clinical").id
])

delete(collection_id)

Deletes a collection.

Parameters:

collection_id (str) – The id of the collection to delete.

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the collection id, you can delete the collection directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.collections.delete('5c463a6c040068100c7f665acad17ac4')

find(workspace=None, predicate=None, **props)

Finds the first collection that matches the input paramters.

Note

For more information on how to use this method, see Using Find Methods.

Parameters:

workspace (str, optional) – An id or name of the workspace in which to query for workspace representations of collections. If a workspace is not provided, only organization collections will be considered. Required if the user does not have organization-level Read Collections permission.
predicate (func) – A function that is passed a collection as input and which should return a bool indicating whether the collection is a match.
**props – A dictionary of keyword arguments that may include any collection attribute. These arguments are considered in turn to find matching collections.

Returns:

A representation of the matching collection.

Return type:

proknow.Collections.CollectionItem

Raises:

proknow.Exceptions.HttpError – If the HTTP request generated an error.

get(collection_id, workspace_id=None)

Gets a collection.

Parameters:

collection_id (str) – The id of the collection to get.
workspace_id (str, optional) – The id of the workspace to use to get the collection. Required if the user does not have organization-level Read Collections permission.

Returns:

An object representing a collection in the organization

Return type:

proknow.Collections.CollectionItem

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the collection id, you can get the collection directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.get('5c463a6c040068100c7f665acad17ac4')

query(workspace=None)

Queries for collections.

Parameters:

workspace (str, optional) – An id or name of the workspace in which to query for workspace representations of collections. If a workspace is not provided, only organization collections will be returned.

Returns:

A list of proknow.Collections.CollectionSummary objects, each representing a summarized collection in the organization.

Return type:

list

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example queries the collections and prints the name of each collection:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
for collection in pk.collections.query():
    print(collection.name)

CollectionSummary

class proknow.Collections.CollectionSummary(collections, collection, workspace_id=None)

This class represents a summary view of a collection. It’s instantiated by the proknow.Collections.Collections.query() method to represent each of the collections returned in a query result.

id

The id of the collection (readonly).

Type:: str

name

The name of the collection (readonly).

Type:: str

description

The description of the collection (readonly).

Type:: str

data

The summary representation of the collection as returned from the API (readonly).

Type:: dict

get()

Gets the complete representation of the collection.

Returns:: An object representing a collection in the organization
Return type:: proknow.Collections.CollectionItem
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of CollectionSummary objects into a list of CollectionItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collections = [collection.get() for collection in pk.collections.query()]

CollectionItem

class proknow.Collections.CollectionItem(collections, collection, workspace_id=None)

This class represents a collection. It’s instantiated by the proknow.Collections.Collections class as a complete representation of a collection.

id

The id of the collection (readonly).

Type:: str

data

The complete representation of the collection as returned from the API (readonly).

Type:: dict

name

The name of the collection.

Type:: str

description

The description of the collection.

Type:: str

patients

An object for interacting with the patients within a collection.

Type:: proknow.Collections.CollectionPatients

scorecards

An object for interacting with the scorecards belonging to the collection.

Type:: proknow.Collections.CollectionScorecards

delete()

Deletes the collection.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a collection by its name and delete it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
collection.delete()

save()

Saves the changes made to a collection.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a collection by its name, edit the description, and save it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
collection.description = "This is my collection."
collection.save()

CollectionPatients

class proknow.Collections.CollectionPatients(collections, collection, workspace_id=None)

This class should be used for interacting with the patients for a collection.

add(workspace, items)

Add patients (with optional representative entities) within a workspace to the collection.

Parameters:

workspace (str) – An id or name of the workspace in which to find the patient(s).
items (list) – A list of dictionary objects containing the key “patient” and, optionally, the key “entity.” The values of these fields must be ids.

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.
proknow.Exceptions.WorkspaceLookupError – If the workspace with the given name or id could not be found.

Example

The following example shows how to add three patients with dose entities to a collection:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name="My Collection").get()
patients = pk.patients.lookup("Clinical", ["1802-2891", "3812-3239", "5800-2495"])
items = []
for summary in patients:
    patient = summary.get()
    dose = patient.find_entities(type="dose")[0]
    items.append({
        "patient": patient.id,
        "entity": dose.id
    })
collection.patients.add("Clinical", items)

query()

Queries for patients belonging to the collection.

Returns:: A list of proknow.Collections.CollectionPatientSummary objects, each representing a summarized patient in the collection.
Return type:: list
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to query for patients in a collection and print each patient ID:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name="My Collection").get()
for patient in collection.patients.query():
    print(patient.data["patient"]["mrn"])

remove(workspace, items)

Remove patients within a workspace from the collection.

Parameters:

workspace (str) – An id or name of the workspace in which to find the patient(s).
items (list) – A list of dictionary objects containing the key “patient.” The value of this field must be an id.

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.
proknow.Exceptions.WorkspaceLookupError – If the workspace with the given name or id could not be found.

Example

The following example shows how to remove three patients from a collection:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name="My Collection").get()
patients = pk.patients.lookup("Clinical", ["1802-2891", "3812-3239", "5800-2495"])
items = [{ "patient": patient.id } for patient in patients]
collection.patients.remove("Clinical", items)

CollectionPatientSummary

class proknow.Collections.CollectionPatientSummary(collections, summary)

This class represents a summary view of a patient.

id

The id of the patient (readonly).

Type:: str

entity_id

The id of the entity if specified (readonly).

Type:: str

data

The summary representation of the collection patient as returned from the API (readonly).

Type:: dict

get()

Gets the complete representation of the patient.

Returns:: An object representing a patient in the organization.
Return type:: proknow.Patients.PatientItem
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of CollectionPatientSummary objects into a list of PatientItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name="My Collection").get()
patients = [patient.get() for patient in collection.patients.query()]

CollectionScorecards

class proknow.Collections.CollectionScorecards(collections, collection)

This class should be used to interact with collection scorecards. It is instantiated for you as an attribute of the proknow.Collections.CollectionItem class.

create(name, computed, custom)

Creates a new collection scorecard.

Note

For information on how to construct computed metrics visit Computed Metrics.

For information on how to define scorecard objectives, see Scorecard Objectives.

Parameters:

name (str) – The scorecard name.
computed (list) – The computed metrics.
custom (list) – The custom metrics.

Returns:

A representation of the created collection scorecard

Return type:

proknow.Collections.CollectionScorecardItem

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example creates a new scorecard:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
collection.scorecards.create("My Scorecard", [{
    "type": "VOLUME",
    "roi_name": "BRAINSTEM",
    "arg_1": None,
    "arg_2": None
}, {
    "type": "VOLUME_CC_DOSE_RANGE_ROI",
    "roi_name": "BRAINSTEM",
    "arg_1": 30,
    "arg_2": 60,
    "objectives": [{
        "label": "IDEAL",
        "color": [18, 191, 0],
        "max": 0
    }, {
        "label": "GOOD",
        "color": [136, 223, 127],
        "max": 3
    }, {
        "label": "ACCEPTABLE",
        "color": [255, 216, 0],
        "max": 6
    }, {
        "label": "MARGINAL",
        "color": [255, 102, 0],
        "max": 9
    }, {
        "label": "UNACCEPTABLE",
        "color": [255, 0, 0]
    }]
}], [{
    "id": pk.custom_metrics.resolve_by_name("Genetic Type").id
}])

delete(scorecard_id)

Deletes a scorecard by id.

Parameters:

scorecard_id (str) – The id of the scorecard to delete.

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the scorecard id, you can delete the scorecard directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
collections.scorecards.delete('5c463a6c040040f1efda74db75c1b121')

find(predicate=None, **props)

Finds the first scorecard that matches the input paramters.

Note

For more information on how to use this method, see Using Find Methods.

Parameters:

predicate (func) – A function that is passed a scorecard as input and which should return a bool indicating whether the scorecard is a match.
**props – A dictionary of keyword arguments that may include any scorecard attribute. These arguments are considered in turn to find matching scorecards.

Returns:

A summary representation of the matching scorecard.

Return type:

proknow.Collections.CollectionScorecardSummary

Raises:

proknow.Exceptions.HttpError – If the HTTP request generated an error.

get(scorecard_id)

Gets a scorecard by id.

Parameters:

scorecard_id (str) – The id of the scorecard to get.

Returns:

A complete representation of the collection scorecard

Return type:

proknow.Collections.CollectionScorecardItem

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

If you know the scorecard id, you can get the collection scorecard directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
scorecard = collection.scorecards.get('5c463a6c040068100c7f665acad17ac4')

query()

Queries for collection scorecards.

Returns:

A list of proknow.Collections.CollectionScorecardSummary objects, each representing a summarized collection scorecard for the current collection.

Return type:

list

Raises:

AssertionError – If the input parameters are invalid.
proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

This example queries the scorecards and prints the name of each scorecard:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
for scorecard in collection.scorecards.query():
    print(scorecard.name)

CollectionScorecardSummary

class proknow.Collections.CollectionScorecardSummary(scorecards, collection, scorecard)

This class represents a summary view of a collection scorecard. It’s instantiated by the proknow.Collections.CollectionScorecards.query() method to represent each of the scorecards returned in a query result.

id

The id of the scorecard (readonly).

Type:: str

name

The name of the scorecard (readonly).

Type:: str

data

The summary representation of the scorecard as returned from the API (readonly).

Type:: dict

get()

Gets the complete representation of the scorecard.

Returns:: A complete representation of the collection scorecard
Return type:: proknow.Collections.CollectionScorecardItem
Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of CollectionScorecardSummary objects into a list of CollectionScorecardItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
scorecards = [scorecard.get() for scorecard in collection.scorecards.query()]

CollectionScorecardItem

class proknow.Collections.CollectionScorecardItem(scorecards, collection, scorecard)

This class represents a collection scorecard. It’s instantiated by the proknow.Collections.CollectionScorecards class as a complete representation of the scorecard.

id

The id of the scorecard (readonly).

Type:: str

data

The complete representation of the scorecard as returned from the API (readonly).

Type:: dict

name

The name of the scorecard.

Type:: str

computed

The computed metrics of the scorecard.

Type:: list

custom

The custom metrics of the scorecard.

Type:: list

delete()

Deletes the scorecard.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a scorecard by its name and delete it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
scorecard = collection.scorecards.find(name='My Scorecard').get()
scorecard.delete()

save()

Saves the changes made to a scorecard.

Note

For information on how to construct computed metrics visit Computed Metrics.

For information on how to define scorecard objectives, see Scorecard Objectives.

Raises:: proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to find a scorecard by its name, remove the associated custom metrics, and save it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
collection = pk.collections.find(name='My Collection').get()
scorecard = collection.scorecards.find(name='My Scorecard').get()
scorecard.custom = []
scorecard.save()