proknow.Patients

Patients

class proknow.Patients.Patients(proknow, requestor)

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

create(workspace, mrn, name, birth_date=None, sex=None)

Creates a new patient.

Parameters:
  • workspace (str) – An id or name of the workspace in which to create the patient.
  • mrn (str) – The MRN of the patient.
  • name (str) – The name of the patient.
  • birth_date (str, optional) – The birth date of the patient. If provided, this should be of the form "YYYY-MM-DD" or None.
  • sex (str, optional) – The sex of the patient. This should be one of "M", "F", "O", or None.
Returns:

A representation of the created patient.
Return type:

proknow.Patients.PatientItem
Raises:

Example

This example shows how to create a patient in the workspace called “Clinical”:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.create("Clinical", "12345", "Becker^Matthew")
delete(workspace_id, patient_id)

Deletes a patient.

Parameters:
  • workspace_id (str) – The id of the workspace to which the patient belongs.
  • patient_id (str) – The id of the patient to delete.
Raises:

Example

If you know the workspace id and patient id, you can delete a patient directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.patients.delete('5c463a6c040040f1efda74db75c1b121', '5c4b4c52a5c058c3d1d98ac194d0200f')
find(workspace, predicate=None, **props)

Finds the first patient that matches the input paramters.

Note

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

Parameters:
  • workspace (str) – An id or name of the workspace in which to query for patients.
  • predicate (func) – A function that is passed a metric as input and which should return a bool indicating whether the metric is a match.
  • **props – A dictionary of keyword arguments that may include any patient attribute. These arguments are considered in turn to find matching patients.
Returns:

A representation of the matching patient.
Return type:

proknow.Patients.PatientSummary
Raises:
get(workspace_id, patient_id)

Gets a patient from the given workspace.

Parameters:
  • workspace_id (str) – The id of the workspace to which the patient belongs.
  • patient_id (str) – The id of the patient to get.
Returns:

an object representing a patient in the organization
Return type:

proknow.Patients.PatientItem
Raises:

Example

If you know the workspace id and patient id, you can get the patient directly using this method:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.patients.get('5c463a6c040040f1efda74db75c1b121', '5c4b4c52a5c058c3d1d98ac194d0200f')
lookup(workspace, mrns)

Looks up a collection of patients matching the given list of MRNs.

Parameters:
  • workspace (str) – An id or name of the workspace in which to query for patients.
  • mrns (list) – A list of MRN string values.
Returns:

A list of proknow.Patients.PatientSummary objects that match the given MRNs.
Return type:

list
Raises:

Example

Use this method to resolve a list of patient MRNs. Just provide the ID as a list in the second argument:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
pk.patients.lookup('Clinical', ['HNC-0522c0009', 'HNC-0522c0013'])
query(workspace, search=None)

Queries for patients.

Parameters:
  • workspace (str) – An id or name of the workspace in which to query for patients.
  • search (str, optional) – If provided, returns only the patients whose MRN or name match the parameter.
Returns:

A list of proknow.Patients.PatientSummary objects, each representing a summarized patient in the given workspace.
Return type:

list
Raises:

Example

This example queries the patients belonging to the Clinical workspace and prints the name of each patient:

from proknow import ProKnow

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

PatientSummary

class proknow.Patients.PatientSummary(patients, workspace_id, patient)

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

id

The id of the patient (readonly).

Type:str
mrn

The patient medical record number or MRN (readonly). In the Proknow interface, this is referred to as the Patient ID.

Type:str
name

The name of the patient (readonly).

Type:str
birth_date

The birth_date of the patient (readonly).

Type:str
sex

The sex of the patient (readonly).

Type:str
data

The summary representation of the 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 PatientSummary objects into a list of PatientItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = [patient.get() for patient in pk.patients.query("Clinical")]
upload(path_or_paths, **kwargs)

Initiates an upload or series of uploads to the API for a patient.

Parameters:
  • path_or_paths (str or list) – A path or list of paths such that each path is a directory of files to upload or a path to a file to upload.
  • **kwargs – Keyword arguments to be passed along to the proknow.Uploads.Uploads.upload() method.
Returns:

An object used to manage a batch of uploads.
Return type:

proknow.Uploads.UploadBatch
Raises:

Example

This examples show how to upload a directory of files to a patient:

from proknow import ProKnow
pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.lookup('Clinical', ['HNC-0522c0009'])[0]
patient.upload("./DICOM")

PatientItem

class proknow.Patients.PatientItem(patients, workspace_id, patient)

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

