OpenSpecimenAPIconnector.os_core package¶

Submodules¶

OpenSpecimenAPIconnector.os_core.collection_protocol module¶

class OpenSpecimenAPIconnector.os_core.collection_protocol.collection_protocol[source]¶

Bases: object

Handles the calls Collection Protocol

This class handles the API calls for OpenSpecimen Collection Protocol. It can create, delete, search a Protocol with different parameters, can get all Collection Protocols in the system and can get the template of the Collection Protocols as JSON dict or as Pandas dataframe. The output is a JSON dict or the error message as JSON dict, except the Pandas dataframe.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the Collection protocols are handled, is in the Jupyter-Notebook

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

create_collection_protocol(data)[source]¶

Creates a Collection Protocol

Creates a Collection Protocol in OpenSpecimen. In order to use this function, one has to know the parameters which OpenSpecimen needs to create a protocol. One can use it via the os_util class collection_protocol_util. This allows just the basic definition, if one has Extensions e.g. BBMRI contact, this fields have to be added separately.

Parameters: data (JSON-formatted string) – JSON formatted string with parameters: title, shortTitle, code[optional], startDate[optional], endDate[optional], principalInvestigator, coordinators[optional], irbId[optonal], anticipatedParticipantsCount[optional], activityStatus, visitNameFmt[optional], specimenLabel[optional], derivedlabelFormat[optional], ppIdFormat[optional], cpSites, manualPpidEnabled[optional], manualVisitNameEnabled[optional], manualSpecLabelEnabled[optional]
Returns: Either error details of the created protocol
Return type: json-dict

delete_collection_protocol(cpid)[source]¶

Delete a Collection Protocol with OpenSpecimens unique CollectionProtocolID

Delete an already existing Collection Protocol. The Parameters <cpid> is the uniqe ID of the Collection Protocol which is generated automatically from OpenSpecimen. To get the ID, one can click in the GUI on the Collection Protocol Details button and read it from the URL, with the format: http(s)://<host>:<port>/openspecimen/#/cp-view/{cpid}/overview. Another possibility is to search via ‘search_collection_protocols’ for a specific Parameters and then extract the ID from the JSON-dict which gets returned.

Parameters: cpid (int) – The unique ID of the collection protocol which OpenSpecimen creates itself as a string or integer. It will get converted to a string.
Returns: Details of the Collection Protocol which is deleted or the OpenSpecimen error message as dict.
Return type: JSON-dict

get_all_collection_protocols()[source]¶

Get all Collection Protocol

Get all Collection Protocols within the OpenSpecimen distribution, which is defined in the base_url.

Returns: Details of all Collection Protocols, which are in the OpenSpecimenDistribution.
Return type: JSON-dict

get_collection_protocol(cpid)[source]¶

Get the Collection Protocol with the ID cpid

Get the details of the Collection Protocol with the unique ID cpid. This ID is generated automatically from OpenSpecimen when the Protocol is created.

Parameters: cpid (int) – The System’s ID of the Collection Protocol will be converted to a string.
Returns: Details of the Collection Protocol with the specified ID, or the OpenSpecimen error message.
Return type: JSON-dict

get_cp_pandas_template()[source]¶

Template for the Collection Protocol

Template for the Collection Protocol as specified within the system. If, for Examples, some extension details for the Collection Protocols exists, this function will return also those values. These values are converted into a pandas dataframe, precisely, it is the header of a pandas data frame.

Returns: Empty pandas dataframe with OpenSpecimen keys as header inclusive extension details.
Return type: pandas.core.dataframe

merge_colelction_protocols(params)[source]¶

Merge two Collection Protocols

Merge two Collection Protocols which are defined in params. To call this function the short titles of the source and target collection protocol have to be known. The Parameters <params> is a json-formatted string, with keys srcCPShortTitle and tgtCpShorttitle. The merged Protocol is the one with short title tgtCpShortTitle, with merge logic outer.

Note

Merging is restricted to Super Admins. The CPs must have the same format for PPID, visits and specimens. Or the target CP has no specific formats.

Parameters: params (string) – JSON formatted string with keys srcCpShortTitle and tgtCpShortTitle and the corresponding short titles as values.
Returns: JSON dict with the short titles of the source and target Collection Protocols.
Return type: JSON-dict

search_collection_protocols(search_string)[source]¶

Search for Collection Protocols with specific values.

Search for one or more Collection Protocols with the search_string defined. The search string looks like: http(s)://<host>:<port>/openspecimen/rest/np/collection-protocols?{param_1}={value_1}&…&{param_x}={value_x} With the class collection_protocol_util from os_util and function <search_cps> the search string is generated and this function is called. Not all keys from OpenSpecimen can be easily searched for.

