pma_python package

Submodules

PMA module

_pma_clear_url_cache()

_pma_http_get(url, headers, verify=True)

_pma_join(*s)

_pma_q(arg)

_pma_set_debug_flag(flag): Determine whether pma_python runs in debugging mode or not. When in debugging mode (flag = true), extra output is produced when certain conditions in the code are not met

get_supported_formats(pandas=False, verify=True): Get an up-to-date list of all supported file formats on the Pathomation software platform

Core module

class UploadChunksIterator(file: BufferedReader, filename, total_size: int, callback, chunk_size: int = 16384): Bases: object

_pma_api_url(sessionID=None): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_first_session_id(): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_is_lite(pmacoreURL='http://localhost:54001/', verify=True): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_merge_dict_values(dicts): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_query_url(sessionID=None): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_session_id(sessionID=None): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

_pma_upload_amazon_callback(bytes_read, total_size, previous, filename)

_pma_upload_callback(monitor, filename)

_pma_url(sessionID=None): Internal methods prefixed with _pma_ are not supposed to be invoked by consumers directly

add_annotation(slideRef, classification, notes, ann, color='#000000', layerID=0, sessionID=None, verify=True)

Adds an annotation to a slide with the specified parameters

Parameters

slideRef (str) – The slide path to add annotation to
classification (str) – A string representing the class of this annotation (tumor, necrosis etc)
notes (str) – A string for free text notes to be associated with this annotation
ann – A Well-Known Text (WKT) representation of the geometry of this annotation; can be a dictionary as well
color (str, optional) – An HTML color, defaults to “#000000”
layerID (int, optional) – The layer id to attach this annotation to, defaults to 0
sessionID (str, optional) – The PMA.core session id, defaults to None for autodetection

Raises

ValueError – If the server response is not in a known format

Returns

JSON object containing the annotation ID

Return type

int

add_annotations(slideRef, classification, notes, anns, color='#000000', layerID=0, sessionID=None, verify=True)

Adds multiple annotations to a slide with the specified parameters

Parameters

slideRef (str) – The slide path to add annotation to
classification (str) – A string representing the class of this annotation (tumor, necrosis etc)
notes (str) – A string for free text notes to be associated with this annotations. If param Notes is empty the notes parameter of the annotations object will be used
anns (list) – A list of Well-Known Text (WKT) representation of the geometry of this annotation
color (str, optional) – An HTML color, defaults to “#000000”; you can specify a separate color for each annotation individually as well
layerID (int, optional) – The layer id to attach this annotation to, defaults to 0
sessionID (str, optional) – The PMA.core session id, defaults to None for autodetection
verify (boolean, optional) – confirm whether TLS connection has to be verified

Raises

ValueError – If the server response is not in a known format

Returns

An integer representing the annotation id

Return type

int

In case if you want to have different notes per annotation the notes parameter has to be empty and the annotation dictionary should contain a notes key: value pair.

analyse_corresponding_root_directories(sessionIDs): Return a pandas DataFrame that indicates which root-directories exist on which PMA.core instances

analyse_corresponding_slides(sessionPathDict, recursive=False, includeFingerprint=False)

Return a pandas DataFrame that indicates which slides exist on which PMA.core instances :param dict sessionPathDict: a dictionary that looks e.g. like

{DevSessionID: rootDirAndPath1, ProdSessionID: rootDirAndPath2 }

Parameters: recursive (bool) – indicates whether the method should look in sub-directories or not

clear_all_annotations(slideRef, sessionID=None)

clear_annotations(slideRef, layerID, sessionID=None, verify=True)

connect(pmacoreURL='http://localhost:54001/', pmacoreUsername='', pmacorePassword='', verify=True): Attempt to connect to PMA.core instance; success results in a SessionID

disconnect(sessionID=None): Attempt to disconnect from a PMA.core instance

download(slideRef, save_directory=None, sessionID=None, verify=True): Downloads a slide from a PMA.core server. :param str slideRef: The virtual path to the slide :param str save_directory: The local directory to save the downloaded files to :param str sessionID: The sessionID to authenticate to the pma.core server

dummy_annotation(): Returns a dictionary with the right keys and default values filled out already to be used as input for add_annotation() and add_annotations

export_annotations(slideRef, annotation_source_format=[0], annotation_target_format=3, sessionID=None, verify=True): Retrieve the annotations for slide slideRef

get_annotation_distance(slideRef, layerID, annotationID, sessionID=None, verify=True)