id

The id of the patient (readonly).

Type:str
data

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

Type:dict
mrn

The MRN of the patient.

Type:str
name

The name of the patient.

Type:str
birth_date

The birth_date of the patient.

Type:str
sex

The sex of the patient.

Type:str
metadata

The metadata of the patient.

Type:dict
studies

A list of proknow.Patients.StudySummary objects for the patient.

Type:list
delete()

Deletes the patient.

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

Example

The following example shows how to find a patient by its MRN and delete it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
patient.delete()
find_entities(predicate=None, **props)

Finds the entities for the patient matching 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 an entity as input and which should return a bool indicating whether the entity is a match.
  • **props – A dictionary of keyword arguments that may include any entity attribute to match. These arguments are considered in turn to find matching entities.
Returns:

A list of matching proknow.Patients.EntitySummary objects.
Return type:

list

Example

Use this example to find the patient entities matching the predicate function (returns all plan and dose entities):

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(lambda entity: entity.data["type"] == "dose" or entity.data["type"] == "plan")

Use this example to find the patient entities matching the predicate function (returns entities with the modality value of “MR”):

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(modality="MR")
get_metadata()

Gets the metadata dictionary and decodes the ids into metrics names.

Returns:The dictionary of custom metric key-value pairs where the keys are the decoded custom metric names.
Return type:dict
Raises:proknow.Exceptions.CustomMetricLookupError – If a custom metric could not be resolved.

Example

Use this example to print the metadata values for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
for key, value in patient.get_metadata():
    print(key + ": " + value)
save()

Saves the changes made to a patient.

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

Example

The following example shows how to find a patient by its MRN, update the name, and save it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
patient.name = "ANON-1234"
patient.save()
set_metadata(metadata)

Sets the metadata dictionary to an encoded version of the given metadata dictionary.

Params:
metadata (dict): A dictionary of custom metric key-value pairs where the keys are the names of the custom metric.
Raises:proknow.Exceptions.CustomMetricLookupError – If a custom metric could not be resolved.

Example

Use this example to set the metadata value for “Genetic Type” for a patient before saving:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
meta = patient.get_metadata()
meta["Genetic Type"] = "Type II"
patient.set_metadata(meta)
patient.save()
upload(path_or_paths, **kwargs)

Initiates an upload or series of uploads to the API for a patient.

Parameters:
  • path_or_paths (str or list) – A path or list of paths such that each path is a directory of files to upload or a path to a file to upload.
  • **kwargs – Keyword arguments to be passed along to the proknow.Uploads.Uploads.upload() method.
Returns:

An object used to manage a batch of uploads.
Return type:

proknow.Uploads.UploadBatch
Raises:

Example

This examples show how to upload a directory of files to a patient:

from proknow import ProKnow
pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup('Clinical', ['HNC-0522c0009'])
patient = patients[0].get()
patient.upload("./DICOM")

StudySummary

class proknow.Patients.StudySummary(patients, workspace_id, patient_id, study)

This class represents a summary view of a study. It’s instantiated by the proknow.Patients.PatientItem() class to represent each of the studies that belong to the patient.

id

The id of the study (readonly).

Type:str
data

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

Type:dict

EntitySummary

class proknow.Patients.EntitySummary(patients, workspace_id, patient_id, entity)

This class represents a summary view of an entity. It’s instantiated by the proknow.Patients.StudySummary() class to represent each of the entities that belong to the study.

id

The id of the entity (readonly).

Type:str
data

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

Type:dict
delete()

Deletes the entity.

Raises:

Example

This examples shows how you can delete the entities within a patient while leaving the patient intact:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(lambda entity: True)
for entity in entities:
    entity.delete()
get()

Gets the entity item for the entity summary type.

Returns:One of (proknow.Patients.ImageSetItem, proknow.Patients.StructureSetItem, proknow.Patients.PlanItem, proknow.Patients.DoseItem) based on the entity summary type.
Raises:proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

Use this example to find all of the patient’s entities and construct a list of the type-specific object types:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = [entity.get() for entity in patient.find_entities(lambda entity: True)]

EntityItem

class proknow.Patients.EntityItem(patients, workspace_id, patient_id, entity)

This class is a base class for specific entity types.

id

The id of the entity (readonly).

Type:str
workspace_id

The id of the workspace (readonly).

Type:str
patient_id

The id of the patient (readonly).

Type:str
data

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

Type:dict
scorecards

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

Type:proknow.Patients.EntityScorecards
delete()