Parameters: search_string (string) – String with the following format: ?{param_1}={value_1}&…&{param_x}={value_x} . The parameters can be one of the following: searchString (OpenSpecimen’s AQL)[optional], title[optional], piId (Principa Investigator)[optional], repositoryName[optional], startAt[optional], maxResults[optional], detailedList[optional]
Returns: [Details of the matching Collection Protocols, if no one matches it, is an empty list.
Return type: JSON-dict

update_collection_protocol(cpid, params)[source]¶

Updates an existing Collection Protocol with ID cpid with the Parameters params

Note

For updating, all parameters are optional. Those parameters which are not passed to the function, will stay the same as before.

Parameters

cpid (int) – Unique Collection Protocol ID which is generated automatically from the System. It will be converted to a string.
params (string) – JSON-formatted string with the parameters should get updated. The keys which can get updated are: title, shortTitle, code[optional], startDate[optional], endDate[optional], principalInvestigator, coordinators[optional], irbId[optonal], anticipatedParticipantsCount[optional], activityStatus, visitNameFmt[optional], specimenLabel[optional], derivedlabelFormat[optional], ppIdFormat[optional], cpSites, manualPpidEnabled[optional], manualVisitNameEnabled[optional], manualSpecLabelEnabled[optional]

Returns

JSON-dict with the details of the updated Collection Protocol or the OpenSpecimen’s error message.

Return type

JSON-dict

OpenSpecimenAPIconnector.os_core.collection_protocol_event module¶

class OpenSpecimenAPIconnector.os_core.collection_protocol_event.collection_protocol_event[source]¶

Bases: object

Handles the Events of corresponding to a Colelction Protocol

This class allows you to handle the Events in Openspecimen. One can create an event, but first the corresponding Colelction Protocol have to be created, for Examples via os_core.collection_protocol.py. Get all events or just get one event, delete or update an existing event. The output is a JSON dict with either details or the Openspecimen error message.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes one can just pass the parameters via JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where also Events are handled is in the Jupyter-Notebook

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors one can easily test if the URL and login data are spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

create_event(params)[source]¶

Create an event for a given Collection Protocol.

Create an event for a given Collection Protocol. In order to use this function one has to know the parameters, which OpenSpecimen needs for to create an event. Another way to use it is with the class os_util.cpevent_util.py. An advantage of creating events with API calls is that the event Code “code” can be set, which is needed to add conditional forms via the workflow.

Parameters: params (string) – json-formatted string with parameters: eventLabel, eventPoint, collectionProtocol, defaultSite, clinicalDiagnosis, clinicalStatus, activityStatus, code[optional]
Returns: Returns a json dict with the details of the created event, or the OpenSpecimen error message.
Return type: json dict

delete_event(eventid)[source]¶

Delete an event with the ID eventid.

Delete an event, which is already in OpenSpecimen. The unique ID is generated from OpenSpecimen and can for Examples be seen in the URL, if one clicks on the event in the GUI. The URL looks like: http(s)://<host>:<port>/openspecimen/#/cps/{CollectionProtocolId}/specimen-requirements?eventId={eventid} For Examples, one can extract the eventid with an event-key from OpenSpecimen, when the function “get_all_events(self, cpid)” for a specific Collection Protocol, with the Collection Protocol ID is called first.

Parameters: eventid (int) – The unique ID of the event, which is created by OpenSpecimen.
Returns: Details of the deleted event or OpenSpecimens error message as JSON dict.
Return type: json dict

get_all_events(cpid)[source]¶

Get all events for a specific Collection Protocol with ID cpid.

Get the details of all events within a given Collection Protocol with the ID cpid. For Examples, the ID can be seen in the URL if one clicks on the overview of a Collection Protocol. The URL looks like: http(s)://<host>:<port>/openspecimen/#/cps/{cpid}/overview . Another possibility is to search via the function “search_collection_protocols(self, search_params)” from the class os_core.collection_protocol with an OpenSpecimen specific key and value.

Parameters: cpid (int) – Unique ID within OpenSpecimen from a given Collection Protocol. OpenSpecimen generates this ID automatically.
Returns: Details of all events within a given Collection Protocol as dict, where each event is a JSON-dict, or an error message, which is generated from OpenSpecimen.
Return type: json-dict

get_event(eventid)[source]¶

Get the details of an event with the unique ID eventid.

Get the details of an event, which is already in OpenSpecimen. The unique ID is generated from OpenSpecimen and can for Examples be seen in the URL, if one clicks on the event in the GUI. The URL looks like: http(s)://<host>:<port>/openspecimen/#/cps/{CollectionProtocolId}/specimen-requirements?eventId={eventid} For Examples, one can extract the eventid with an event-key from OpenSpecimen, when the function “get_all_events(self, cpid)” for a specific Collection Protocol, with the Collection Protocol ID is called first.

Parameters: eventid (int) – Unique ID of the event within OpenSpecimen, which is generated automatically.
Returns: Details of an event JSON-dict with ID eventid, or an error message, which is generated from OpenSpecimen.
Return type: json-dict

update_event(eventid, params)[source]¶

Update an existing event with ID eventid and the parameters params.

Update an existing event with ID eventid. In order to use this function, one has to know the parameters, which OpenSpecimen allows to update. For Examples, one can ‘add’ the Parameters “code” to an existing event which was created via GUI. This is needed if one wants to add conditional forms via the workflow.

Parameters

eventid (string or int) – Unique ID of the event within OpenSpecimen, which is generated automatically.
params (string) – json-formatted string with parameters: eventLabel, eventPoint, collectionProtocol, defaultSite, clinicalDiagnosis, clinicalStatus, activityStatus, code[optional]

Returns

Details of the event as JSON-dict which was updated, or an error message, which is generated from OpenSpecimen.

Return type

json-dict

OpenSpecimenAPIconnector.os_core.collection_protocol_registration module¶

class OpenSpecimenAPIconnector.os_core.collection_protocol_registration.collection_protocol_registration[source]¶

Bases: object

Handles the API calls to registrate participants to a Collection Protocol

Handles the OpenSpecimen API calls to registrate participants to an existing Collection Protocol. This class can create participants, delete participants, register existing participants to another protocol, merge participants, get the details of an existing participant or more existing participants, update a participant, get the consent forms of a participant, download a consent form and delete consents form of participants.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes one can just pass the parameters via JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where also Participants are registrated is in the Jupyter-Notebook

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

create_participant(params)[source]¶

Create or update a participant to a Collection Protocol.

This function can create a new participant or update an existing participant to an already existing Collection Protocol. To use this function one has to know either the Collection Protocoll id <cpId>, the title of the Collection Protocol <cpTitle> or the short title of the Collection Protocol <cpshorttitle> . Those values can be seen via GUI, extracted from the responses with the class collection_protocol in os_core or collection_protocol_util in os_util. To update a participant, one has to specify the unique ID of the participant. This Id can be searched via the function get_participant_matches in the os_core class participants.

Parameters

params (string) – JSON formatted string with the parameters of the participant. The paramter participant is a JSON-formatted string itself, for creating a participant it can be left empty; for updating the ID of the participant is needed. The keys of the participant dict are id[mandatory for updating], firstName, middleName, lastName, uid, birthdate, vitalStatus, deathDate, gender, race, ethnicities, sexGenotype, pmis, mrn, siteName, empi.
One of the following keys is mandatory to identify the protocol where the participant is created or updated cpId, cpTitle or cpShortTitle. – The key ppid has to be left blank, if it is set to be autogenerated by the system and is mandatory, if it is created manually.
registrationDate is a mandatory key, the date format is YYYY-MM-DD .

Returns

Details of the created or updated Participant or the OpenSpecimen error message as Dictionary.

Return type

JSON-dict

delete_consent(cprid)[source]¶

Delete a consent form of a participant.

Deletes a consent form of an existing participant with the uniquely participant ID <cprid> which is generated from the system. The ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters: cprid (int) – System generated unique ID of the participant. Will get converted to a string.
Returns: dict with value true or error message
Return type: JSON-dict

delete_participant(cprid)[source]¶

Delete a participant from a Collection Protocol

Deletes an existing participant with the uniquely participant ID <cprid> which is generated from the system. The ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters: cprid (int) – System generated unique ID of the participant. Will get converted to a string.
Returns: Details of the deleted participant or OpenSpecimen’s error message.
Return type: JSON-dict

download_consent_form(cprid)[source]¶

Download the consent form of a participant.

Downloads the consent form of an existing participant with the uniquely participant ID <cprid> which is generated from the system. The ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters: cprid (int) – System generated unique ID of the participant. Will get converted to a string.
Returns: Binary file content of the consent form or a status code.
Return type: binary

get_consents(cprid)[source]¶

Get the consent form of a participant.

Gets the consent form of an existing participant with the uniquely participant ID <cprid> which is generated from the system. The ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters: cprid (int) – System generated unique ID of the participant. Will get converted to a string.
Returns: Details of the consent form or the openSpecimen’s error message.
Return type: JSON-dict

get_registration(cprid)[source]¶

Get the details form of a participant.

Gets the details as JSON-dict form of an existing participant with the uniquely participant ID <cprid> which is generated from the system. The ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters: cprid (int) – System generated unique ID of the participant. Will get converted to a string.
Returns: Details of the participant or the openSpecimen’s error message.
Return type: JSON-dict

get_registrations(params)[source]¶

Search for one or more participants

Gets the details of one or more participants, which are specified in the parameters. The Parameters are passed via a JSON-formatted string. This function is used in the os_util class cpr_util, where the specific parameters can be passed.

Parameters: params (string) – Json formatted string with keys: cpId, registrationDate[optional], name(substring of first, last or middlename)[optional], ppid[optional], participantId[optional], dob[optional], specimen[optional], startAt(default=0)[optional], maxResults(default=100)[optional], includeStats(default=false)[optional], exactMatch(default=false)[optional]
Returns: Details of the Participant, who are matching the search criteria.
Return type: JSON-dict

merge_participants(id_from, id_to)[source]¶

Merge Participant x to Participant y

Merges Participant with the unique Participant ID <id_from> to the Participant with unique Participant ID <id_to>. This will move data from all visits and specimens from the source participant to the target participant and then deletes the source participant. The Participants unique ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants.

Parameters

id_from (int) – System generated unique ID of the source participant. Will get converted to a string.
id_to (int) – System generated unique ID of the target participant. Will get converted to a string.

Returns

Returns details of the merged participants as JSON-dict or OpenSpecimen’s error message.

Return type

JSON-dict

register_to_cp(params)[source]¶

Register a participant to another Collection Protocol

Registers an already existing Participant to another Collection Protocol. The Participants unique ID has to be known and can be seen for Examples via the GUI in the URL: http(s)://<host>:<port>/openspecimen/cp-view/{cpId}/participants/{cprid}/… or with the function get_participant_matches in the os_core class participants. Also, the collection protocol ID of the Protocol in which the participant is registered at has to be known.

Parameters: params (string) – JSON-formatted string with the Parameters: the keys are participant( value is a dict with key id and value Pariticipant ID[mandatory])[mandatory], registrationDate [mandatory], cpId [mandatory], ppid[mandatory if manually generated, leave empty if system-generated]
Returns: JSON-dict of the participant which is registred to another protocol.
Return type: JSON-dict

update_participant(cprid, params)[source]¶

Update a participant already in a Collection Protocol.

This function can update an existing participant with a unique Participant ID <cprid> to an already existing Collection Protocol. To use this function one has to know either the Collection Protocoll id <cpId>, the title of the Collection Protocol <cpTitle> or the short title of the Collection Protocol <cpshorttitle> . Those values can be seen via GUI, extracted from the responses with the class collection_protocol in os_core or collection_protocol_util in os_util. To update a participant, one has to specify the unique ID of the participant. This Id can be searched via the function get_participant_matches in the os_core class participants.

Parameters

cprid (int) – System generated unique ID of the participant. Will get converted to a string.
params (string) – JSON formatted string with the parameters of the participant. The paramter participant is a JSON-formatted string itself, the parameters which are passed will get updated. The keys of the participant dict are id[mandatory], firstName, middleName, lastName, uid, birthdate, vitalStatus, deathDate, gender, race, ethnicities, sexGenotype, pmis, mrn, siteName, empi.
One of the following keys is mandatory to identify the protocol, where the participant is created or updated cpId, cpTitle or cpShortTitle. – The key ppid has to be left blank, if it is set to be autogenerated by the system and is mandatory, if it is created manually.
registrationDate is a mandatory key, the date format is YYYY-MM-DD .

Returns

Details of the created or updated Participant or the OpenSpecimen error message as Dictionary.

Return type

JSON-dict

OpenSpecimenAPIconnector.os_core.container module¶

class OpenSpecimenAPIconnector.os_core.container.container[source]¶

Bases: object

Handles the API calls for the container operations

Handles the OpenSpecimen API calls related to Container Management. This class can get a container with a Participant Protocoll ID PPID or via search parameters.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the institutes are handled, is in the Jupyter-Notebook:

create_container(params)[source]¶

Creates a Container

Creates a Container in OpenSpecimen. In order to use this function, one has to know the parameters which OpenSpecimen needs to create a protocol. One can use it via the os_util class container_util. This allows just the basic definition, if one has Extensions e.g. BBMRI contact, this fields have to be added separately.

Parameters: params (string) – JSON formatted string with parameters: name(mandatory), barcode(optional), typeName(optional), activitystatus(optional), sitename(mandatory), storageloc(optional), numcols(mandatory), numrows(mandatory), storespecimens(mandatory), childcontainers(optional), temp(optional), columnlabelscheme(optional), rowlablescheme(optional), comment(optional), specimenclasses(optional), specimentypes(optinal), collectionprotocols(optional)
Returns: Either error details of the created container
Return type: json-dict

disable_container(containerid)[source]¶

Delete a container

Parameters: containerid (int) – The unique ID of the collection protocol which OpenSpecimen creates itself as a string or integer. It will get converted to a string.
Returns: Details of the Collection Protocol which is deleted or the OpenSpecimen error message as dict.
Return type: JSON-formatted string

get_all_containers(maxresults=None)[source]¶

Get all containers

Get all container4s currently created in the attached OpenSpecimen instance

Parameters: maxresults (int) – Maximum Number of Resutls to be fetched
Returns: Details of the fetched containers or the OpenSpecimen error message as dict.
Return type: JSON-formatted string

get_container(container_id)[source]¶

Get all containers

Get container with specified id <container_id> currently created in the attached OpenSpecimen instance

Parameters: container_id (int) – Id of the given container
Returns: Details of the given container or the OpenSpecimen error message as dict.
Return type: JSON-formatted string

update_container(params, container_id)[source]¶

Update Storage container

Parameters: params (string) – JSON formatted string with parameters: name(mandatory), barcode(optional), typeName(optional), activitystatus(optional), sitename(mandatory), storageloc(optional), numcols(mandatory), numrows(mandatory), storespecimens(mandatory), childcontainers(optional), temp(optional), columnlabelscheme(optional), rowlablescheme(optional), comment(optional), specimenclasses(optional), specimentypes(optinal), collectionprotocols(optional)
Returns: Details of the fetched containers or the OpenSpecimen error message as dict.
Return type: JSON-formatted string

OpenSpecimenAPIconnector.os_core.csv_bulk module¶

class OpenSpecimenAPIconnector.os_core.csv_bulk.csv_bulk[source]¶

Bases: object

Handles the OpenSpecimen CSV Bulk Importer via API.

Handles the API calls of the OpenSpecimen’s Bulk Importer for all the different schemas. This class can get the templates to a schema, upload the csv-files, run the job, get the job status and get the job report.

Note

The OpenSpecimen Documentation of the Bulk Import can be seen at https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/440434702/Bulk+Import+via+API . File uploading in OpenSpecimen are two calls, which here are two seperated calls, via the function bulk_import from the os_util class bulk_operations these calls get one call.

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

get_job_status(jobid)[source]¶

Get the Job status.

Get the status of a job with the ID <jobid> . The status of the job has to be known and can be seen via GUI in JOBS. The number after # in the title is the ID. The codes are: 200 : Bulk Import request was successfully processed. 401 : Authorisation failed, user doesn’t have the authority. 500 : Internal server error, encountered server error while performing operations.

Parameters: jobid (int) – ID of the job.
Returns: A string with the status code as mentioned above.
Return type: string

get_template(schemaname)[source]¶

Get the Templates to the corresponding schema

Get the Templates of a OpenSpecimen schema and load it into an empty pandas dataframe, where the OpenSpecimen specific keys are the header of the dataframe. To use this class, one has to know the schemanames which are used in OpenSpecimen. They are written in camelCase.

Note

The schemanames can be seen at: https://docs.google.com/spreadsheets/d/1fFcL91jSoTxusoBdxM_sr6TkLt65f25YPgfV-AYps4g/edit#gid=0

Parameters

schemaname (string) – String in camelCase of the schema, permissable values are: cp, specimen, cpr, user, userRoles, site, shipment, institute, dpRequirement, distributionProtocol, distributionOrder, storageContainer, storageContainertype, containerShipment, cpe, masterSpecimen, participant, sr, visit, specimenAliquot, specimenDerivatice, specimenDisposal, consent

Returns

pandas core dataframe – Empty dataframe with OpenSpecimen’s keys to the corresponding schema.
data binary csv file – The raw csv file

job_report(jobid)[source]¶

Download a job report.

Get the status of a job with the ID <jobid> . The status of the job has to be known and can be seen via GUI in JOBS or in the corresponding schema with View Past Imports. The number after # in the title is the ID. Generates a JSON-dict of the JOB containing the information which were uploaded and the additional fields OS_IMPORT_STATUS, OS_ERROR_MESSAGE. The status and error message can be extracted when converted to a list with location [-2,-1], or when converted to a dict with keys [‘OS_IMPORT_STATUS’] and [‘OS_ERROR_MESSAGE’].

Parameters: jobid (int) – ID of the job.
Returns: Job details as CSV like string separated by ‘,’
Return type: string

run_upload(schemaname, fileid, operation='CREATE', dateformat=None, timeformat=None)[source]¶

Run a job which is already created.

Runs a Job, which is already created. The schema and file-ID have to be known. Moreover, one has to specify if the job updates already existing objects or create new ones.

Note

The date and timeformat can be left empty, if it is compatible with OpenSpecimen.

Parameters

schemaname (string) – String in camelCase of the schema, permissable values are: cp, specimen, cpr, user, userRoles, site, shipment, institute, dpRequirement, distributionProtocol, distributionOrder, storageContainer, storageContainertype, containerShipment, cpe, masterSpecimen, participant, sr, visit, specimenAliquot, specimenDerivative, specimenDisposal, consent
fileid (string) – The file-ID, from OpenSpecimen generated, which is generated when the file is uploaded.
operation (string) – The permissable operations are ‘CREATE’ and ‘UPDATE’.
dateformat (string) – An optional Parameters, which has to be specified if the format is not compatible with OpenSpecimen.
timeformat (string) – An optional Parameters, which has to be specified if the format is not compatible with OpenSpecimen.

Returns

A tuple with the format (‘JOBID’, ‘Response Text’).

Return type

string

upload_csv(filename, file)[source]¶

Upload a CSV file to OpenSpecimen

This function handles the uploading of a CSV file to OpenSpecimen. This creates a job with a file-ID. With the file-ID the job then can be started via the function run_upload.

Note

The values are separated by comma ‘,’. This is the OpenSpecimen standard format.

Parameters

filename (string) – The name of the file as string with the ending, here .csv .
file (binary) – The file itself which should get uploaded.

Returns

The Job-ID as list with length 1.

Return type

list

OpenSpecimenAPIconnector.os_core.csv_export module¶

class OpenSpecimenAPIconnector.os_core.csv_export.CSV_exporter[source]¶

Bases: object

Handles the API calls for CSV file export

This class provides methods to create and fetch the resutls of an internal OpenSpecimen export job.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes one can just pass the parameters via JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

Just call create export job with the correct data json String like my_id = CSV_exporter().create_export_job() or supply a job id to call my_pd_data_frame = CSV_exporter().get_job_output() to retrieve a pandas data frame

create_export_job(data)[source]¶

Create export job method with the entity (Collection Protocoll, Institutes etc.) encoded within the data JSON-formated-string.

Parameters: data (JSON-formatted-string) – Containing the information needed by the API. See OpenSpecimenAPIconnector.os_util.Export_OP().export_file to find the JSON blueprint methods in OpenSpecimenAPIconnector.os_core.Json_Factory().
Returns: job_id – A string representing the id (integer number) assigned by the OpenSpecimen API
Return type: String

get_job_output(job_id)[source]¶

Fetch the output

Parameters: job_id – String representing the ID for identifying the output file
Returns: job_data – A pandas data frame containing the CSV files information. You can easily recover the original file by using the pandas.to_csv() method.
Return type: pandas.DataFrame()

OpenSpecimenAPIconnector.os_core.institute module¶

class OpenSpecimenAPIconnector.os_core.institute.institutes[source]¶

Bases: object

Handles the API calls for the institutes

Handles the OpenSpecimen API calls for the institutes. This class can create, delete, update institutes. One can search via different parameters for an institute and get all Collection protocols corresponding to an institute. Get one or all institutes.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

Code examples, where the institutes are handled, is in the Jupyter-Notebook:

ausgabe()[source]¶

Testing of the URL and Authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

create_institute(params)[source]¶

Create an Institute.

Creates an institute in OpenSpecimen. In order to use this function one has to know the parameters which OpenSpecimen needs to create an institute. One can use it via the os_util class institute_util. This allows just the basic definition.

Parameters: params (string) – JSON formatted string with Parameters: name (Name of the Institute)
Returns: Either details of the created institute as JSON-dict or the OpenSpecimen’s error message.
Return type: json-dict

delete_institute(inid)[source]¶

Delete an Institute

Delete an existing institute in OpenSpecimen with ID <inid>. The ID is created from OpenSpecimen and can, for Examples, be seen in the GUI under Institutes. When clicking on the institute, the URL looks like: http(s)://<host>:<port>/openspecimen/institutes/{inid}/overview . Otherwise, one can search with the function search_institutes for Examples by name and extract the ID from there.

Parameters: inid (int) – The ID of the Institute, generated by the system, will get converted to a string.
Returns: Details of the deleted institute or the OpenSpecimen’s error message.
Return type: JSON-dict

get_all_institutes()[source]¶

Get all Institutes

Get all institutes within the OpenSpecimen distribution, which is defined in the base_url.

Returns: Details of all institutes which are in the OpenSpecimen Distribution.
Return type: JSON-dict

get_institute(inid)[source]¶

Get the institute with the ID inid

Get the details of the Institute with the unique ID inid. This ID is automatically generated by OpenSpecimen at Protocol creation.

Parameters: inid (int) – The System’s ID of the Institute, will be converted to a string.
Returns: Details of the Institute with the specified ID, or the OpenSpecimen error message.
Return type: JSON-dict

search_institutes(substring)[source]¶

Search for Institutes with specific substring.

Search for one or more institutes with the substring. The search URL looks like: http(s)://<host>:<port>/openspecimen/rest/np/institutes?{param_1}={value_1}&…&{param_x}={value_x}

Parameters: substring (string) – Substring of the Institutename.
Returns: Details of all matching institutes or the OpenSpecimen’s error message.
Return type: JSON-dict

update_institute(inid, params)[source]¶

Updates an existing Institute with ID inid with the Parameters params

Updates an existing institute with the automatically generated OpenSpecimen’s system wide unique Institute ID instituteid, with the Parameters params which are passed to the function. The ID of the institute has to be known and can, for Examples, be seen in the GUI by clicking on the institutes, which has the format http(s)://<host>:<port>/openspecimen/institutes/{inid}/….or via the function search_institutes.

Parameters

instituteid (int) – Unique Institute ID which is generated automatically from the system. It will be converted to a string.
institutename (string) – New name of the institute, if it is left empty, nothing will be updated.

Returns

JSON-dict with the details of the updated institute or the OpenSpecimen’s error message.

Return type

JSON-dict

OpenSpecimenAPIconnector.os_core.jsons module¶

class OpenSpecimenAPIconnector.os_core.jsons.Json_factory[source]¶

Bases: object

add_visit_json(cprid, name, site, eventid=None, eventlabel=None, ppid=None, cptitle=None, cpshorttitle=None, diagnosis=None, clinicalstatus=None, activity=None, visitstatus='Complete', missedreason=None, missedby=None, comments=None, pathologynumber=None, cohort=None, visitdate=None, cpid=None)[source]¶

Create JSON formated string neccesary for adding an visit

Parameters

cprid (int) – Identifier of the Collection Protocoll Registration to which the Visit belongs. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.
name (string) – Name of the Visit.
site (string) – Site to which the Visit belongs.
eventid (int) – ID of the event to which the visit belongs.[optional]
eventlabel (string) – Label of the event to which the visit belongs.[optional]
ppid (string) – Identifier of the Participant to whom the Visit belongs. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.
cptitle (string) – Name of the Collection Protocol. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.
cpshorttitle (title) – Acronym of the Collection Protocol. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.
diagnosis (string) – Name of the diagnoses of the visit.
clinicalstatus (string) – Clinical Status of the visit.[optional]
activity (string) – Activity Status of the Visit.[optional]
visitstatus (string) – Status of the visit.[optional]
missedreason (string) – Reason why the visit was missed.[optional]
missedby (string) – Details of the person who missed the visit.[optional]
comments (string) – Commets regarding the visit.[optional]
pathologynumber (string) – Surgical Pathology number. [optional]
cohort (string) – Cohorts to which the Visit belongs. [optional]
visitdate (string) – Date when the visit will occur, if empty takes the current date.[optional]
cpid (int) – Identifier of the Collection Protocol. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.

Returns

Json data necessary to add an visit via API call

Return type

JSON-formatted string

assign_user_role_json(siteid, cpid, role)[source]¶

Assign Role

Assign a Role to a Collection Protocol.

Parameters

siteid (int) – Integer with the Unique ID of the site, where the User belongs.
cpid (int) – Integer with the unique ID of the Collection protocol.
role (string) – String with the name of the Role.

Returns

JSON-formatted string such that OpenSpecimen can read it.

Return type

string

change_user_pw_json(userid, newpw, oldpw=None)[source]¶

Change Password

Change the password of an user via API.

Note

If an user changes its own password, the old password is mandatory. If the user who changes the password is a superadmin, the new password is enough.

Parameters

userid (int) – Integer with the unique ID of the user, which password should be changed.
newpw (string) – String with the new password, care about the password complexity.
oldpw (string) – String with the old password.

Returns

JSO-formatted string to change the password, such that OpenSpecimen can read it.

Return type

string

create_CP_json(short_title=None, title=None, pi_mail=None, time_start=None, time_end=None, sites=None, man_id=False, coords=None, consentsWaived=None, eth_cons_id=None, part_no=None, desc_url=None, visitNameFmt=None, specimenLabelFmt=None, derivativeLabelFmt=None, man_visit_name=False, man_spec_label=True, aliquots_in_same=None, activity=None, aliquotLabelFmt=None, ppidFmt=None, specimenCentric=None, cpid=None)[source]¶

Creates the JSON-formated string corresponding to the collection_protocol_util funciton create_CP

Note

Mandatory paramters are passed as positional args within the calling util class

Parameters

short_title (string) – Short title of the Collection Protocol.
title (string) – Title of the Collection Protocol.
pi_mail (string) – Email Address of the Principal Investigator.
time_start (string) – String with the start_time of the collection Protocol in the timeformat specified in the System configuration.
time_end (string) – String with the end_time of the collection Protocol in the timeformat specified in the System configuration.
sites (list) – Sites which are assigned to the collection Protocol.
man_id (string) – OpenSpecimen’s boolean true/false if the manual PPID creation is enabled.
coords (dict) – dict with Coordinators and coordinator ids in it.
consentsWaived (string) – OpenSpecimen’s boolean true/false if consent should be waived.
eth_cons_id (string) – Ethical aproavel id.
part_no (string) – String with number of anticipated Participant count.
desc_url = string – URL with the decription of the Collection Protocol.
visitNameFMT (string) – String which contains the OpenSpecimen’s token for creating Visit Names automatically.
man_visit_name (string) – String with OpenSpecimen’s boolean format if the Visits should be created manually.
man_spec_label (string) – String with OpenSpecimen’s boolean format if the Specimen Labels should be created manually.
man_spec_label (string) – String with OpenSpecimen’s boolean format if the Aliquotes are stored in the same Container.
activity (string) – String with the acitivity status of the Specimen.
cpid (int) – Integer with the Unique ID of the Collection Protocol.

Returns

Collection protocol information neccesary for creation

Return type

JSON-formated-string

create_bulk_import_job(schemaname=None, operation=None, fileid=None, dateformat=None, timeformat=None)[source]¶

Create JSON formated string neccesary for creating a bulk import operation to be handled by OpenSpecimen

Parameters

schemaname (string) – The Openspecimen schematype, that defines the expected CSV file structure for the entity to be created
operation (string) – Either CREATE or UPDATE duplicate entries will be ignored in case of creation.
fileid (string) – The file id created internally by OpenSpecimen, which needs to be passed to the API
dateformat (string) – Specification of date format used in the OpenSpecimen API. See link for details https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/68976690/Date+and+time+formats
timeformat (string) – Specification of time format used in the OpenSpecimen API. See link for details https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/68976690/Date+and+time+formats

Returns

Json data needed for creating an CSV file import job for the given entity

Return type

JSON-formated-string

create_container_json(name=None, barcode=None, typename=None, activitystatus=None, sitename=None, storageloc=None, numcols=None, numrows=None, storespecimens=None, childcontainers=None, temp=None, columnlabelscheme=None, rowlablescheme=None, comment=None, specimenclasses=None, specimentypes=None, collectionprotocols=None)[source]¶

Create a storage container in OpenSpecimen

Parameters

name (string) – Name of the sorage container
barcode (string) – Barcode of the sotrage container
typename (string) – Container type (e.g. Freezer see https://openspecimen.atlassian.net/wiki/spaces/CAT/overview for available types and customization)
activitystatus (string) – Whether the container is operational: Active or disabled; Default active
sitename (string) – Site location of the container
storageloc (dict) – used if conatiner is a child container gives the name, id and position of the child within the parent container
numcols (string) – Number of container columns (if type allows it)
numrows (string) – Number of rows (if type allows it)
storespecimens (string) – Boolean value (true, false) whether container can hold specimens or not
childcontainers (string) – Filled if container sotres multiple other conatiners with different attributes
temp (string) – Number literal giving the container temperature in celcius (e.g. -80, -20)
columnlabelscheme (string) – Column labels - Numbers by default; Permissible Values are {Numbers, Alphabets Upper Case, Alphabets Lower Case, Roman Upper Case, Roman Lower Case}
rowlabelscheme (string) – Row labels - Numbers by default; Permissible Values are {Numbers, Alphabets Upper Case, Alphabets Lower Case, Roman Upper Case, Roman Lower Case}
comment (string) – Additional comments for the sorage container
specimenclasses (list) – Specimen Classes allowed to be stored within the container
specimentypes (list) – Specimen Types allowed to be stored within the container
collecitonprotocols (list) – List of collection Protocols that can store samples within the given container

Returns

Json-formatted string with details needed to create a container.

Return type

string

create_cp_event_json(label=None, point=None, cp=None, site=None, diagnosis=None, status=None, activity=None, unit=None, code=None)[source]¶

Create JSON-formated string needed for event creation

Create an event for a given Collection Protocol. Details of the parameters can be found in the parameters section.

Note

Mandatory paramters are passed as positional args within the calling util class

Parameters

label (string) – Label of the Event, has to be unique.
point (string or int) – Starting Point of the event, Value + unit (e.g. DAYS).
cp (string) – title of the collection protocol.
site (string) – The default Site of the event.
diagnosis (string) – Defines the permissable values of the diagnosis.
status (string) – Defines the permissable values of the clinical status.
acitivity (string) – DEfines the activity status of the event.
unit (string) – Defines which unit has the starting point.
code (string) – the Event code, is optional. In order to define condionals in the workflow, one need the Event code.

Returns

Returns a JSON-formated string with the given details for cp event creation

Return type

JSON-formated string

create_csv_export_job(objecttype=None, recordids=None, cpid=None, ppids=None, entitytype=None, formname=None, specimenlabels=None)[source]¶

Create JSON formated string neccesary for exporting an collection protocol (should be implemented but is not see OpenSpecimen 7.2)

Parameters

objecttype (string) – Identifying the general object to be exported. Permissible Values: “institute”, “site”, “user”, “cpr”, “specimen”, “extensions”, “storageContainer”
recordids (list or string) – Comma seperated list of record ids for fetching selected entries by their identifier. (Sites, Institutes, Users and Containers)
cp_id (string) – Collection protocol id of export target not neccesary for objects higher in the hierachy like institue or site. For all others it can be specified or set to “-1” which means all data in the system.
ppids (list or string) – List of comma seperated participant identifiers; String if its a singular participant to be exported Used in combination with specimen object type as a paramter
entitytype (string) – Paramter defining the entity for data extraction (e.g.: attached form at participant level) used with the extension object type
formname (string) – Defines the form to be downloaded in context of the extension object type together with the specified entity
specimenlabels (list or string) – List of comma seperated specimen identifiers; str if its a singular specimen to be exported

Returns

Json data needed for creating an export job for the given entity

Return type

JSON-formated-string

create_extension(attrsmap=None, extensiondict=None, useudn=None)[source]¶

create_institute(institutename=None, inst_id=None, get_csv=False)[source]¶

Create JSON-formatted string to neccesary to retrieve storage location via API

Parameters

institutename (string) – Name of the institute
inst_id – institute_id needed for updating when creating an institute via csv
get_csv (bool) – Return a CSV for creating an institute

Returns

JSON-formated string neccesary for creating an institute

Return type

JSON-formated string

create_participant_json(regdate=None, id_=None, cpid=None, cptitle=None, cpshorttitle=None, ppid=None, firstname=None, middlename=None, lastname=None, uid=None, birthdate=None, vitalstatus=None, deathdate=None, gender=None, race=None, ethnicities=None, cprid=None, sexgenotype=None, pmis=None, mrn=None, sitename=None, empi=None)[source]¶

Creates a JSON-formated string for participant creation This function creates the json corresponding to the cpr_util function

Note

Mandatory parameters are passed as positional arguments in the caliing function

Parameters

regdate (string) – Mandatory field with date of registration in the format which is defined in the systemsettings of openSpecimen.
cprid (int) – Unique ID of the Participant’s Registration.
id_ (int) – Unique ID of the Participant.
cpid (int) – Unique ID of the Collection Protocol, which is autogenerated from OpenSpecimen. cpid or cptitle or cpshorttile is mandatory.
cptitle (string) – Unique title of the Collection Protocol. cpid or cptitle or cpshorttile is mandatory.
cpshorttitle (string) – Unique Acronym of the Collection Protocol. cpid or cptitle or cpshorttile is mandatory.
ppid (string) – Participant protocol ID, is mandatory if created manaully and have to be empty if it is autogenerated. This is a protocol setting.
firstname (string) – Participants first name.
middlename (string) – Participants middle name.
lastname (string) – Participants last name.
uid (string) – Unique identifier e.g. social security number.
birthdate (string) – Birthdate in the format which is defined in the systemsettings of OpenSpecimen.
vitalstatus (string) – Vital status of the Participant.
deathdate (string) – Deathdate in the format which is defined in the systemsettings of OpenSpecimen.
gender (string) – Gender of the participant, permissable values are Male, Female, Unknown, Unspecified.
race (string) – Participants racial origination, permissable values are {American Indian or Alaska Native, Asian, black or Afro American, Native Hawaiian or other Pacific Islander, Not REported, Unknown, White}
ethnicities (string) – Participants ethnicities, permissable values are: {Hispanic or Latino, Not Hispanic or Latino, Not Reported, Unknown}
sexgenotype (string) – Participants sex Genotype, permissable values are {XX Genotype, XY Genotype, XXX, Klinefelter’s Syndrome, XXXY syndrome, XXYY syndrome, Mosaic including XXXXY, Penta X syndrome}
pmis (string) – Collection of the Participants medical record numner.
mrn (string) – Participants medical record number.
sitename (string) – Name of the site, where the participant is registrated.
empi (string) – Enterprise master patient index number.

Returns

Details of the updated Participant or the OpenSpecimen error message as Dictornary.

Return type

JSON-dict

create_site(name=None, institutename=None, type_=None, coordinators=None, address=None)[source]¶

Create a Site

Create the payload to create a site in OpenSpecimen via API.

Parameters

name (string) – String with the name of the site.
institutename (string) – String with the name of the institute.
type_ (string) – String with the type of the site.
coordinators (string) – String with the login-name of the coordinators.
address (string) – String with the address of the institute.
site_id (string) – String with site id for upadting via csv

Returns

JSON-formatted string to create a site such that OpenSpecimen can read it.

Return type

string

create_specimen_json(label=None, specimenclass=None, specimentype=None, pathology=None, anatomic=None, laterality=None, initqty=None, avaqty=None, visitid=None, userid=None, colltime=None, rectime=None, recqlt=None, lineage='New', status='Collected', storloc=None, concentration=None, biohazard=None, comments=None, collproc=None, conttype=None, extension=None)[source]¶

Create a API Json String for a Specimen Create the JSON String neccesary for creating a specimen

Note

Mandatory paramters are passed as positional args within the calling util class

Parameters

label (string) – UUID of specimen generated automatically if not set to manual in corresponding collection protocol
specimenclass (string) – Class of the specimen.
specimentype (string) – Type of the specimen, belongs to the class.
pathology (string) – Pathologystatus of the Specimen.
anatomic (string) – The anatomic site of the specimen.
laterality (string) – The laterality of the specimen.
initqty (int) – The initial quantity of a specimen.
avaqty (int) – The available quantity of a specimen.
visitid (int) – The unique identifier of the visit.
recqlt (string) – The received quality.
colltime (string) – Date and Time of the collection event, the format is in the OpenSpecimen’s System configuration.[optional]
rectime (string) – Date and Time of the received event, the format is in the OpenSpecimen’s System configuration.[optional]
lineage (string) – Lineage of the specimen, default value is New.
status (string) – Status of the Specimen, default is ‘Collected’.
stor_name (string) – Name of the container. [optional]
storlocx (int) – Position of the specimen in the Container in x direction.[optional]
storlocy (int) – Position of the specimen int the container in y direction.[optional]
concetration (int) – Concentration of the specimen[optional].
biohazard (string) – Biohazards of that specimen.[optional]
userid (int) – ID of the user who creates the specimen. If not specified the API user is taken.
comments (string) – Comments regarding to the specimen[optional].
collproc (string) – The procedure of the collection[otpional].
conttype (string) – Type of the storage conatiner.
extension (JSON-String) – JSON-formated-string containing the dict of specimnen extensions created during call to the corresponding util class

Returns

JSON-formated-string with the complete specimen to be created

Return type

dict

create_user_json(first=None, last=None, email=None, phone=None, login=None, institute=None, type_=None, address=None, domain=None)[source]¶

Create User

Create the payload for creating a user in OpenSpecimen.

Parameters

first (string) – First name of the user.
last (string) – Last name of the user.
email (string) – Email-address of the user.
phone (string) – Phone number of the user.
login (string) – Login name of the user.
institute (string) – Institute to which the user belongs.
type_ (string) – Type of the user.
address (string) – Address of the user.
domain (string) – Domain where the user belongs to.

Returns

JSON formatted string to create an user such that Openspecimen can read it

Return type

string

execute_aql(cpid, aql, rowmode='OFF', columnexpr='true', isodate='true')[source]¶

Create JSON formated string to execute a specified query passed to the method

Parameters

cp_id (string) – Collection protocoll id of export target
aql (string) – query command in the OpenSpecimen Syntax (see OpenSpecimen API)
rowmode (string) – Specifies whether multi-valued attributes result in a single row or one row per value. Default value is OFF. Other permitted values are SHALLOW and DEEP. Try out to see what fits best for your use case.
columnexpr (string) – Specifies whether the column labels or AQL expression needs to be included in the query response. By default, user friendly column labels are included in query response.
isodate (string) – Specifies how the date column values needs to be serialised in the query response. If true, then date/time values are serialised using ISO format: yyyy-MM-dd’T’HH:mm:ss. Otherwise, date/time values are serialised using the format specified in OS locale settings

Returns

Json data needed for executing a system query

Return type

JSON-formated-string

execute_query(start, results, drivingform='Participant', rowmode='OFF')[source]¶

Create JSON formated string neccesary for execution of a saved query

Parameters

start (string) – Used for paginating the results. If start=5, the output result will start from row number 5.
results (string) – Used for paginating the results. If results=10, the output result will be maximum 10 rows
drivingform (string) – Driving form determines the search perspective. When left empty, it defaults to Participant. (For Examples when drivingForm is Participant, the root table is ‘catissue_coll_prot_reg’ which is then used to join with the other tables. Similarly when drivingForm is Specimen, the root table will be catissue_specimen, which will be joined with the other tables.) rowmode: string

Returns

Json data needed for executing a query saved within an Openspecimen appliance

Return type

JSON-formatted-string

get_participants(lastname=None, uid=None, birthdate=None, pmi=None, empi=None, reqreginfo=None)[source]¶

Create JSON-formatted string to neccesary to retrieve storage location via API

Parameters

lastname (string) – Substring of the Lastname of a Paritcipant.
uid (string) – Country specific unique social security number.
birthdate (string) – The date of registration in the format, which is defined in the System settings.
pmi (dict) – Dict with details of the Medical records number mrn and the assigned site with key siteName.
empi (string) – Enterprise wide unique ID assigned to the participant.
reqreginfo (string) – OpenSpecimen’s boolean (true/false). If true it returns details of the participant

Returns

JSON-formated string neccesary for creating an institute

Return type

JSON-formated string

get_registrations(cpid=None, registrationdate=None, ppid=None, name=None, birthdate=None, uid=None, specimen=None, includestats=None, startat=None, maxresults=None, exactmatch=None)[source]¶

Create JSON formated string neccesary for creating a bulk import operation to be handled by OpenSpecimen

Parameters

cpid (string) – Collection protol id of the participants to be queried
registrationdate (string) – Date formatted string to query participants registered especially on this date
ppid (string) – OpenSpecimen internal unique id or part of a unique id to be matched (exact matching is defind in exact match)
name (string) – Name of the participant to be matched
birthdate (string) – Date formatted string containing the birthdate of a particiapnt to be queried
uid (string) – Social Security number or different national identifier
specimen (string) – Participants whose specimen labels or barcodes contain this Parameters value as a substring will be matched
includestats (string) – Include additional statitics within the response (visits specimens etc.)
startat (string) – startat and maxResults are useful in implementing pagination of participants list. When not specified, startAt defaults to 0. When startAt = n, the first element of the response is (n + 1)th participant satisfying the query criteria.
maxresults (string) – This Parameters specifies how many participant records should be included in the API response.
exactmatch (string) – Specifies whether the PPID should be exact match or sub-string match. Boolean true means exact match. Otherwise it is substring match.

Returns

CP id of target of merge action Json data needed for creating an CSV file import job for the given entity

Return type

JSON-formated-string

merge_cps(src_cp, trg_cp)[source]¶

Create JSON-formatted string to neccesary to retrieve storage location via API

Parameters

src_cp (string) – CP id of source collection protocoll for merge
trg_cp (string) – CP id of target of merge action

Returns

JSON-formated string neccesary for merging to CP’s via API

Return type

JSON-formated string

register_to_cp(cprid, regdate, cpid, ppid)[source]¶

Register a Registration to another Protocol

Register an existing Registration to another Collection Protocol.

Parameters

cprid (int) – Integer with the existing Registration Id of the Participant.
regdate (string) – Dete of the Regisrtation to the new protocol.
cpid (int) – Integer with the unique ID of the Collection Protocol.
ppid (string) – String with the Participant protocol ID.

Returns

Json-formatted string for register a Participant to another Protocol such that OpenSpecimen can read it.

Return type

string

storage_location_json(id_=None, name=None, xpos=None, ypos=None)[source]¶

Create JSON-formatted string to neccesary to retrieve storage location via API

Parameters

id (string) – Identifier of the Storage Container within OpenSpecimen.
name (string) – Storage Container name
xpos (string) – x-coordinate within the given storage conatiner grid (if applicable)
ypos (string) – y-coordinate within the given storage container grid (if applicable)

Returns

JSON foramted string that is needed to retrieve the storage location of a specimen

Return type

JSON-formated string

OpenSpecimenAPIconnector.os_core.mandatory module¶

class OpenSpecimenAPIconnector.os_core.mandatory.mark_mandatory[source]¶

Bases: object

mark_as_mandatory(names_list, mandatory_list, mand_ident, identifier)[source]¶

OpenSpecimenAPIconnector.os_core.participant module¶

class OpenSpecimenAPIconnector.os_core.participant.participant[source]¶

Bases: object

Handles the API calls for the participant

Handles the OpenSpecimen API calls for the participants. This class can get a participant with a Participant Protocoll ID PPID or via search parameters.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the institutes are handled, is in the Jupyter-Notebook:

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

get_participant(ppid)[source]¶

Get the participant with the Participant Protocol ID ppid

Get the details of the Participant with the Collection protocol wide unique ID ppid. This ID can be generated automatically from OpenSpecimen or generated manually, which has to be specified when the Collection Protocol is created.

Parameters: ppid (int) – The Collection Protocol wide unique Participant Protocol ID of the Institute will be converted to a string.
Returns: Details of the Participant with the specified PPID, or the OpenSpecimen error message.
Return type: JSON-dict

get_participant_matches(params)[source]¶

Get the Participants who matches the params.

Get one or more participants who match the criteria passed with params. This class can be used via the os_util class cpr_util.py.

Note

In the response the matching attributes are listed.

Parameters: params (string) – Json formatted string with parameters: lastName (substring)[optional], uid[optional], birthDate[optional], pmi(dict with keys mrn[optional], siteName[optional]) [optional], empi[optional], reqRegInfo(default =false)[optional]
Returns: Details of all matching participants or the OpenSpecimen’s error message.
Return type: JSON-dict

OpenSpecimenAPIconnector.os_core.query module¶

class OpenSpecimenAPIconnector.os_core.query.query[source]¶

Bases: object

Handles the API calls for the queries

Handles the OpenSpecimen API calls for the queries. This class can create, execute, search for queries. Also it can create a query in the OpenSpecimen specific Querylanguage AQL.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the Queries are handled, is in the Jupyter-Notebook:

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

execute_aql(params)[source]¶

Write and Execute a Query in OpenSpecimen

Creates a query which then is executed. The query language AQL can be extracted from the OpenSpecimen GUI query generator. The possible metainfos are written like schemaname.key. To use this class, one has to know the AQL language.

Parameters: params (string) – JSON-formatted string with the desired parameters. cpId, aql, wideRowMode(default =’OFF’) [optional] , outputColumnExprs (default= ‘true’)[optional], outputIsoDateTime (default = ‘true)[optional]
Returns: Details of the outcomes of the query with metadata, labels, and columns or the OpenSpecimen’s error message.
Return type: JSON-dict

execute_query(qryid, params)[source]¶

Execute a saved Query.

Execute an already existing query with the OpenSpecimen’s unique Query ID <qryid> . The query ID can be seen via clicking on the queries in OpenSpecimen and it is the number after # in the title.

Parameters

qryid (string or int) – The systems ID of the query will be converted to a string.
params (string) – JSON-formatted string with parameters: drivingForm, wideRowmode, startAt, maxResults

Returns

Details of all matching queries or the OpenSpecimen’s error message.

Return type

JSON-dict

search_query(suburl)[source]¶

Search for list of queries with specific suburl.

Search for one or more queries with the parameters in the suburl defined. The search URL looks like: http(s)://<host>:<port>/openspecimen/rest/np/saved-queries?{param_1}={value_1}&…&{param_x}={value_x}

Parameters: suburl (string) – Suburl of the queries with parameters: cpId, searchString, start, max, countReq
Returns: Details of all matching queries or the OpenSpecimen’s error message.
Return type: JSON-dict

OpenSpecimenAPIconnector.os_core.req_util module¶

class OpenSpecimenAPIconnector.os_core.req_util.OS_request_gen(auth)[source]¶

Bases: object

Generates OpenSpecimen specific requests

This class generates OpenSpecimen specific requests such that headers and authentification are created automatically. With this class the users have to specify which requests they do need, the url and the payload, which should be sent to OpenSpecimen. The payload alters for different requests and can be seen in the OpenSpecimen’s API documentation. The class can handle the following requests: GET, POST(formdata, files, json-formatted string), PUT, DELETE, HEADER.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. The users have to know which requests are needed and what content should be uploaded. The API documentation of OpenSpecimen is in: https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs

Examples

A code Examples, where those requests are used, is in the Jupyter-Notebook: $ jupyter notebook main.ipynb

delete_request(url)[source]¶

Generates DELETE requests for OpenSpecimen

Generates DELETE request for OpenSpecimen, which always contains the URL in the format http(s)://<host>:<port>/openspecimen/rest/ng/{entity}/{objectID} . Is used for deleting objects of a desired entity e.g. specimens. Usually OpenSpecimen requires the ID of the object in the URL.

Parameters: url (string) – URL for the get request as string has the form: http(s)://<host>:<port>/openspecimen/rest/ng/{entity}/{objectID}
Returns: The response of the request consists of status code, header and body. The type of the body alters for different requests.
Return type: http(s) response

get_request(url, stream=False)[source]¶

Generates GET requests for OpenSpecimen

Generates GET request for OpenSpecimen, which always contains the URL in the format http(s)://<host>:<port>/openspecimen/rest/ng/… . It is used for searching objects and downloading templates or collections. If one downloads a larger file, the Parameters stream has to be set to “True”.

Parameters

url (string) – URL for the get request as string has the form: http(s)://<host>:<port>/openspecimen/rest/ng/…
stream (bool) – Can be set to “True” for larger files, which takes a while to download. Default value is “False”.

Returns

The response of the request consists of status code, header and body. The type of the body alters for different requests.

Return type

http(s) response

head_request(url)[source]¶

Generates HEAD requests for OpenSpecimen

Generates a HEAD request for OpenSpecimen, which always contains the URL in the format http(s)://<host>:<port>/openspecimen/rest/ng/{entity} . It is used for getting the header of an object. Usually OpenSpecimen requires the entity of the object in the URL.

Parameters: url (string) – URL for the get request as string has the form: http(s)://<host>:<port>/openspecimen/rest/ng/{entity}
Returns: The response of the request consists of status code, header and body. The type of the body alters for different request.
Return type: http(s) response

post_request(url, data=None, form_data=False, files=None, params=None)[source]¶

Generates POST requests for OpenSpecimen

Generates POST request for OpenSpecimen, which always contains the URL in the format http(s)://<host>:<port>/openspecimen/rest/ng/… . This request is most times used for creating or updating objects in OpenSpecimen and the data is either a JSON-dict with the keys from OpenSpecimen or a binary-file content( this needs a second call to execute the job)

Parameters

url (string) – URL for the get request as string has the form: http(s)://<host>:<port>/openspecimen/rest/ng/…
data (json-formatted strings) – Json-formatted string, with the keys from OpenSpecimen.
form_data (bool) – Default value is “False”. Can be set to “True” if, for Examples, forms (.xml-files) are uploaded.
files (binary) – Default value is “None”. Contains tuple with name + ending and file itself.
params (json formatted string) – Json-formatted string, with the keys from OpenSpecimen.

Returns

The response of the request consists of status code, header and body. The type of the body alters for different requests.

Return type

http(s) response

put_request(url, data)[source]¶

Generates PUT requests for OpenSpecimen

Generates PUT request for OpenSpecimen, which always contains the URL in the format http(s)://<host>:<port>/openspecimen/rest/ng/… . This request is most times used for updating objects in OpenSpecimen and the data is a JSON-dict with the keys from OpenSpecimen.

Parameters

url (string) – URL for the get request as string has the form: http(s)://<host>:<port>/openspecimen/rest/ng/…
data (json-formatted strings) – Json-formatted string, with the keys from OpenSpecimen.

Returns

The response of the request consists of status code, header and body. The type of the body alters for different request.

Return type

http(s) response

user_name()[source]¶

Returns the OpenSpecimen Login name

Returns the OpenSpecimen login name of the API-User.

Returns: The API-User’s login name.
Return type: string

OpenSpecimenAPIconnector.os_core.site module¶

class OpenSpecimenAPIconnector.os_core.site.sites[source]¶

Bases: object

Handles the calls for sites

This class handles the API calls for OpenSpecimen Sites. It can create, delete, search sites with different parameters, get all sites and get the template of the sites as Pandas dataframe. The output is a JSON dict or the error message as JSON dict, except the Pandas dataframe.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the Collection protocols are handled, is in the Jupyter-Notebook: $ jupyter notebook main.ipynb

ausgabe()[source]¶: Testing of the URL and authentification. If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data and hand it over to the output terminal.

create_sites(params)[source]¶

Create a site in OpenSpecimen

Create a site in OpenSpecimen with an API call. In order to use this function, one has to know the OpenSpecimen specific permissable values. With the os_util class site_util.py a site with standard OpenSpecimen fields can be created, which is calling this function.

Parameters: params (string) – JSON-formatted string with parameters: name, instituteName, coordinators, type, activityStatus, address
Returns: Details of the created site as dictionary or the OpenSpecimen’s error message.
Return type: dict

delete_sites(siid)[source]¶

Delete a site with OpenSpecimen’s uniques Site ID

Delete an already existing site. The Parameters <siid> is the uniqe ID of the site which is generated automatically from OpenSpecimen. To get the ID, one can click in the GUI on the sites page of the desired site and read it from the URL, with format: http(s)://<host>:<port>/openspecimen/#/sites/{siid}/overview . Another possibility is to search via ‘search_sites’ for a specific Parameters and then extract the ID from the JSON-dict which get returned.

Parameters: siid (int) – The unique ID of the site which OpenSpecimen creates itself as an integer.
Returns: Details of the site which is deleted or the OpenSpecimen error message as dict.
Return type: JSON-dict

get_all_sites()[source]¶

Get all Sites

Get all sites within the OpenSpecimen distribution defined with the base_url.

Returns: Details of all sites as dictionary in the OpenSpecimen distribution
Return type: dict

get_site(siteid)[source]¶

Get the Site with the ID siteid

Get the details of a site with the system wide unique ID siteid. This ID is generated automatically from OpenSpecimen when the site is created.

Parameters: siteid (int) – The system wide unique ID of the side as int.
Returns: Details of the site with the specified ID as dictionary or the OpenSpecimen’ error message.
Return type: dict

search_sites(search_string)[source]¶

Search for sites with specific values. Search for one or more sites with the values in search_string defined. The search string looks like: http(s)://<host>:<port>/openspecimen/rest/np/sites?{param_1}={value_1}&…&{param_x}={value_x} With the class sites_util from os_util and function <search_sites> the search string is generated automatically and this function is called. Not all keys from OpenSpecimen can be easily searched for.

Parameters: search_string (string) – String with the following format: ?{param_1}={value_1}&…&{param_x}={value_x} . The parameters can be one of the following: startAt[optional], maxResults[optional], name[optional], exactMatch[optional], institute[optional]
Returns: Details of the matching sites, if no one matches, it is an empty list.
Return type: JSON-dict

update_site(siid, params)[source]¶

Updates an existing Site with ID siid with the Parameters params

Updates an existing site with the automatically generated OpsenSpecimen’s system wide unique site ID siid, with the parameters params which are passed to the function. The ID of the site has to be known and can, for Examples, be seen in the GUI by clicking on the site, which has the format http(s)://<host>:<port>/openspecimen/site/{cpid}/… . Or via the function search_sites or get_all_sites and extracted with key [“id”]

Note

The optional parameters are those, which are optional for a site. For updating, all parameters are optional, those which are not passed to the function will stay the same as before.

Parameters

siid (int) – Unique site ID which is generated automatically from the system.
params (string) – JSON-formatted string with the parameters which should get updated.The keys which can get updated are: name, instituteName, coordinators, type, activityStatus, address

Returns

JSON-dict with the details of the updated site or the OpenSpecimen’s error message.

Return type

JSON-dict

OpenSpecimenAPIconnector.os_core.specimen module¶

class OpenSpecimenAPIconnector.os_core.specimen.specimen[source]¶

Bases: object

Handles the calls for Specimens

This class handles the API calls for OpenSpecimen Specimens/Aliquots/Derivatives. It can create, delete, search, and determine the existence of specimens with different parameters. Further, a list of all specimens in the system can be created. The output is a JSON dict or the error message as dict.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the Specimens/Derivatives/Aliquots are handled, is in the Jupyter-Notebook: $ jupyter notebook main.ipynb

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

check_specimen(specimenLabel)[source]¶

Check if a Specimen with Label exists

Check if a specimen with Label specimenLabel already exists in the System. Can be interesting if one manually creates a label to avoid specimens with the same label.

Parameters: specimenLabel (string) – Label which should be checked as string. Gets converted to a string
Returns: If Specimen exists, returns “Specimen with label <specimenLabel> exists”. Or Else “Specimen with label <specimenLabel> does not exist”.
Return type: string

create_specimen(params)[source]¶

Creates a Specimen

Creates a Specimen. In order to use this function one has to know the parameters which OpenSpecimen needs to create a Specimen. One can use it via the os_util class specimen_util.py. This allows just the basic definition, if one has extensions e.g. BBMRI contact, this fields has to be added separately.

Parameters: params (string) – JSON formatted string with parameters: label[mandatory if its created manually, leave empty if the System creates it automatically], specimenclass, type, pathology, atomicSite, laterality, initialQty, availableQty, lineage, visitId, status, storageLocation(dict with keys positionX[optional], positionY[optional])[optional], concentration[optional], biohazards[optional], comments[optional], collectionEvent(DICT with keys user,time, container[otpional], procedure[optional]), receivedEvent(DICT with keys user, time, receivedQuality), extensionDetails(DICT with keys useUdn, attrsmap, DICT with extension keys)[optional]
Returns: Either details of the created specimen as dictionary or OpenSpecimen’s error message
Return type: json-dict

delete_specimen(specimenids)[source]¶

Delete a Specimen/Derivative/Aliquot

Delete an already existing Specimen/Derivative/Aliquot. The Parameters specimenid is the uniqe ID of the Specimen/ Derivative/Aliquot which is generated automatically from OpenSpecimen. To get the ID, one can click in the GUI on the Specimen/Derivative/Aliquot and read it from the URL, with format: http(s)://<host>:<port>/openspecimen/cp-view/{cpid}/specimen/{specimenid}/… . Another possibility is to search via ‘search_specimens’ for a specific Parameters and then extract the ID from the JSON-dict which gets returned. The function allows also to delete a list of specimen

Parameters: specimenids (string) – The unique ID(s) of the Specimen/Aliquot/Derivative which OpenSpecimen creates itself. Deleting specimens has the form “?id=specimenid_1+…+specimenid_n”
Returns: Details of the Specimens which are deleted or the OpenSpecimen error message as dict.
Return type: JSON-dict

get_specimen(specimenid)[source]¶

Get the Specimen with the ID specimenid

Get the details of the Specimen with the unique ID specimenid. This ID is generated automatically from OpenSpecimen when the Specimen is created. It can be seen in the GUI by clicking on the desired Specimen, and read from the URL: http(s)://<host>:<port>/openspecimen/cps/{cpid}/specimens/{specimenid}/… . Otherwise via search Specimen, for Examples by name and then extract the ID via key [“id”].

Parameters: specimenid (string or int) – The System’s ID of the Specimen, which will be converted to a string.
Returns: Details of the Specimen with the specified ID, or the OpenSpecimen error message.
Return type: JSON-dict

search_specimens(search_string)[source]¶

Search for Specimen with specific values.

Search for one or more Specimens with the values in the search_string defined. The search string looks like: http(s)://<host>:<port>/openspecimen/rest/np/specimens?{param_1}={value_1}&…&{param_x}={value_x} With the class specimen_util from os_util and function search_specimens the search string is generated and this function is called. Not all keys from OpenSpecimen can be easily searched for.

Parameters: search_string (string) – String with the following format: ?{param_1}={value_1}&…&{param_x}={value_x} . The parameters can be one of the following: label[optional], cprId[optional], eventId[optional], visitId[optional]
Returns: Details of the matching Specimens, if no one matches, it is an empty list.
Return type: dict

update_specimen(specimenid, params)[source]¶

Updates an existing Specimen/Aliquot/Derivative

Updates an existing Specimen/Derivative/Aliquot with the automatically generated OpsenSpecimen’s system wide unique specimen ID specimenid, with the parameters updateparams which are passed to the function. The ID of the specimen has to be known and can, for Examples, be seen in the GUI by clicking on theSpecimen, which has the format http(s)://<host>:<port>/openspecimen/cps/{cpid}/specimen/{specimenid} . Or via the function search_specimens and extract from there with the key [“id”]

Note

The optional parameters are those, which are optional for a Specimen. For updating, all parameters are optional, those which are not passed to the function will stay the same as before.

Parameters

cpid (int) – Unique Collection Protocol ID which is generated automatically from the System.
params (string) – JSON formatted string with parameters: label[mandatory if its created manually, leave empty if the System creates it automatically], specimenclass, type, pathology, atomicSite, laterality, initialQty, availableQty, lineage, visitId, parentId[mandatory if Aliquot/Derivative], status, storageLocation(dict with keys positionX[optional], positionY[optional])[optional], concentration[optional], biohazards[optional], comments[optional], collectionEvent(DICT with keys user,time, container[otpional], procedure[optional]), receivedEvent(DICT with keys user, time, receivedQuality), extensionDetails(DICT with keys useUdn, attrsmap, DICT with extension keys)[optional]

Returns

JSON-dict with the details of the updated Collection Protocol or the OpenSpecimen’s error message.

Return type

JSON-dict

OpenSpecimenAPIconnector.os_core.url module¶

class OpenSpecimenAPIconnector.os_core.url.url_gen[source]¶

Bases: object

Generates the endpoint URL for search- and list operations

This class generates the Parameters string used in search operations. It can also be used on arrays and lists. For Examples deleting a list of specimens can be handled with this class. Parameters strings look like ‘?entity1=value1&…&entityx=valuex’. To specify a list/array operation Parameters string format follows the following rule ‘?entity=value1,…,valuex&’

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes, one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

cp_search_url_gen(searchstring=None, title=None, piid=None, reponame=None, startat=None, maxresults=None, detailedlist=None)[source]¶

Generates the Parameters string for Collection Protocol search

This function generates the Parameters string to search for collection protocols. Permissable values are specified within OpenSpecimen. Values can be passed as lists single parameters will be added as logical AND.

Note

All parameters can be passed to the function as lists and will be reformated to be accepted by Openspecimen. Parameters permissible to be lists are marked as such within the parameters section.

Parameters

searchstring (string or list) – Substring of the title and short title which want to be searched for as string or list.
title (string or list) – Substring of the title which wants to be searched for as string or list.
ppid (string or int) – The ID of the principal investigator as string or int. Gets converted to a string.
reponame (string or list) – Name of the repositories as string or list.
startat (string or int) – Defines which row of the search outcome will be the first to show in the return(default n=0)
maxresults (string or int) – Defines how many rows of the search outcome will be shown, default value is 100.
detailedlist (string) – String with true or false, if true extension details will be shown.

Returns

Parameters string specific for the given searchoperation to be added to the URL endpoint the e.g.: ‘?query=’searchstring&title=title&…&detailedList=true’.

Return type

string

delete_specimens(specimenids)[source]¶

Generates the URL endpoint for deleting Specimens

Generates the string of the URL endpoint for deleting one or more specimens. Looks like ‘?id=specimenid1,…,specimenidx’

Parameters: specimenids (string/int or list of string/int) – The specimen IDs which one wants to delete, gets converted to a string.
Returns: The url endpoint as string.
Return type: string

query_url_gen(cpid=None, searchstring=None, start=None, max_=None, countreq=None)[source]¶

Generates the URL endpoint for searching a query.

Generates the string of the URL endpoint to searching for queries.

Note

All parameters can be passed to the function as lists and will be reformated to be accepted by Openspecimen. Parameters permissible to be lists are marked as such within the parameters section.

Parameters

cpid (string or int) – ID of the Collection Protocol, where the query is assigned to. Gets converted to a string.
searchstring (string) – Substring of the query-title.
start (string or int) – Defines the startrow, of the search outcome. Default is 0, gets converted to a string.
max_ (string or int) – Max results to displayed, default value is 100. Gets converted to a string.
countreq (true/false) – String with true or false. If true shows the total number of saved queries.

Returns

The URL endpoint to search for queries.

Return type

string

search_specimen(label=None, cprid=None, eventid=None, visitid=None, maxres='100', exact='false', extension='true')[source]¶

Generates the searchstring for Specimens

This function generates the string to search for collection protocols, with the permissable values from OpenSpecimen. The values can be lists, they are handled as a logical OR. The values not passed to the function will be ignored.

Note

All parameters can be passed to the function as lists and will be reformated to be accepted by Openspecimen. Parameters permissibke to be lists are marked as such within the paramters section.

Parameters

label (string or list) – The label of the specimen. If a list is passed it searches for multiple labels (logical OR)
cprid (string or int) – The Collection Protocol Registration ID of the specimen. Gets converted to a string.
enventid (string or int) – The Event ID of the anticipated Specimen. If searching with cprid the eventid or visitid is mandatory.
visitid (string or int) – The Visit ID of the anticipated Specimen. If searching with cprid the eventid or visitid is mandatory.
maxres (string or int) – The maximum results to display as int or string, gets converted to a string. The default value is 100.
exact (string) – Openspecimen’s boolean true/false. If true, the search parameters have to match exactly.
extensions (string) – Openspecimen’s boolean value true/false. If true, the extensionDetails will be shown in the results.

Returns

String of the URL endpoint for searching after specimens.

Return type

string

search_visit_cprid(cprid, includestats='false')[source]¶

Generates the URL endpoint for searching a visit

Generates the string of the URL endpoint for searching visits by the Collection Protocol Registration ID.It looks like ‘?cprId=cprid&includeStats=true/false’

Parameters

cprid (string or int) – The Visit ID which one wants to get. Gets converted to a string.
includestats (string) – OpenSpecimens boolean type true/false. Default is false and thus optional.

Returns

The url endpoint as string.

Return type

string

search_visit_name_spr(visitname=None, sprnumber=None)[source]¶

Generates the URL endpoint for searching a Visit

Generates the string of the URL endpoint for searching one or more visits by the name or surgical pathology number.It looks like ‘?name=visitname&sprNumber=sprnumber’

Parameters

visitname (string) – The visit name which one wants to get.
sprnumber (string or int) – The surgical pathology number as int or string, gets converted to a string

Returns

The url endpoint as string.

Return type

string

site_search_url_gen(sitename=None, institutename=None, maxresults=100)[source]¶

Generates the string for Site

This function generates the Parameters string to search for sites, with names or the sites to an institute. Sitename and Institutename can be lists, they are handled as a logical AND.

Parameters

sitename (string or list) – Substring of the Site which wants to be searched for as string or list.
instituename (string or list) – Substring of the Institute which want to be searched for as string or list.
maxresults (string or int) – The maximum results what should be shown. OpenSpecimen’s and here the default-value is 100. Gets converted to a string.

Returns

endpoint of the searchoperation, looks like ‘?name=’sitename1&name=sitename2&…&institute=institutenamex’.

Return type

string

OpenSpecimenAPIconnector.os_core.users module¶

class OpenSpecimenAPIconnector.os_core.users.users[source]¶

Bases: object

Handles the API calls for Users

This class handles the API calls for users. Get all or specific user information, create a user, change his/her/their password, get user-roles of or assign a specific role to a user.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. The users have to know which requests are needed and what content should be uploaded. The API documentation of OpenSpecimen is in: https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs

assign_role(userid, params)[source]¶

Assign a role to a User

Assign a role to a user with ID in OpenSpecimen. To use this function, one has to know the ID of the user. This can be seen in the GUI, if one clicks on the user and reads from the URL, which has the format: http(s)://<host>:<port>/openspecimen/users/{userid}/… . Or with the function get_all_users and then extract the ID to the wanted user.

Parameters

userid (int) – Int of the User ID, which one wants to delete. Gets converted to a string.
params (string) – JSON formatted string with parameters: site(dict with sitedetail), collectionProtocol (dict with Collection protocol detail), role(dict with detail of the role)

Returns

JSON dict with Details of the Roles of the User with ID userid or the OpenSpecimen’s error message.

Return type

dict

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

change_password(params)[source]¶

Change the password of a user

Change the password of a user. If the API-User is Superadmin, the parameters are userId,newPassword. If the user isn’t a Superadmin nor the Superadmin changes his own password, the parameters are userId, oldPassword, newPassword.

Parameters: params (string) – JSON formatted string with parameters userId, oldPassword[mandatory, if not SuperAdmin] newPassword
Returns: Dict with status code. 200 password updated, 400 invalid Parameters, 500 unknown error.
Return type: dict

create_user(params)[source]¶

Create a user

Create a user in OpenSpecimen. To use this function, one has to know the parameters. They are explained in the parameters section. Or one can use the os_util class user_util.

Parameters: params (string) – JSON formatted string with parameters: firstName, lastName, emailAddress, phoneNumber, domainName, loginName, instituteName, type, address[optional], activityStatus
Returns: JSON dict with details of the created user or the OpenSpecimen’s error message.
Return type: dict

delete_user(userid)[source]¶

Delete a user

Delete a user in OpenSpecimen. To use this function, one has to know ID of the user. This can be seen in the GUI, if one clicks on the user and reads from the URL, which has the format: http(s)://<host>:<port>/openspecimen/users/{userid}/… . Or with the function get_all_users and then extract the ID to the wanted user.

Parameters: userid (int) – String or int of the User Id which one wants to delete. Gets converted to a string.
Returns: JSON dict with details of the deleted user or the OpenSpecimen’s error message.
Return type: dict

get_all_users()[source]¶

Get all Users from OpenSpecimen

Returns all users within the OpenSpecimen disrtibution.

Returns: Returns all users as JSON dict, or an OpenSpecimen’s error message
Return type: dict

get_roles(userid)[source]¶

Get the roles of a user

Get the roles of a user with ID in OpenSpecimen. To use this function, one has to know the ID of the user. This can be seen in the GUI, if one clicks on the user and reads from the URL, which has the format: http(s)://<host>:<port>/openspecimen/users/{userid}/… . Or with the function get_all_users and then extract the ID to the wanted user.

Parameters: userid (int) – Int of the User Id which one wants to delete. Gets converted to a string.
Returns: JSON dict with Details of the Roles of the User with ID userid or the OpenSpecimen’s error message.
Return type: dict

get_user(userId)[source]¶

Get the User with ID

Get the User with ID from OpenSpecimen. To use this function, one has to know the ID of the user. This can be seen in the GUI if one clicks on the User and reads from the URL, which has the format: http(s)://<host>:<port>/openspecimen/users/{userid}/… . Or with the function get_all_users and then extract the ID to the wanted user.

Parameters: userId (int) – ID of the User which one wants to get.
Returns: JSON dict of the details of the specified user with ID or the OpenSpecimen’s error message
Return type: dict

update_user(userid, params)[source]¶

Update a User

Update a User in OpenSpecimen. To use this function, one has to know the parameters. They are explained in the parameters section. Or one can use the os_util class user_util. Also the ID of the user, which gets updated, has to be known. This can be seen in the GUI, if one clicks on the user and reads from the URL, which has the format: http(s)://<host>:<port>/openspecimen/users/{userid}/… . Or with the function get_all_users and then extract the ID to the wanted user.

Parameters

userid (int) – ID of the User.
params (string) – JSON formatted string with parameters: firstName, lastName, emailAddress, phoneNumber, domainName, loginName, instituteName, type, address[optional], activityStatus

Returns

JSON dict with Details of the updated User or the OpenSpecimen’s error message.

Return type

dict

OpenSpecimenAPIconnector.os_core.visit module¶

class OpenSpecimenAPIconnector.os_core.visit.visit[source]¶

Bases: object

Handles the API calls for Visits

This class handles the API calls for OpenSpecimen visits. It can create, delete, search visits with different parameters. Further visits can be added to a collection protocol within the system. The outputs are JSON dicts or the error messages as dict.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. In the core classes one can just pass the parameters via a JSON-formatted string. This means the user has to know the keywords. The API calls are documented in https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/1116035/REST+APIs and the calls refer to this site. More details can be seen in the documentation.

Examples

A code Examples, where the visits are handled, is in the Jupyter-Notebook: $ jupyter notebook main.ipynb

add_visit(params)[source]¶

Add a visit to a Participant.

Add a visit to a participant in OpenSpecimen via API call. To use this function, one has to know the parameters of the participant, event and site.

Note

Mandatory fields are -cprId or (ppid and cpTitle) or (ppid and cpShortTitle) - name, site

Parameters: params (string) – JSON formatted string with parameters: cprId, eventId, eventLabel, ppid, cptitle, cpShorttitle, name, clinicalDiagnoses[optional], clinicalStatus[optional], activityStatus [optional], site, status(permissable values: COMPLETE, PENDING, MISSED), missedReason[optional], missedBy[optional], comments[optional], surgicalPathologyNumber[optional], cohort[optional], visitDate[optional]
Returns: Details of the visit as JSON dict or the Openspecimen’s error message.
Return type: dict

add_visit_specimen(params)[source]¶

Generate a visit and corresponding specimens

Create a visit and specimens in one call. To use this function one has to know the parameters of the participants and events. Or one can use the create_visit_specimens function from the os_util class visit_util.

Note

The visit fields can be seen in add_visit and the ones for specimens are in create specimen.

Parameters: params (string) – JSON formatted string with parameters visit (dict-like string with details of the visit), specimens(dict-like string with details of the specimens)
Returns: JSON dict with the details of the created visit and specimens or OpenSpecimen’s error message
Return type: dict

ausgabe()[source]¶

Testing of the URL and authentification.

If there are any unexpected errors, one can easily test if the URL and login data is spelled correctly. The function prints the URL and login data to the output terminal, which was handed over to the class.

delete_visit(visitid)[source]¶

Delete a Visit from OpenSpecimen

Delete an existing visit in OpenSpecimen with the Visit ID visitid. This has to be known and can be found out in the GUI by clicking on a participant and the visit. It looks like: http(s)://<host>:<port>/openspeicmen/cp-view/{cpid}/participant/{cprid}/visits/detail/ocerview?visitId={visitid}&eventId={eventId} . Or via the function get_visit_namespr, when one knows the name of the visit and then extract the ID from there.

Parameters: visitid (int) – ID of the visit, gets converted to a string.
Returns: JSON-dict with the details of the deleted visit or the OpenSpecimen’s error message
Return type: dict

get_visit(visitid)[source]¶

Get a Visit from OpenSpecimen

Get an existing visit in OpenSpecimen with the Visit ID visitid. This has to be known and can be found out in the GUI by clicking on a participant and the visit. It looks like: http(s)://<host>:<port>/openspeicmen/cp-view/{cpid}/participant/{cprid}/visits/detail/ocerview?visitId={visitid}&eventId={eventId} . Or via the function get_visit_namespr, when one knows the name of the visit and then extract the id from there.

Parameters: visitid (int) – ID of the visit, gets converted to a string.
Returns: JSON-dict with the details of the visit with ID visitid or the OpenSpecimen’s error message
Return type: dict

get_visit_namespr(search_string)[source]¶

Get a Visit by the Name or the Surgical Pathology Number

Get one or more visits by name or surgical pathology number. Parameters have to be known in advance in order to use this function. If just the visitname is passed, one returns a visit with the corresponding name. If just the surgical pathology number is passed, it returns all visits attached to this number. If both are passed, it works as logical AND.

Parameters: search_string (string) – string in the format ‘?name=visitname(optional)&sprNumer=sprnumber(optional)
Returns: JSON-dict with details of the visits.
Return type: dict

get_visits_cpr(search_string)[source]¶

Get a Visit by the Collection Protocol Registration ID.

Get a visit by the collection protocoll registration ID. Parameters have to be known in advance in order to use this function. They can be extracted from calling a search function in the os_core class visits.

Parameters: search_string (string) – string in the format ‘?cprId=cprid&includeStats=true/false(optional)’
Returns: JSON-dict with details of the visit.
Return type: dict

update_visit(visitid, params)[source]¶

Updating a visit

Update an existing visit with ID visitid and the parameters params. All parameters are optional for updating and those which are not passed, stay the same. Those parameters and the visit ID have to be known to use this function and can be found out in the GUI by clicking on a participant and the visit. It looks like: http(s)://<host>:<port>/openspeicmen/cp-view/{cpid}/participant/{cprid}/visits/detail/ocerview?visitId={visitid}&eventId={eventId} . Or via the function get_visit_namespr, when one knows the name of the visit and then extract the ID from there.

Note

Mandatory fields are -cprId or (ppid and cpTitle) or (ppid and cpShortTitle), - name, -site

Parameters

visitid (int) – ID of the visit as int or string, gets converted to a string
params (string) – JSON- formatted string with parameters: cprId, eventId, eventLabel, eventPoint[optional], ppid, cptitle, cpShorttitle, name, clinicalDiagnoses[optional], clinicalStatus[optional], activityStatus [optional], site, status(permissable values: COMPLETE, PENDING, MISSED), missedReason[optional], missedBy[optional], comments[optional], surgicalPathologyNumber[optional], cohort[optional], visitDate[optional]

Returns

JSON-dict with details of the updated visit or OpenSpecimens error message

Return type

dict

OpenSpecimenAPIconnector.os_core package¶

Submodules¶

OpenSpecimenAPIconnector.os_core.collection_protocol module¶

OpenSpecimenAPIconnector.os_core.collection_protocol_event module¶

OpenSpecimenAPIconnector.os_core.collection_protocol_registration module¶

OpenSpecimenAPIconnector.os_core.container module¶

OpenSpecimenAPIconnector.os_core.csv_bulk module¶

OpenSpecimenAPIconnector.os_core.csv_export module¶

OpenSpecimenAPIconnector.os_core.institute module¶

OpenSpecimenAPIconnector.os_core.jsons module¶

OpenSpecimenAPIconnector.os_core.mandatory module¶

OpenSpecimenAPIconnector.os_core.participant module¶

OpenSpecimenAPIconnector.os_core.query module¶

OpenSpecimenAPIconnector.os_core.req_util module¶

OpenSpecimenAPIconnector.os_core.site module¶

OpenSpecimenAPIconnector.os_core.specimen module¶

OpenSpecimenAPIconnector.os_core.url module¶

OpenSpecimenAPIconnector.os_core.users module¶

OpenSpecimenAPIconnector.os_core.visit module¶

Module contents¶