get_annotation_surface_area(slideRef, layerID, annotationID, sessionID=None, verify=True)

get_annotations(slideRef, sessionID=None, verify=True): Retrieve the annotations for slide slideRef

get_api_verion_string(pmacoreURL='http://localhost:54001/'): Returns the API version as a formatted string, rather than a list

get_api_version(pmacoreURL='http://localhost:54001/', verify=True): Retrieves the API version exposed by the underlying PMA.core (no authentication or sessionID needed for this)

get_available_forms(slideRef=None, sessionID=None, verify=True): See what forms are available to fill out, either system-wide (leave slideref to None), or for a particular slide

get_barcode_image(slideRef, width=None, height=None, sessionID=None, verify=True): Get the barcode (alias for “label”) image for a slide

get_barcode_text(slideRef, sessionID=None, verify=True): Get the text encoded by the barcode (if there IS a barcode on the slide to begin with)

get_barcode_url(slideRef, width=None, height=None, sessionID=None): Get the URL that points to the barcode (alias for “label”) for a slide

get_build_revision(pmacoreURL='http://localhost:54001/', verify=True): Get build revision from PMA.core instance running at pmacoreURL. Return None if PMA.core not found running at pmacoreURL endpoint

get_directories(startDir, sessionID=None, recursive=False, verify=True): Return an array of sub-directories available to sessionID in the startDir directory

get_files_for_slide(slideRef, sessionID=None, verify=True): Obtain all files actually associated with a specific slide This is most relevant with slides that are defined by multiple files, like MRXS or VSI

get_fingerprint(slideRef, sessionID=None, verify=True): Get the fingerprint for a specific slide

get_first_non_empty_directory(startDir=None, sessionID=None)

Traversing a folder hierarchy for find any non-empty data (sample slides) is a stupid repetitive task: This method makes it easy to do this. When you need any sample slides on any PMA.core instance, use this method to find any folder that has some data in it

get_label_image(slideRef, width=None, height=None, sessionID=None): Get the label image for a slide

get_label_url(slideRef, width=None, height=None, sessionID=None): Get the URL that points to the label for a slide

get_last_modified_date(slideRef, sessionID=None)

get_macro_image(slideRef, width=None, height=None, sessionID=None, verify=True): Get the macro image for a slide

get_macro_url(slideRef, width=None, height=None, sessionID=None): Get the URL that points to the macro image (thumbnail + label) for a slide

get_magnification(slideRef, zoomlevel=None, exact=False, sessionID=None): Get the magnification represented at a certain zoomlevel

get_max_zoomlevel(slideRef, sessionID=None): Determine the maximum zoomlevel that still represents an optical magnification

get_number_of_channels(slideRef, sessionID=None): Number of fluorescent channels for a slide (when slide is brightfield, return is always 1)

get_number_of_layers(slideRef, sessionID=None): Number of (z-stacked) layers for a slide

get_number_of_tiles(slideRef, zoomlevel=None, sessionID=None): Determine the number of tiles needed to reconstitute a slide at a given zoomlevel

get_number_of_z_stack_layers(slideRef, sessionID=None): Number of z-stack layers for a slide

get_physical_dimensions(slideRef, sessionID=None): Determine the physical dimensions of the sample represented by the slide. This is independent of the zoomlevel: the physical properties don’t change because the magnification changes

get_pixel_dimensions(slideRef, zoomlevel=None, sessionID=None): Get the total dimensions of a slide image at a given zoomlevel

get_pixels_per_micrometer(slideRef, zoomlevel=None, sessionID=None): Retrieve the physical dimension in terms of pixels per micrometer. When zoomlevel is left to its default value of None, dimensions at the highest zoomlevel are returned (in effect returning the “native” resolution at which the slide was registered)

get_region(slideRef, x=0, y=0, width=0, height=0, scale=1, zstack=0, sessionID=None, format='jpg', quality=100, rotation=0, contrast=None, brightness=None, postGamma=None, dpi=300, flipVertical=False, flipHorizontal=False, annotationsLayerType=None, drawFilename=0, downloadInsteadOfDisplay=False, drawScaleBar=False, gamma=[], channelClipping=[], verify=True): Gets a region of the slide at the specified scale Format can be ‘jpg’ or ‘png’ Quality is an integer value and varies from 0 (as much compression as possible; not recommended) to 100 (100%, no compression) x,y,width,height is the region to get rotation is the rotation in degrees of the slide to get