Deletes the entity.

Raises:

Example

This examples shows how you can delete the entities within a patient while leaving the patient intact:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(lambda entity: True)
for entity in entities:
    entity.get().delete()

EntityScorecards

class proknow.Patients.EntityScorecards(patients, workspace_id, entity_id)

This class should be used to interact with entity scorecards. It is instantiated for you as an attribute of the proknow.Patients.EntityItem class.

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

create(name, computed, custom)

Creates a new entity scorecard.

Parameters:
  • name (str) – The scorecard name.
  • computed (list) – The computed metrics.
  • custom (list) – The custom metrics.
Returns:

A representation of the created entity scorecard
Return type:

proknow.Patients.EntityScorecardItem
Raises:

Example

This example creates a new scorecard:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
entity.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:

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")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
entity.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.Patients.EntityScorecardSummary
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 entity scorecard
Return type:

proknow.Patients.EntityScorecardItem
Raises:

Example

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

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
scorecard = entity.scorecards.get('5c463a6c040068100c7f665acad17ac4')
query()

Queries for entity scorecards.

Returns:

A list of proknow.Patients.EntityScorecardSummary objects, each representing a summarized entity scorecard for the current entity.
Return type:

list
Raises:

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")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
for scorecard in entity.scorecards.query():
    print(scorecard.name)

EntityScorecardSummary

class proknow.Patients.EntityScorecardSummary(scorecards, workspace_id, entity_id, scorecard)

This class represents a summary view of an entity scorecard. It’s instantiated by the proknow.Patients.EntityScorecards.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 entity scorecard
Return type:proknow.Patients.EntityScorecardItem
Raises:proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of EntityScorecardSummary objects into a list of EntityScorecardItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
scorecards = [scorecard.get() for scorecard in entity.scorecards.query()]

EntityScorecardItem

class proknow.Patients.EntityScorecardItem(scorecards, workspace_id, entity_id, scorecard)

This class represents an entity scorecard. It’s instantiated by the proknow.Patients.EntityScorecards 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")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
scorecard = entity.scorecards.find(name='My Scorecard').get()
scorecard.delete()
save()

Saves the changes made to a 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, remove the associated custom metrics, and save it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
entity = entities[0].get()
scorecard = entity.scorecards.find(name='My Scorecard').get()
scorecard.custom = []
scorecard.save()

ImageSetItem

class proknow.Patients.ImageSetItem(patients, workspace_id, patient_id, entity)

This class represents a an image set. It’s instantiated by the proknow.Patients.EntitySummary class as a complete representation of an image set entity.

id

The id of the entity (readonly).

Type:str
data

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

Type:dict
download(path)

Download the image set as a directory of images.

Parameters:

path (str) – A path to a directory in which a directory of images should be downloaded.
Returns:

The absolute path to the downloaded image set directory.
Return type:

str
Raises:

Example

This example shows how to download an image set into the current directory:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="image_set")
image_set = entities[0].get()
image_set.download("./")

StructureSetItem

class proknow.Patients.StructureSetItem(patients, workspace_id, patient_id, entity, lock=None, is_editable=False, is_draft=False)

This class represents a structure set. It’s instantiated by the proknow.Patients.EntitySummary class as a complete representation of a structure set entity.

id

The id of the entity (readonly).

Type:str
data

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

Type:dict
rois

A list of proknow.Patients.StructureSetRoiItem items.

Type:list
versions

A object for interacting with the versions of the current structure set.

Type:proknow.Patients.StructureSetVersions
approve(label=None, message=None)

Approves the draft structure set.

Parameters:
  • label (str, optional) – The label for the new structure set version.
  • message (str, optional) – The message for the new structure set version.
Returns:

The newly approved structure set item.
Return type:

proknow.Patients.StructureSetItem
Raises:

Example

This example shows how to approve a draft version of a structure set (with no other changes):

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
with structure_set.draft() as draft:
    draft.approve()
create_roi(name, color, type)

Creates a new ROI as part of the draft structure set.

Parameters:
  • name (str) – The name of the new ROI.
  • color (list) – The color of the new ROI.
  • type (str) – The type of the new ROI (todo: link here).
Returns:

The item created as part of the draft structure set.
Return type:

proknow.Patients.StructureSetRoiItem
Raises:

Example

This example shows how to add a new ROI for PTV:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
with structure_set.draft() as draft:
    draft.create_roi("PTV", [255, 0, 0], "PTV")
discard()

Discuards the draft structure set.

