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: 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.
- 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: Raises: proknow.Exceptions.HttpError
– If the HTTP request generated an error.
-
get
(collection_id)¶ Gets a collection.
Parameters: collection_id (str) – The id of the collection to get.
Returns: an object representing a collection in the organization
Return type: 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)¶ 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)¶ 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)¶ 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: 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: 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: 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()
-