get_root_directories(sessionID=None, verify=True): Return an array of root-directories available to sessionID

get_slide_file_extension(slideRef): Determine the file extension for this slide

get_slide_file_name(slideRef): Determine the file name (with extension) for this slide

get_slide_info(slideRef, sessionID=None, verify=True): Return raw image information in the form of nested dictionaries

get_slides(startDir, sessionID=None, recursive=False, verify=True)

Return an array of slides available to sessionID in the startDir directory The recursive argument can be either of boolean or of integer type.

:param recursive : If recursive is False (boolean) or 0 (integer), no recursion takes place If recursive is True (boolean), then the folder structure will be traversed recursively down to the deepest level But setting recursive to True is actually not recommended, as you may not know how far down a folder structure goes (or just be plain wrong assuming it’s shallow). A better approach therefore is to set recursive to an integer value that indicates how many levels deep the parsing should go at most. Setting recursive to 1 means that only the subfolders of startDir will be included; Setting recursive to 2 means that the subfolders AND the subfolders of these subfolders will be included. Setting recursive to 3 means that the subfolders AND the subfolders of these subfolders AND the subfolders of the subfolders of these subfolders will be included. Etcetera

get_submitted_form_data(slideRef, sessionID=None, verify=True): Get all submitted form data associated with a specific slide

get_submitted_forms(slideRef, sessionID=None, verify=True): Find out what forms where submitted for a specific slide

get_thumbnail_image(slideRef, width=None, height=None, sessionID=None, verify=True): Get the thumbnail image for a slide

get_thumbnail_url(slideRef, width=None, height=None, sessionID=None): Get the URL that points to the thumbnail for a slide

get_tile(slideRef, x=0, y=0, zoomlevel=None, zstack=0, sessionID=None, format='jpg', quality=100, verify=True): Get a single tile at position (x, y) Format can be ‘jpg’ or ‘png’ Quality is an integer value and varies from 0 (as much compression as possible; not recommended) to 100 (100%, no compression)

get_tile_size(sessionID=None): Retrieve the standard tile size set by the PMA.core instance linked to the sessionID

get_tile_url(slideRef, x=0, y=0, zoomlevel=None, zstack=0, sessionID=None, format='jpg', quality=100, verify=True): Get a single tile at position (x, y) Format can be ‘jpg’ or ‘png’ Quality is an integer value and varies from 0 (as much compression as possible; not recommended) to 100 (100%, no compression)

get_tiles(slideRef, fromX=0, fromY=0, toX=None, toY=None, zoomlevel=None, zstack=0, sessionID=None, format='jpg', quality=100): Get all tiles with a (fromX, fromY, toX, toY) rectangle. Navigate left to right, top to bottom Format can be ‘jpg’ or ‘png’ Quality is an integer value and varies from 0 (as much compression as possible; not recommended) to 100 (100%, no compression)

get_uid(slideRef, sessionID=None, verify=True): Get the UID for a specific slide

get_version_info(pmacoreURL='http://localhost:54001/', verify=True): Get version info from PMA.core instance running at pmacoreURL. Return None if PMA.core not found running at pmacoreURL endpoint

get_zoomlevels_dict(slideRef, sessionID=None, min_number_of_tiles=0)

Obtain a dictionary with the number of tiles per zoomlevel. Information is returned as (x, y, n) tuples per zoomlevel, with

x = number of horizontal tiles, y = number of vertical tiles, n = total number of tiles at specified zoomlevel (x * y)

Use min_number_of_tiles argument to specify that you’re only interested in zoomlevels that include at lease a given number of tiles

get_zoomlevels_list(slideRef, sessionID=None, min_number_of_tiles=0): Obtain a list with all zoomlevels, starting with 0 and up to and including max_zoomlevel Use min_number_of_tiles argument to specify that you’re only interested in zoomlevels that include at lease a given number of tiles

is_fluorescent(slideRef, sessionID=None): Determine whether a slide is a fluorescent image or not

is_lite(pmacoreURL='http://localhost:54001/'): Checks to see if PMA.core.lite (server component of PMA.start) is running at a given endpoint. if pmacoreURL is omitted, default check is to see if PMA.start is effectively running at localhost (defined by _pma_pmacoreliteURL).Note that PMA.start may not be running, while it is actually installed. This method doesn’t detect whether PMA.start is installed; merely whether it’s running! if pmacoreURL is specified, then the method checks if there’s an instance of PMA.start (results in True), PMA.core (results in False) or nothing (at least not a Pathomation software platform component) at all (results in None)