Parameters:
  • name (str) – The name of the new ROI.
  • color (list) – The color of the new ROI.
  • type (str) – The type of the new ROI (todo: link here).
Raises:

Example

This example loads the current draft and discards it:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
with structure_set.draft() as draft:
    draft.discard()
download(path)

Download the current structure set file.

Parameters:
  • path (str) – A path to a directory or file to which the structure set file should be
  • streamed. –
Returns:

The absolute path to the downloaded file.
Return type:

str
Raises:

Example

This example shows how to download a structure set file for a patient to the current directory:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
structure_set.download("./")
draft()

Creates a draft if one does not already exist for the structure set or obtains the lock.

Returns:

A draft structure set item.
Return type:

proknow.Patients.StructureSetItem
Raises:

Example

It is usually best to use with statements to obtain a draft of a structure set, which will allow the SDK to manage lock renewal for you:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
with structure_set.draft() as draft:
    pass # Your code here

Of course, it’s possible to create a draft without using the built-in context management functionality, but be aware that you will have to manage the renewal of structure set draft locks yourself:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
draft = structure_set.draft()
draft.start_renewer()
try:
    # Do something with the draft here...
finally:
    draft.stop_renewer()
    draft.release_lock()
is_draft()

Returns whether the structure set item is a draft.

Returns:True if the structure set item is a draft and False otherwise
Return type:bool
is_editable()

Returns whether the structure set item is editable.

Returns:True if the structure set item is editable and False otherwise
Return type:bool
release_lock()

Releases the lock for the draft structure set version.

Example

Please see above under the proknow.Patients.StructureSetItem.draft() for example use.

start_renewer()

Starts the lock renewer.

Example

Please see above under the proknow.Patients.StructureSetItem.draft() for example use.

stop_renewer()

Stops the lock renewer.

Example

Please see above under the proknow.Patients.StructureSetItem.draft() for example use.

StructureSetRoiItem

class proknow.Patients.StructureSetRoiItem(structure_set, roi)

This class represents a stucture set ROI. It’s instantiated by the proknow.Patients.StructureSetItem class.

id

The id of the ROI (readonly).

Type:str
tag

The ROI tag (readonly).

Type:str
name

The name of the ROI.

Type:str
color

The color of the ROI represented as three numbers corresponding to the red, blue, and green components of the colors.

Type:list
type

The type of the ROI.

Type:str
delete()

Deletes the roi.

Raises:

Example

This example deletes the ROI called BODY_2:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
for roi in structure_set.rois:
    if roi.name == "BODY_2":
        match = roi
        break
else:
    match = None
assert match is not None
match.delete()
get_data()

Gets the data for an ROI (contours, lines, and points).

Raises:proknow.Exceptions.HttpError – If the HTTP request generated an error.
Returns:The ROI data representation.
Return type:proknow.Patients.StructureSetRoiData

Example

This example dumps the contouring data for the structure PTV to file:

from proknow import ProKnow
import json

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
for roi in structure_set.rois:
    if roi.name == "PTV":
        match = roi
        break
else:
    match = None
assert match is not None
data = match.get_data()
with open('ptv_contours.json', 'w') as file:
    json.dumps(data.contours, file)
is_editable()

Returns whether the ROI item is editable.

Returns:True if the ROI item is editable and False otherwise
Return type:bool
save()

Saves the roi.

Raises:

Example

This example saves changes made to the name, color, and type of an ROI called BODY:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
for roi in structure_set.rois:
    if roi.name == "BODY":
        match = roi
        break
else:
    match = None
assert match is not None
match.name = "PATIENT"
match.color = [0, 238, 255]
match.type = "EXTERNAL"
match.save()

StructureSetRoiData

class proknow.Patients.StructureSetRoiData(roi_item, data)

This class represents the data for a stucture set ROI. It’s returned by calls to the proknow.Patients.StructureSetRoiItem.get_data() method.

Note

For information on how to use contour data, please check out the Using Contouring Data guide.

contours

The list of contours for the ROI.

Type:list
lines

The list of lines for the ROI.

Type:list
points

The list of points for the ROI.

Type:list
is_editable()

Returns whether the ROI item is editable.

Returns:True if the ROI item is editable and False otherwise
Return type:bool
save()

Saves the roi data.

Raises:

Example

This example clears the roi point data for a structure called PTV and saves the data:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
for roi in structure_set.rois:
    if roi.name == "PTV":
        match = roi
        break
else:
    match = None
assert match is not None
data = match.get_data()
data.points = []
data.save()

