OpenSpecimenAPIconnector.os_util package

Submodules

OpenSpecimenAPIconnector.os_util.aggregated_fields module

class OpenSpecimenAPIconnector.os_util.aggregated_fields.aggregator[source]

Bases: object

extract_age_fields(cp_csv, cp_data, cp_id)[source]
run_aggregation(sel_schema, ids=None)[source]

General purpose aggreation for fields in attached forms under developement. TODO: See which entities are stored with extension detail - and where to use’’–_’

OpenSpecimenAPIconnector.os_util.bulk_operations module

class OpenSpecimenAPIconnector.os_util.bulk_operations.bulk_operations[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 makes and executes an Import JOB.

Note

The OpenSpecimen Documentation of Bulk Import can be seen at https://openspecimen.atlassian.net/wiki/spaces/CAT/pages/440434702/Bulk+Import+via+API .

bulk_import(file, filename, schemaname, operation='CREATE', dateformat=None, timeformat=None)[source]

Make and Run a CSV-bulk import job

Make a JOB, precisely upload a file to OpenSpecimen, extract the file-ID token from this return and then execute it with the right schema and operation (Create or Update). To use this function one has to know which entity should be created or updated and which fields are mandatory.

Parameters

  • file (binary) – The file to upload, is a CSV-file with separator ‘,’.

  • filename (string) – Name of the file with ending (.csv)

  • schemaname (string) – The schemaname in OpenSpecimen with permissable values are: cp, cpr, user, userRoles, site, shipment, institute, dpRequirement, distributionProtocol, distributionorder, storagecontainer, storagecontainerType, containerShipment, cpe, masterSpecimen, participant, sr, visit, specimenAliquot, specimenDerivative, specimendisposal, consent

  • operation (string) – String with Information if the file updates data or create it. Default value = ‘CREATE’. Permissable values are CREATE or UPDATE

  • dateformat (string) – If another dateformat than in the OpenSpecimen System configuration is taken, this has to be specified.

  • timeformat (string) – If another timeformat than in the OpenSpecimen System configuration is taken, this has to be specified.

Returns

Data Frame with label, OS_IMPORT_STATUS OS_IMPORT_MESSAGE as column headers.

Return type

Pandas DataFrame

OpenSpecimenAPIconnector.os_util.collection_protocol_util module

class OpenSpecimenAPIconnector.os_util.collection_protocol_util.collection_protocol_util[source]

Bases: object

Utility class for Site API calls

This class handles the API calls for OpenSpecimen Collection Protocol. It can create, update, search and merge Protocols. 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 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

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

Create a Collection protocol with the given Parameters

Create a collection protocol with the Parameters passed to the function.

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 Protocl.

  • 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.

Returns

Details of the created Collection Protocol, or the OpenSpecimen’s error message.

Return type

dict

merge_cps(src_cp, trg_cp)[source]

Merge two Collection protocols

Merge two Colelction Protocols which are defined in src_cp and trg_cp together. To call this function the short titles of the source and target collection protocol has to be known. 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 PPI, visits and specimens. Or the target CP has no specific formats.

Parameters

  • src_cp (string) – String with the shortTitle of the source collection Protocol.

  • trgcp (string) – String with the shortTitle of the target collection Protocol.

Returns

JSON dict with the short titles of the source and target Colelction Protocols.

Return type

JSON-dict

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

Search for Colelction 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 after.

Parameters

  • search_string (string) – openSpecimen’s Advanced Query Language[optional]. Substring of the title or shorttitle

  • title (string) – Name of the desired Collection Protocol

  • ppid (string or int) – Id of the Pricincipal Investigator, gets converted to a string[optional].

  • reponame (string) – Name of the Repository in which the Collection Protocol is[optional].

  • startat (int) – Value which one of the outcomes is the first to show, if not specified OpenSpecimen takes 0.

  • maxresults (int) – Value how many Collection Protocols are shown, if not specified OpenSpecimen takes 100.

  • detailedList (string) – String in OpenSpecimen’s boolean format, permissable values are true/false. If not specified, OpenSpecimen takes false.

Returns

[Details of the matching Collection Protocols, if no one matches it is an empty list.

Return type

JSON-dict

update_cp(cpid, 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)[source]

Update a Collection protocol with the given Parameters.

Update a collection protocol with the Parameters passed to the function. The Collection protocol ID cpid is mandatory.

Note

The parameters except cpid are mandatory. All values not passed will not get changed.

Parameters

  • cpid (int) – ID of the Colelction Protocol which should get updated.

  • 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 Protocl.

  • 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.

Returns

Details of the created Collection Protocol, or the OpenSpecimen’s error message.

Return type

dict

OpenSpecimenAPIconnector.os_util.container_util module

class OpenSpecimenAPIconnector.os_util.container_util.container_util[source]

Bases: object

Handles the container operations to and from OpenSpecimen

This class handles the container based operations that can be done with OpenSpecimen.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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:

$ jupyter notebook main.ipynb

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

Create a container in Openspecimen

Create a 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

Returns data of the created container or the OpenSpecimen Error Message

Return type

data

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

Create a container in Openspecimen

Create a 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

  • container_id (int) – Id of the given container

Returns

Returns data of the created container or the OpenSpecimen Error Message

Return type

data

OpenSpecimenAPIconnector.os_util.cpevent_util module

class OpenSpecimenAPIconnector.os_util.cpevent_util.cpevent_util[source]

Bases: object

Handles the Events of corresponding to a Collection Protocol

This class allows you to handle the events in Openspecimen. One can create an event, but first the corresponding Collection Protocol has to be created, for Examples via os_core.collection_protocol.py. or one can update an existing event. The other calls are in the os_core class collection_protocol_event.py. 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. 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

$ jupyter notebook main.ipynb

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

Create an event for a given Collection Protocol.

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

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 needs the event code.

Returns

Returns a json dict with the details of the created event, or the OpenSpecimen error message.

Return type

json dict

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

Update an event for a given Collection Protocol.

Update an event for a given Collection Protocol. To use this function one has to know the eventid, it can for Examples be seen in the URL, if one click 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 first the function “get_all_events(self, cpid)” for a specific Collection Protocol, with the Collection Protocol ID is called.

Note

All parameters except the eventid are optional. If they are not passed to the function they stay the same as before.

Parameters

  • eventid (int) – The ID of the event. Gets converted to a string.

  • label (string) – Label of the event, has to be unique.

  • point (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 needs the event code.

Returns

Returns a json dict with the details of the created event, or the OpenSpecimen error message.

Return type

json dict

OpenSpecimenAPIconnector.os_util.cpr_util module

class OpenSpecimenAPIconnector.os_util.cpr_util.cpr_util[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, register existing participants to another protocol, get the details of an existing participant or more existing participants, update a participant.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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:

$ jupyter notebook main.ipynb

create_registration(regdate, 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, sexgenotype=None, pmis=None, mrn=None, sitename=None, empi=None)[source]

Register a participant to a Collection Protocol.

This function can create a new participant to an already existing Collection Protocol. To use this function one has to known 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.

Note

Either cpid or cptitle or cpshorttitle are mandatory to identify the Collection Protocol. ppid has to be left empty if PPID is auto-generated at protocol level, else it is mandatory. regdate is mandatory. For creating a Participant, all Participant fields can be left empty, except the first five have special rules.

Parameters

  • regdate (string) – Mandatory field with date of registration in the format which is defined in the systemsettings of OpenSpecimen.

  • 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 manually 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 number.

  • mrn (string) – Participants medical record number.

  • sitename (string) – Name of the site, where the participant is registered.

  • empi (string) – Enterprise master patient index number

Returns

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

Return type

JSON-dict

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

Search for one or more participants

Get the details of one or more participants, which are sepecified with the parameters from the function. The parameters are optional and if its all empty 100 participants will get returned, default order is with PPID. This function should be used before creating a participant to see if a participant is already in the system.

Parameters

  • lastname (string) – Substring of the Lastname of a Participant.

  • 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.

reqreginfostring

OpenSpecimen’s boolean (true/false). If true, it returns details of the participant

Returns

Details of the matching Parameters, if reqreginfo is true, return additional the participant info.

Return type

JSON-dict

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

Search for one or more participants

Get the details of one or more participants, which are sepecified with the parameters from the function. The parameters are optional and if its all empty 100 participants will get returned, default order is with PPID.

Parameters

  • cpid (int) – The collection protocols Id where the participant is registrered.

  • registrationdate (string) – The date of registration in the format, which is defined in the system settings.

  • ppid (string) – The Participant protocoll ID.

  • name (string) – Substring of the first, middle or last name.

  • birthdate (string) – The date of registration in the format, which is defined in the system settings.

  • uid (string) – Social Security Number or another unique national ID.

  • specimen (string) – The label or barcode of a specimen from the participant.

  • includestats (string) – OpenSpecimen’s boolean (true/false). If true, it returns the number of specimens and visits.

  • startat (int) – Defines which line of the matches is the first to show, the rows before get ignored in the return.

  • maxresults (int) – Defines how many rows should be displayed. OpenSpecimen’s default is 100.

Returns

Details of the Participant, who are matching the search criteria.

Return type

JSON-dict

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

Register a Participant to another protocol

Register an existing Participant to another Collection protocol.

Parameters

  • cprid (int) – Unique ID of the Participant’s Registration.

  • regdate (string) – Date of the registration.

  • cpid (int) – Unique ID of the Collection Protocol, which is autogenerated from OpenSpecimen. cpid or cptitle or cpshorttile is mandatory.

  • ppid (string) – Participant protocol ID, is mandatory if created manually and has to be empty if it is autogenerated. This is a protocol setting.

Returns

JSON-dict with details of the new participant, or the OS specific error message.

Return type

dict

update_registration(regdate, cprid, id_, 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, sexgenotype=None, pmis=None, mrn=None, sitename=None, empi=None)[source]

Register a Participant to a Collection Protocol.

This function can create a new 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. For updating a participant the cprid has to be known. This can be seen via GUI or with searching the participant first.

Note

Either cpid or cptitle or cpshorttitle are mandatory to identify the Collection Protocol. ppid has to be left empty, if PPID is auto-generated at protocol level, else it is mandatory. regdate is mandatory. For creating a participant, all participant fields can be left empty, except the first five have special rules.

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.

  • 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 manually and has 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 number.

  • mrn (string) – Participants medical record number.

  • sitename (string) – Name of the site, where the participant is registered.

  • empi (string) – Enterprise master patient index number.

Returns

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

Return type

JSON-dict

OpenSpecimenAPIconnector.os_util.csv_exp_util module

class OpenSpecimenAPIconnector.os_util.csv_exp_util.csv_exporter[source]

Bases: object

Handles the export of CSV files from open specimen for different entities like collection protocols, specimens etc etc.

This class handles the CSV export of various different entities and creates CSV files of the requested entities like collection protocols, institutes etc.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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:

$ jupyter notebook main.ipynb

csv_export(objecttype, recordids=None, cpid=None, ppids=None, entitytype=None, formname=None, specimenlabels=None, csv=False)[source]

Export CSV for the given entity

Export function for collection protocols

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 parameter

  • 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 or str if its a singular specimen to be exported

Returns

job – Returns the csv file as Pandas data frame or CSV binary string

Return type

Pandas DataFrame or CSV binary File

OpenSpecimenAPIconnector.os_util.institute_util module

class OpenSpecimenAPIconnector.os_util.institute_util.institutes_util[source]

Bases: object

Handles the API calls for the institutes

Handles the OpenSpecimen API calls for the institutes. This class can create, and update institutes. The other calls are in the os_core class institutes.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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:

$ jupyter notebook main.ipynb

create_institute(institutename)[source]

Creates an Institute.

Creates an Institute in OpenSpecimen.

Parameters

institutename (string) – the name of the institute.

OpenSpecimenAPIconnector.os_util.query_util module

class OpenSpecimenAPIconnector.os_util.query_util.query_util[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. The other calls are in the os_core class query.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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:

$ jupyter notebook main.ipynb

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

Create a Query in OpenSpecimen

Creates a Query which is stored in the Queries in OpenSpecimen. The query language can be extracted from the OpenSpecimen GUI query generator.

Parameters

  • cpid (int) – The collection Protocol ID where the query gets assigned to.

  • aql (string) – Command to execute in the OpenSpecimen’s Advanced Query Language.

  • rowmode (string) – Permissable Values OFF/SHALLOW/DEEP. Specify if multi-valued attributes result in a single row or one row per value.

  • columnexpr (string) – Permissable values true/false. If true Userfriendly column labels are included in the response.

  • isodate (string) – Permissable values are true/false. If true, the API accepts a ISO-date-format(yyy-MM-dd’T’HH:mm:ss), or else it takes the format from the OS local settings.

Returns

Details of the saved query or the OpenSpecimen’s error message.

Return type

JSON-dict

execute_query(qryid, start='0', results='100', rowmode='OFF', drivingform='Participant')[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 (int) – The System’s ID of the Query, will be converted to a string.

  • start (int) – Defines the row of the outcomes from which they will be displayed.

  • results (int) – Defines how many results will be displayed.

  • rowmode (string) – Permissable values are DEEP/SHALLOW/OFF. If OFF all values of a multivalued field are shown in one row.

  • drivingform (string) – Defines the search perspective, precisely which tables are searched at, permissable values are Participant, Specimen.

Returns

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

Return type

JSON-dict

search_query(cpid=None, searchstring=None, start=None, max_=None, countreq=None)[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

  • cpid (int) – The collection Protocol ID where the query is assigned to.

  • searchstring (string) – Substring of the query title.

  • start (int) – Defines the row of the outcomes from which they will be displayed.

  • max_ (int) – Defines how many results will be displayed.

  • countreq (string) – OpenSpecimen’s boolean, if true total number of saved queries will be shown.

Returns

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

Return type

JSON-dict

OpenSpecimenAPIconnector.os_util.site_util module

class OpenSpecimenAPIconnector.os_util.site_util.site_util[source]

Bases: object

Handles the calls for sites

This class handles the API calls for OpenSpecimen Sites. It can create, update and search sites with different parameters. The other calls are in the os_core class sites.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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

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

Create a site in OpenSpecimen

Create a site in OpenSpecimen with an API call.

Parameters

  • name (string) – Name of the site.

  • institutename (string) – Name of the institute where the site belongs to.

  • type_ (string) – Type of the site, permissable values are: collection site, repository, laboratory, not specified.

  • coordiantors (dict) – Dict with identifier of coordinators.[optional]

  • address (string) – String with the Address of the site[optional].

Returns

Details of the created site as dictionary or the OpenSpecimen’s error message.

Return type

dict

search_sites(sitename=None, institutename=None, maxresults=100, siteExtension=True)[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} This string gets generated here. If siteExtension is true, the detailed site parameters will get returned.

Parameters

  • sitename (string) – Substring of the sitenames.

  • institutename (string) – Substring of the Institutenames

  • maxresults (int) – Defines how many results will get returned maximally.

  • siteExtension (boolean) – If true, returns also the extension details.

Returns

Details of the matching sites, if no one matches it is an empty list.

Return type

JSON-dict

update_sites(siteid, name=None, institutename=None, type_=None, coordinators=None, address=None)[source]

Update a site in OpenSpecimen

Update a site in OpenSpecimen with an API call. In order to update a site one has to know the ID of the site which can be seen in the GUI, by clicking on the site, the URL looks like: http(s)://<host>:<port>/openspecimen/sites/{siteid}/overview. Or it can be first searched for, for Examples, by name with the function search_sites and then the ID can be extracted from there.

Parameters

  • siteid (int) – Unique Identifier of the Site

  • name (string) – Name of the Site.

  • institutename (string) – Name of the institute where the site belongs to.

  • type_ (string) – Type of the site, permissable values are: collection site, repository, laboratory, not specified.

  • coordiantors (dict) – Dict with identifier of coordinators.[optional]

  • address (string) – String with the Address of the site[optional].

Returns

Details of the created site as dictionary or the OpenSpecimen’s error message.

Return type

dict

OpenSpecimenAPIconnector.os_util.specimen_util module

class OpenSpecimenAPIconnector.os_util.specimen_util.specimen_util[source]

Bases: object

Handles the calls for Specimens

This class handles the API calls for OpenSpecimen Specimens. It can create, update, delete, search specimens with different parameters. The other calls are in the os_core class specimens. The output is a JSON dict or the Error message as dict. It also can check if a specimen exists which returns a string which tells you if it exists.

Note

In order to use this and also the other classes, the user has to know OpenSpecimen. 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

create_specimen(specimenclass, specimentype, pathology, anatomic, laterality, initqty, avaqty, visitid, recqlt, userid, colltime=None, rectime=None, lineage='New', status='Collected', stor_name=None, storlocx=None, storlocy=None, concetration=None, biohazard=None, comments=None, collproc=None, label=None, conttype=None, extensionudn=None, extensionmap=None, extensiondict=None)[source]

Create a Specimen to a visit

Create a Specimen to an already existing Visit. In order to use this function one has to know, the mandatory details of the specimen e.g. the class of the Specimen.

Note

The label is mandatory if the Protocolsettings are such that the Label is created manually, otherwise it has to be left empty.

Parameters

  • 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.

  • label (string) – The Label of the specimen, if automatically generated it has to be left empty, or else it is mandatory.

  • 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 in 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.

  • extensionudn (string) – OpenSpecimen’s boolean true/false. If true, the extension keys are the udn values of the corresponding form.[optional]

  • extensionmap (string) – The name of the Form which should be taken.[optional]

  • extensiondict (dict) – The dictionary of the extensions, has to be created manually. Either with udn or name (as defined before). [optional]

Returns

Dictionary with details of the specimen or the OpenSpecimen’s error meessage.

Return type

dict

delete_specimens(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 get returned. The function allows also to delete a list of specimen

Parameters

specimenids (list or int) – The unique ID(s) of the Specimen/Aliquot/Derivative which OpenSpecimen creates itself. The URL of the specimens, which should be deleted, 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

search_specimens(label=None, cprid=None, eventid=None, visitid=None, maxres='100', exact='false', extension='true')[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}

Parameters

  • label (string) – Label of the specimen.

  • cprid (int) – Collection Protocol Registration ID to what Participant the specimen belongs to.

  • eventid (int) – Unique systemwide Identifier of the event.

  • visitid (int) – Unique systemwide identifier of the visit.

  • maxres (int) – Defines how many results are returned maximally.

  • exact (string) – OpenSpecimen’s boolean true/false. If true Parameters have to match exactly.

  • extension (string) – OpenSpecimen’s boolean true/false. If true extension Details will get returned too.

Returns

Details of the matching Specimens, if no one matches it is an empty list.

Return type

dict

update_specimen(specimenid, label=None, specimenclass=None, specimentype=None, pathology=None, anatomic=None, laterality=None, initqty=None, avaqty=None, visitid=None, recqlt=None, colltime=None, rectime=None, lineage='New', status='Collected', stor_name=None, storlocx=None, storlocy=None, concetration=None, biohazard=None, userid=None, comments=None, collproc=None, conttype=None, extensionudn=None, extensionmap=None, extensiondict=None)[source]

Update an existing Specimen

Update an existing Specimen in order to use this function one has to know the specimenid. This can be seen via the GUI by clicking on the desired specimen, and read from the URL: http(s)://<host>:<port>/openspecimen/cps/{cpid}/specimens/{specimenid}/… . Or via search Specimen, for Examples by name and then extract the ID via key [“id”].

Note

The specimenid is mandatory, all the other keys are otional for updating. If left empty nothing will be changed.

Parameters

  • specimenid (int) – Unique Id of the specimen.

  • 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.

  • label (string) – The Label of the specimen.

  • colltime (string) – Date and Time of the collection event, the format is in the OpenSpecimen’s System configuration.

  • rectime (string) – Date and Time of the received event, the format is in the OpenSpecimen’s System configuration.

  • 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.

  • storlocx (int) – Position of the specimen in the Container in x direction.

  • storlocy (int) – Position of the specimen in the container in y direction.

  • concetration (int) – Concentration of the specimen.

  • biohazard (string) – Biohazards of that specimen.

  • 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.

  • collproc (string) – The procedure of the collection.

  • conttype (string) – Type of the storage container.

  • extensionudn (string) – OpenSpecimen’s boolean true/false. If true the extension keys are the udn values of the corresponding form.

  • extensionmap (string) – The name of the Form which should be taken.

  • extensiondict (dict) – The dictionary of the extensions, has to be created manually. Either with udn or name (as defined before).

Returns

Dictionary with details of the specimen or the OpenSpecimen’s error meessage.

Return type

dict

OpenSpecimenAPIconnector.os_util.users_util module

class OpenSpecimenAPIconnector.os_util.users_util.user_util[source]

Bases: object

assign_role(userid, siteid, cpid, role)[source]

Assign a role to a user

Assign a role to a user with ID {userid} in OpenSpecimen. To use this function one has to know the ID of the user, the site, the collection protocol and the name of the role. The user Id 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) – The ID of the user.

  • siteid (int) – The ID of the site.

  • cpid (int) – The ID of the collection protocol.

  • role (string) – The name 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

change_password(userid, newpw, oldpw=None)[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 the Superadmin, nor the Superadmin changes his own password the parameters are userid, oldpassword, new password.

Note

In the Systemsetting the Superadmin can define the passwords’ complexity.

Parameters

  • userid (int) – ID of the user, whose password should be changed.

  • newpw (string) – The new password of the user.

  • oldpw (string) – The old password of the user, has to be specified if the API user is not the Superadmin or the Superadmin changes his password.

Returns

Dict with status code. 200 password updated, 400 invalid Parameters, 500 unknown error.

Return type

dict

create_user(first, last, email, login, institute, type_, phone=None, address=None, domain='openSpecimen')[source]

Create a user

Create a User in OpenSpecimen. This function parses the input to a dict, what OpenSpecimen can understand.

Parameters

  • first (string) – Firstname of the User.

  • last (string) – Lastname of the User.

  • email (string) – Emailaddress of the user.

  • phone (string) – Phonenumber of the user.

  • login (string) – Loginename of the user, which has to be unique within the domain.

  • institute (string) – Name of the institute where the user belongs.

  • type_ (string) – Name of the usertype, defined in the OpenSpecimen distribution.

  • address (string) – Address of the user. [optional]

  • domain (string) – Domainname, by default OpenSpecimen.

Returns

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

Return type

dict

update_user(userid, first, last, email, login, institute, phone=None, type_=None, address=None, domain='openspecimen')[source]

Update a user

Update a User 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.

Note

For updating, the user has to be identified with its unique id {userid}, all the other parameters of the user are optional. If they are not passed to the function, they stay the same.

Parameters

  • userid (int) – Unique Id of the user.

  • first (string) – Firstname of the User.

  • last (string) – Lastname of the User.

  • email (string) – Emailaddress of the user.

  • phone (string) – Phonenumber of the user.

  • login (string) – Loginename of the user, which has to be unique within the domain.

  • institute (string) – Name of the institute where the user belongs to.

  • type_ (string) – Name of the usertype, defined in the OpenSpecimen distribution.

  • address (string) – Address of the user. [optional]

  • domain (string) – Domainname, by default OpenSpecimen.

Returns

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

Return type

dict

OpenSpecimenAPIconnector.os_util.visit_util module

class OpenSpecimenAPIconnector.os_util.visit_util.visit_util[source]

Bases: object

Handles the API calls for Visits

This class handles the API calls for OpenSpecimen Visits. It can create, update, search visits with different parameters, add visits and specimens in one call. 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. 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(name, site, eventid=None, eventlabel=None, cprid=None, ppid=None, cptitle=None, cpshorttitle=None, cpid=None, diagnosis=None, clinicalstatus=None, activity=None, visitstatus='Complete', missedreason=None, missedby=None, comments=None, pathologynumber=None, cohort=None, visitdate=None)[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) or (ppid and cpid) - name, site

Parameters

  • name (string) – Name of the Visit.

  • site (string) – Site to which the Visit belongs to.

  • eventid (int) – ID of the event to which the visit belongs to.[optional]

  • eventlabel (string) – Label of the event to which the visit belongs to.[optional]

  • cprid (int) – Identifier of the Collection Protocoll Registration to which the visit belongs to. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.

  • ppid (string) – Identifier of the Participant to whom the visit belongs to. 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.

  • cpid (int) – Identifier 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) – Comments regarding the visit.[optional]

  • pathologynumber (string) – Surgical Pathology number. [optional]

  • cohort (string) – Cohorts to which the visit belongs to. [optional]

  • visitdate (string) – Date when the visit will occur, if empty takes the current date.[optional]

Returns

Details of the visit as JSON dict or the Openspecimen’s error message.

Return type

dict

add_visit_speci(name, lineage, av_qty, user, init_qty, spec_class, spec_type, anat_site, site, path, speclabel=None, eventid=None, eventlabel=None, cprid=None, ppid=None, cptitle=None, cpshorttitle=None, cpid=None, diagnosis=None, clinicalstatus=None, activity=None, visitstatus=None, missedreason=None, missedby=None, comments=None, pathologynumber=None, cohort=None, visitdate=None, laterality=None, rec_qlt=None, colltime=None, rectime=None, status='Collected', stor_name=None, storlocx=None, storlocy=None, concentration=None, biohazrad=None, collproc=None, conttype=None, extensionudn=None, extensionmap=None, extensiondict=None)[source]

Add a visit and a specimen in one call.

Add a visit and a specimen in OpenSpecimen via one 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) or (ppid and cpid) - name, site The label is mandatory if the Protocolsettings are such that the Label is created manually, otherwise it has to be left empty.

Parameters

  • cprid (int) – Identifier of the Collection Protocoll Registration to which the visit belongs to. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.

  • name (string) – Name of the Visit.

  • lineage (string) – Lineage of the specimen, if created it is New.

  • av_qty (int) – The available quantity of a specimen.

  • user (int) – ID of the user who creates the specimen. If not specified the API user is taken.

  • init_qty (int) – The initial quantity of a specimen.

  • spec_class (string) – Class of the specimen.

  • spec_type (string) – Type of the specimen, belongs to the class.

  • anat_site (string) – The anatomic site of the specimen.

  • site (string) – Site to which the visit belongs to.

  • site,

  • eventid (int) – ID of the event to which the visit belongs to.[optional]

  • eventlabel (string) – Label of the event to which the visit belongs to.[optional]

  • ppid (string) – Identifier of the Participant to whom the visit belongs to. 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.

  • cpid (int) – Identifier 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 (stringsite,) – 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) – Comments regarding the visit.[optional]

  • pathologynumber (string) – Surgical Pathology number. [optional]

  • cohort (string) – Cohorts to which the visit belongs to. [optional]

  • visitdate (string) – Date when the visit will occur, if empty takes the current date.[optional]

  • pathology (string) – Pathologystatus of the Specimen.

  • laterality (string) – The laterality of the specimen.

  • 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]

  • 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 in the container in y direction.[optional]

  • concetration (int) – Concentration of the specimen[optional].

  • biohazard (string) – Biohazards of that specimen.[optional]

  • comments (string) – Comments regarding to the specimen[optional].

  • collproc (string) – The procedure of the collection[otpional].

  • conttype (string) – Type of the storage container.

  • extensionudn (string) – OpenSpecimen’s boolean true/false. If true, the extension keys are the udn values of the corresponding form.[optional]

  • extensionmap (string) – The name of the form which should be taken.[optional]

  • extensiondict (dict) – The dictionary of the extensions, has to be created manually. Either with udn or name (as defined before). [optional]

Returns

Details of the visit and specimen as JSON dict or the Openspecimen’s error message.

Return type

dict

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

Get a Visit by the Collection protocol Registration Id.

Get a visit by the Collection Protocoll Registration ID. Those parameters have to be known in order to know this function. They can be extracted from calling a search function in the os_core class visits.

Parameters

  • cprid (int) – Identifier of the collection protocol registration.

  • includestats (string) – OpenSpecimen’s boolean true/false. If true the stats of the participants, e.g. number of visits are included.

Returns

JSON-dict with details of the visit.

Return type

dict

search_visit_namespr(visitname=None, sprnumber=None)[source]

Get a Visit by the name or the Surgical pathology number

Get one or more visits by the name or the surgical pathology number. Those parameters have to be known in order to know 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 with this number. If both are passed it works as logical AND.

Parameters

  • visitname (string) – Substring of the name of the visit.

  • sprnumber (string) – Surgical Pathology number of the visits.

Returns

JSON-dict with details of the visits.

Return type

dict

update_visit(visitid, name=None, site=None, eventid=None, eventlabel=None, cprid=None, ppid=None, cptitle=None, cpshorttitle=None, diagnosis=None, clinicalstatus=None, activity=None, visitstatus=None, missedreason=None, missedby=None, comments=None, pathologynumber=None, cohort=None, visitdate=None, cpid=None)[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 extracts the id from there.

Note

All parameters are optional, except the visitid. The parameters which are not passed will stay the same.

Parameters

  • visitid (int) – Id of the visit, gets converted to a string

  • name (string) – Name of the visit.

  • site (string) – Site to which the visit belongs to.

  • eventid (int) – ID of the event to which the visit belongs to.[optional]

  • eventlabel (string) – Label of the event to which the visit belongs to.[optional]

  • cprid (int) – Identifier of the Collection Protocoll Registration to which the visit belongs to. cprid or (cptitle and ppid) or (cpid and ppid) or (cpshorttitle and ppid) are mandatory.

  • ppid (string) – Identifier of the Participant to whom the visit belongs to. 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.

  • cpid (int) – Identifier 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) – Comments regarding the visit.[optional]

  • pathologynumber (string) – Surgical Pathology number. [optional]

  • cohort (string) – Cohorts to which the visit belongs to. [optional]

  • visitdate (string) – Date when the visit will occur, if empty takes the current date.[optional]

Returns

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

Return type

dict

Module contents