is_multi_layer(slideRef, sessionID=None): Determine whether a slide contains multiple (stacked) layers or not

is_z_stack(slideRef, sessionID=None): Determine whether a slide is a z-stack or not

prepare_form_dictionary(formID, sessionID=None, verify=True): Prepare a form-dictionary that can be used later on to submit new form data for a slide

register_session_id(session_id, pma_core_url): Registers a session ID with it’s corresponding server URL

search_slides(startDir, pattern, sessionID=None, verify=True)

sessions(): Return an overview of all the sessions that PMA.python currently holds in memory

set_debug_flag(flag): Determine whether Core module runs in debugging mode or not. When in debugging mode (flag = true), extra output is produced when certain conditions in the code are not met

show_slide(slideRef, sessionID=None): Launch the default webbrowser and load a web-based viewer for the slide

submit_form_data(slideRef, formID, formDict, sessionID=None): Not implemented yet

upload(local_source_slide, target_folder, target_pma_core_sessionID, callback=None, verify=True): Uploads a slide to a PMA.core server. Requires a PMA.start installation :param str local_source_slide: The local PMA.start relative file to upload :param str target_folder: The root directory and path to upload to the PMA.core server :param str target_pma_core_sessionID: A valid session id for a PMA.core server :param function|boolean callback: If True a default progress will be printed.

If a function is passed it will be called for progress on each file upload. The function has the following signature:

callback(bytes_read, bytes_length, filename)

who_am_i(sessionID=None): Getting information about your Session

Control module

_pma_format_project_embedded_training_sessions_properly(original_project_sessions): Helper method to convert a list of sessions with default arguments into a summarized dictionary

_pma_format_training_session_properly(sess): Helper method to convert a JSON representation of a PMA.control training session to a proper Python-esque structure

_pma_get_case_collection_training_session_id(pmacontrolURL, pmacontrolTrainingSessionID, pmacontrolCaseCollectionID, pmacoreSessionID)

_pma_get_case_collections(pmacontrolURL, pmacoreSessionID): Retrieve all the data for all the defined case collections in PMA.control (RAW JSON data; not suited for human consumption)

_pma_get_projects(pmacontrolURL, pmacoreSessionID): Retrieve all projects and their data in PMA.control (RAW JSON data; not suited for human consumption)

_pma_get_training_sessions(pmacontrolURL, pmacoreSessionID): Retrieve a list of currently defined training sessions in PMA.control.

get_all_participants(pmacontrolURL, pmacoreSessionID): Get a list of all participants registered across all sessions

get_case_collection(pmacontrolURL, pmacontrolCaseCollectionID, pmacoreSessionID): Retrieve case collection details