StructureSetVersions

class proknow.Patients.StructureSetVersions(structure_set)

This class should be used to interact with the versions of a structure set. It is instantiated for you by the proknow.Patients.StructureSetItem class.

delete(version_id)

Deletes a structure set version by id.

Parameters:

version_id (str) – The id of the structure set version to delete.
Raises:

Example

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

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
entity.versions.delete('5c463a6c040040f1efda74db75c1b121')
get(version_id)

Gets a structure set item by id.

Parameters:

version_id (str) – The id of the version to get or the string “draft”.
Returns:

A structure set item for the given version.
Return type:

proknow.Patients.StructureSetItem
Raises:

Example

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

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
version = entity.versions.get('5c463a6c040068100c7f665acad17ac4')
query()

Queries for structure set versions.

Returns:

A list of proknow.Patients.StructureSetVersionItem objects.
Return type:

list
Raises:

Example

This example queries the versions and prints the label and message of each version:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
for version in entity.versions.query():
    print("label=" + version.label + "; message=" + message)

StructureSetVersionItem

class proknow.Patients.StructureSetVersionItem(structure_set_versions, workspace_id, structure_set_id, version)

This class represents a version of a structure set. It is instantiated by the proknow.Patients.StructureSetVersions.query() method.

id

The id of the structure set version item (readonly).

Type:str
data

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

Type:dict
status

The status of the version: either “archived” or “approved” (readonly).

Type:str
label

The structure set version label.

Type:str
message

The structure set version label.

Type:str
delete()

Deletes the structure set version.

Raises:

Example

The following example shows how to delete all archived versions of the structure set (i.e., all versions with a status of “archived” instead of “approved” and “draft”):

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
archived = [version for version in entity.versions.query() if version.status == "archived"]
for version in archived:
    version.delete()
download(path)

Download the version of the structure set.

Parameters:
  • path (str) – A path to a directory or file to which the structure set file should be
  • streamed. –
Returns:

The absolute path to the downloaded file.
Return type:

str
Raises:

Example

This example shows how to download the oldest structure set version for a patient as a file to the current directory:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
structure_set = entities[0].get()
structure_set.versions.query()[-1].download("./")
get()

Gets a structure set item by id.

Returns:A structure set item corresponding to the version.
Return type:proknow.Patients.StructureSetItem
Raises:proknow.Exceptions.HttpError – If the HTTP request generated an error.

Example

The following example shows how to turn a list of StructureSetVersionItem objects into a list of StructureSetItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
structure_sets = [version.get() for version in entity.versions.query()]
revert()

Makes the version the approved version of the structure set.

Returns:

A structure set item corresponding to the version.
Return type:

proknow.Patients.StructureSetItem
Raises:

Example

The following example shows how to make the original version of the structure set the approved version:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
original = entity.versions.query()[-1]
original.revert()
save()

Saves the changes made to the version.

Raises:

Example

The following example shows how to update the label and message for the original version of the structure set:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="structure_set")
entity = entities[0].get()
original = entity.versions.query()[-1]
original.label = "original"
original.message = "This is the original, imported version of the structure set."
original.save()

PlanItem

class proknow.Patients.PlanItem(patients, workspace_id, patient_id, entity)

This class represents a plan. It’s instantiated by the proknow.Patients.EntitySummary class as a complete representation of a plan entity.

id

The id of the entity (readonly).

Type:str
data

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

Type:dict
download(path)

Download the plan file.

Parameters:

path (str) – A path to a directory or file to which the plan file should be streamed.
Returns:

The absolute path to the downloaded file.
Return type:

str
Raises:

Example

This example shows how to download a plan file for a patient to the current directory:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="plan")
plan = entities[0].get()
plan.download("./")

DoseItem

class proknow.Patients.DoseItem(patients, workspace_id, patient_id, entity)

This class represents a dose. It’s instantiated by the proknow.Patients.EntitySummary class as a complete representation of a dose entity.

id

The id of the entity (readonly).

Type:str
data

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

Type:dict
download(path)

Downloads the dose file.

Parameters:

path (str) – A path to a directory or file to which the dose file should be streamed.
Returns:

The absolute path to the downloaded file.
Return type:

str
Raises:

Example

This example shows how to download a dose file for a patient to the current directory:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patients = pk.patients.lookup("Clinical", ["HNC-0522c0009"])
patient = patients[0].get()
entities = patient.find_entities(type="dose")
dose = entities[0].get()
dose.download("./")