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. If the mrn at a given index cannot be found, the result will contain the value None at that index.

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

workspace_id

The id of the workspace in which the patient belongs (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

workspace_id

The id of the workspace in which the patient belongs (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

scorecards

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

Type:

proknow.Patients.PatientScorecards

studies

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

Type:

list

tasks

An instance of the Tasks class for the patient.

Type:

proknow.Patients.Tasks

create_plan(name, image_set_id=None, structure_set_id=None, dose_id=None)

Creates a structure set.

Parameters:

  • name (str) – The name of the structure set (available as the entity description).

  • image_set_id (str, optional) – The id of the image set.

  • structure_set_id (str, optional) – The id of the structure set.

  • dose_id (str, optional) – The id of the dose.

Returns:

The entity summary object representing the new plan.

Return type:

proknow.Patients.EntitySummary

Raises:

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

Example

The following example shows how to create a plan:

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()
image_set = patient.find_entities(modality="CT")[0]
plan = patient.create_plan("My Plan", image_set_id=image_set.id)
create_structure_set(name, image_set_id)

Creates a structure set.

Parameters:

  • name (str) – The name of the structure set (available as the entity description).

  • image_set_id (str) – The id of the image set.

Returns:

The entity summary object representing the new structure set.

Return type:

proknow.Patients.EntitySummary

Raises:

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

Example

The following example shows how to create a 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()
image_set = patient.find_entities(modality="CT")[0]
structure_set = patient.create_structure_set("My Structure Set", image_set.id)
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)
refresh()

Refreshes the patient state.

Raises:

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

Example

The following example shows how to refresh the 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.refresh()
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.

Parameters:

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 example shows 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")

PatientScorecards

class proknow.Patients.PatientScorecards(patients, workspace_id, patient_id)

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

create(name, computed, custom)

Creates a new patient 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 patient scorecard

Return type:

proknow.Patients.PatientScorecardItem

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()
patient.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()
patient.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.PatientScorecardSummary

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 patient scorecard

Return type:

proknow.Patients.PatientScorecardItem

Raises:

Example

If you know the scorecard id, you can get the patient 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()
scorecard = patient.scorecards.get('5c463a6c040068100c7f665acad17ac4')
query()

Queries for patient scorecards.

Returns:

A list of proknow.Patients.PatientScorecardSummary objects, each representing a summarized patient scorecard for the current patient.

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()
for scorecard in patient.scorecards.query():
    print(scorecard.name)

PatientScorecardSummary

class proknow.Patients.PatientScorecardSummary(scorecards, workspace_id, patient_id, scorecard)

This class represents a summary view of a patient scorecard. It’s instantiated by the proknow.Patients.PatientScorecards.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 patient scorecard

Return type:

proknow.Patients.PatientScorecardItem

Raises:

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

Example

The following example shows how to turn a list of PatientScorecardSummary objects into a list of PatientScorecardItem 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()
scorecards = [scorecard.get() for scorecard in patient.scorecards.query()]

PatientScorecardItem

class proknow.Patients.PatientScorecardItem(scorecards, workspace_id, patient_id, scorecard)

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

Tasks

class proknow.Patients.Tasks(patients, workspace_id, patient_id)

This class should be used to interact with the tasks for a patient. It is instantiated for you as an attribute of the proknow.Patients.PatientItem class.

create(body)

Creates a patient task.

Parameters:

body (dict) – The task creation parameters. For information on how to construct this parameter, please check out the Patient Tasks guide.

Raises:

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

Example

The following example shows how to create a task for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234").get()
operands = [{
    "type": "dose",
    "id": dose.id
} for dose in patient.find_entities(type="dose")]
patient.tasks.create({
    "type": "dose_composition",
    "name": "Dose Composition",
    "operation": {
        "type": "addition",
        "operands": operands
    }
})
delete(task_id)

Deletes the patient task.

Parameters:

task_id (str) – The id of the patient task to delete.

Raises:

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

Example

The following example shows how to delete a task for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234").get()
patient.tasks.delete('5c4b4c52a5c058c3d1d98ac194d0200f')
get(task_id)

Gets the patient task.

Parameters:

task_id (str) – The id of the patient task to get.

Raises:

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

Example

The following example shows how to get a task for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234").get()
task = patient.tasks.get('5c4b4c52a5c058c3d1d98ac194d0200f')
query(hidden=False, wait=False)

Queries the patient tasks.

Parameters:

  • hidden (bool, optional) – Whether hidden tasks should be included in the results (defaults=False).

  • wait (bool, optional) – Whether to wait for tasks to reach a resolved state before terminating (default=False).

Raises:

Example

The following example shows how to query tasks for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234").get()
tasks = patient.tasks.query()

TaskSummary

class proknow.Patients.TaskSummary(tasks, workspace_id, patient_id, task)

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

id

The id of the patient (readonly).

Type:

str

data

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

Type:

dict

get()

Gets the complete representation of the patient task.

Returns:

An object representing a patient task.

Return type:

proknow.Patients.TaskItem

Raises:

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

Example

The following example shows how to turn a list of TaskSummary objects into a list of TaskItem objects:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234")
tasks = [task.get() for task in patient.tasks.query()]

TaskItem

class proknow.Patients.TaskItem(tasks, workspace_id, patient_id, task)

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

id

The id of the patient task (readonly).

Type:

str

data

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

Type:

dict

delete()

Deletes the patient task.

Raises:

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

Example

The following example shows how to delete the tasks for a patient:

from proknow import ProKnow

pk = ProKnow('https://example.proknow.com', credentials_file="./credentials.json")
patient = pk.patients.find("Clinical", mrn="1234")
for task in patient.tasks.query():
    task.get().delete()
wait()

Wait for the patient task to be completed

Raises

proknow.Exceptions.TimeoutExceededError: If the timeout was exceeded while waiting for the uploads to complete.

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

description

The entity description.

Type:

str

metadata

The entity metadata.

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.get().delete()
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 entity:

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()
dose_summary = patient.find_entities(type="dose")[0]
dose = dose_summary.get()
meta = dose.get_metadata()
print(meta)
save()

Saves the changes made to an entity.

Raises:

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

Example

The following example shows how to find a dose, update its description, 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()
dose_summary = patient.find_entities(type="dose")[0]
dose = dose_summary.get()
dose.description = "Summed"
dose.save()
set_metadata(metadata)

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

Parameters:

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 “Algorithm” for a dose entity 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()
dose_summary = patient.find_entities(type="dose")[0]
dose = dose_summary.get()
meta = dose.get_metadata()
meta["Algorithm"] = "Monte Carlo"
dose.set_metadata(meta)
dose.save()
update_parent(entity)

Update the parent of the entity.

Parameters:

entity (proknow.Patients.EntitySummary, proknow.Patients.EntityItem, str) – An entity-like object or a entity id to be used to set the new parent of the entity.

Raises:

  • AttributeError – If the provided object is not an entity-like object.

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

Example

Use this example to update the parent of the dose entity to be 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()
dose_summary = patient.find_entities(type="dose")[0]
structure_set_summary = patient.find_entities(type="structure_set")[0]
dose = dose_summary.get()
dose.update_parent(structure_set_summary)

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("./")
get_image_data(index)

Gets the image data for the image at the given index.

Parameters:

index (int) – The index of the image for which to get the data.

Returns:

The image data.

Return type:

bytes

Raises:

Example

This example shows how to get the image data for each image in an image 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="image_set")
image_set = entities[0].get()
slice_count = len(image_set.data["data"]["images"])
slice_data = [image_set.get_image_data(i) for i in range(slice_count)]
refresh()