get_case_collection_titles(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve case collections (possibly filtered by project ID), titles only

get_case_collection_titles_dict(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve case collections (possibly filtered by project ID), return a dictionary of case collection IDs and titles

get_case_collections(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve case collection details that belong to a specific project

get_cases_for_case_collection(pmacontrolURL, pmacontrolCaseCollectionID, pmacoreSessionID): Retrieve cases for a specific collection

get_project(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve project details

get_project_by_case_collection_id(pmacontrolURL, pmacontrolCaseCollectionID, pmacoreSessionID): Retrieve case collection based on the case ID

get_project_by_case_id(pmacontrolURL, pmacontrolCaseID, pmacoreSessionID): Retrieve case collection based on the case ID

get_project_titles(pmacontrolURL, pmacoreSessionID): Retrieve projects, return ONLY the titles

get_project_titles_dict(pmacontrolURL, pmacoreSessionID): Retrieve projects, return a dictionary of project-IDs and titles

get_projects(pmacontrolURL, pmacoreSessionID): Retrieve project details for all projects

get_training_session(pmacontrolURL, pmacontrolTrainingSessionID, pmacoreSessionID): Return the first (training) session with ID = pmacontrolTrainingSessionID

get_training_session_participants(pmacontrolURL, pmacontrolTrainingSessionID, pmacoreSessionID): Extract the participants in a particular session

get_training_session_titles(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve sessions (possibly filtered by project ID), titles only

get_training_session_titles_dict(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve (training) sessions (possibly filtered by project ID), return a dictionary of session IDs and titles

get_training_session_url(pmacontrolURL, participantSessionID, participantUsername, pmacontrolTrainingSessionID, pmacontrolCaseCollectionID, pmacoreSessionID)

get_training_sessions(pmacontrolURL, pmacontrolProjectID, pmacoreSessionID): Retrieve (training) sessions (possibly filtered by project ID), return a dictionary of session IDs and titles

get_training_sessions_for_participant(pmacontrolURL, participantUsername, pmacoreSessionID)

get_version_info(pmacontrolURL): Get version info from PMA.control instance running at pmacontrolURL

is_participant_in_training_session(pmacontrolURL, participantUsername, pmacontrolTrainingSessionID, pmacoreSessionID): Check to see if a specific user participates in a specific session

register_participant_for_project(pmacontrolURL, participantUsername, pmacontrolProjectID, pmacontrolRole, pmacoreSessionID, pmacontrolInteractionMode=0): Registers a participant for all sessions in a given project, assigning a specific role

register_participant_for_training_session(pmacontrolURL, participantUsername, pmacontrolTrainingSessionID, pmacontrolRole, pmacoreSessionID, pmacontrolInteractionMode=0): Registers a participant for a given session, assign a specific role

search_case_collection(pmacontrolURL, titleSubstring, pmacoreSessionID): Return the first collection that has titleSubstring as part of its string; search is case insensitive

search_project(pmacontrolURL, titleSubstring, pmacoreSessionID): Return the first project that has titleSubstring as part of its string; search is case insensitive

search_training_session(pmacontrolURL, titleSubstring, pmacoreSessionID): Return the first (training) session that has titleSubstring as part of its string; search is case insensitive

set_debug_flag(flag): Determine whether pma_python module runs in debugging mode or not. When in debugging mode (flag = true), extra output is produced when certain conditions in the code are not met

set_participant_interactionmode(pmacontrolURL, participantUsername, pmacontrolTrainingSessionID, pmacontrolCaseCollectionID, pmacontrolInteractionMode, pmacoreSessionID): Assign an interaction mode to a participant for a given Case Collection within a training session

Admin module

_pma_admin_url(sessionID=None)

_pma_check_for_pma_start(method='', url=None, session=None)

_pma_http_post(url, data, verify=True)

add_user(admSessionID, login, firstName, lastName, email, pwd, canAnnotate=False, isAdmin=False, isSuspended=False)

admin_connect(pmacoreURL, pmacoreAdmUsername, pmacoreAdmPassword): Attempt to connect to PMA.core instance; success results in a SessionID only success if the user has administrative status

admin_disconnect(admSessionID=None): Attempt to disconnect from PMA.core instance; True if valid admSessionID was indeed disconnected

create_amazons3_mounting_point(accessKey, secretKey, path, instanceId, chunkSize=1048576, serviceUrl=None): create an Amazon S3 mounting point. A list of these is to be used to supply method create_root_directory()

create_directory(admSessionID, path)

create_dropbox_mounting_point(): Placeholder for future functionality

create_filesystem_mounting_point(username, password, domainName, path, instanceId): create an FileSystem mounting point. A list of these is to be used to supply method create_root_directory()

create_googledrive_mounting_point(): Placeholder for future functionality

create_onedrive_mounting_point(): Placeholder for future functionality

create_root_directory(admSessionID, alias, amazonS3MountingPoints=None, fileSystemMountingPoints=None, description='Root dir created through pma_python', isPublic=False, isOffline=False, verify=True)

delete_directory(admSessionID, path): Deletes a directory from the PMA.core storage

delete_slide(admSessionID, slideRef): Deletes a slide from the PMA.core storage

rename_directory(admSessionID, originalPath, newName)

reverse_root_directory(admSessionID, alias, verify=True): lookup the reverse path of a root-directory

reverse_uid(admSessionID, slideRefUid, verify=True): lookup the reverse path of a UID for a specific slide

send_email_reminder(admSessionID, login, subject='PMA.core password reminder'): Send out an email reminder to the address associated with user login

set_debug_flag(flag): Determine whether pma_python runs in debugging mode or not. When in debugging mode (flag = true), extra output is produced when certain conditions in the code are not met

user_exists(admSessionID, u)

Version module

View module

get_version_info(pmaviewURL): Get version info from PMA.view instance running at pmaviewURL

set_debug_flag(flag): Determine whether pma_python runs in debugging mode or not. When in debugging mode (flag = true), extra output is produced when certain conditions in the code are not met