Refreshes the image set entity.

Raises:

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

Example

This example shows how to refresh an image set entity:

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.refresh()

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

refresh()

Refreshes the structure set entity.

Raises:

  • AttributeError – If attempting to refresh a draft structure set entity.

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

Example

This example shows how to refresh a structure set entity:

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.refresh()
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()
with structure_set.draft() as draft:
    for roi in draft.rois:
        if roi.name == "BODY_2":
            match = roi
            break
    else:
        match = None
    assert match is not None
    match.delete()
    # Uncomment the line below if you wish to commit your changes as a new version
    # draft.approve()

Deleting ROIs during an iteration can cause some items to be missed. To avoid this issue, create a copy of the ROI list for iterating:

for roi in list(draft.rois):
    if roi.name not in ["PTV", "BODY"]:
        roi.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()
with structure_set.draft() as draft:
    for roi in draft.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()
    # Uncomment the line below if you wish to commit your changes as a new version
    # draft.approve()

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()
with structure_set.draft() as draft:
    for roi in draft.rois:
        if roi.name == "PTV":
            match = roi
            break
    else:
        match = None
    assert match is not None
    data = match.get_data()
    data.points = []
    data.save()
    # Uncomment the line below if you wish to commit your changes as a new version
    # draft.approve()

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("./")
get_delivery_information()

Gets the delivery information for the plan.

The delivery information is returned as a dictionary with keys including "equipment", "patient_setups", "fraction_groups", "beams", and "brachy".

Returns:

The plan delivery information.

Return type:

dict

Raises:

Example

This example shows how to get the delivery information for a plan::

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() info = plan.get_delivery_information()

refresh()

Refreshes the plan entity.

Raises:

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

Example

This example shows how to refresh a plan entity:

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.refresh()

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

metrics

An instance of the DoseItemMetrics class for the dose item.

Type:

proknow.Patients.DoseItemMetrics

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("./")
get_analysis()

Gets the analysis data for the dose.

The analysis data consists primarily of DVH data.

Note

For information on how interpret the dose analysis object, see Dose Analysis.

Returns:

The dose analysis data.

Return type:

dict

Raises:

  • AssertionError – If dose analysis cannot be computed because the dose is not associated with a structure set or if the dose analysis has failed.

  • proknow.Exceptions.TimeoutExceededError – If the timeout was exceeded while waiting for the analysis data to become available.

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

Example

This example shows how to get the analysis data for a dose:

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()
analysis = dose.get_analysis()
get_slice_data(index)

Gets the slice data for the dose at the given index.

Parameters:

index (int) – The index of the slice for which to get the data.

Returns:

The slice data.

Return type:

bytes

Raises:

Example

This example shows how to get the slice data for each slice in a dose:

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()
slice_count = len(dose.data["data"]["slices"])
slice_data = [dose.get_slice_data(i) for i in range(slice_count)]
refresh()

Refreshes the dose entity.

Raises:

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

Example

This example shows how to refresh a dose entity:

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.refresh()

DoseItemMetrics

class proknow.Patients.DoseItemMetrics(patients, workspace_id, dose_id)

This class represents the computed metrics for a dose. It’s instantiated by instances of the proknow.Patients.DoseItem class.

add(metrics)

Adds the given dose computed metrics for a dose entity.

Note

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

Parameters:

metrics (list) – A list of computed dose metrics to add.

Raises:

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

Example

This example shows how to add dose metrics for a dose:

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.metrics.add([{
    "type": "DOSE_VOLUME_PERCENT_ROI",
    "roi_name": "PTV",
    "arg_1": 99,
    "arg_2": None,
}, {
    "type": "VOLUME_PERCENT_DOSE_RANGE_ROI",
    "roi_name": "BRAINSTEM",
    "arg_1": 0,
    "arg_2": 10,
}])
query(wait=True)

Queries for dose computed metric results.

In addition to the fields that define a computed metric (see Computed Metrics), each dictionary in the list also contains the fields "status", "code", and "value". The "status" field will be one of the following: "pending", "processing", "completed", "failed". If the "status" is "completed", then "value" will be a number. If the "status" is "failed", then "value" will be None and "code" will contain the failure code for the metric. The failure codes and their meanings are listed below.

  • ENOANA: No associated structure set.

  • ECFANA: DVH calculation failed.

  • ENOROI: The structure could not be found.

  • ENODVH: No DVH data is available for this metric.

  • ENOPLN: No associated plan.

  • EIONAN: Input out of range or result is not defined.

  • CRITER: A critical error occurred while processing this metric.

Parameters:

wait (bool) – Whether to wait for the metrics to reach a terminal state.

Returns:

A list of computed metric results.

Return type:

list

Raises:

Example

This example shows how to query dose metrics for a dose:

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()
metrics = dose.metrics.query()