Programmatic access

DE EN
Log in

SAMS is open source and licensed under CC BY-SA 4.0, which includes giving “appropriate credit”. When crediting us, please cite our publication.

The source files are available at https://git-ext.charite.de/genecascade/sams. Please note that we cannot provide support for locally installed versions.

You may integrate SAMS with your own system with an iframe or by using hyperlinks:

Integrate SAMS as an iframe

Show SAMS within another site

The SAMS search interface can be readily integrated into hospital information systems as an HTML5 iframe and will return a GA4GH Phenopacket. No data is stored on our server. Simply include the following code:

<iframe src="https://www.genecascade.org/sams-cgi/phenotype.cgi" style="width: 100%; height: 100%;">
</iframe>

An example implementation can be found on this page. The style parameters can be adjusted to fit your needs.

Capture SAMS phenotypic data from an iframe

When using SAMS in an iFrame as described above and saving data to SAMS's database, SAMS will post messages with the uploaded data encoded 1) in SAMS format and 2) as Phenopacket. Note that you must be logged in to use this feature.

The following code on the website embedding the iframe will capture SAMS's output:

HTML:

<div id="sams-data">Placeholder for data from SAMS.</div><br>
<div id="sams-phenopacket">Placeholder for Phenopacket from SAMS.</div>

JavaScript:

<script>
	function addSAMS_data (evt) {
		if (evt.data) {
			let sams_data=document.getElementById("sams-data");
			let phenopacket=document.getElementById("sams-phenopacket");
			if (sams_data) sams_data.innerHTML=evt.data[0];
			if (phenopacket) phenopacket.innerHTML=evt.data[1];
		}
	}
	window.addEventListener("message", addSAMS_data, false);
</script>

Please note that you have to be logged into SAMS in your browser to access your patient data.
In the examples below, replace myPatID, the patient ID (parameter: external_id), with the pseudonomised ID you have given to your patient.

Link to the interface for recording a visit for a specific patient. You may also provide the visit date and details about the patient.
If a patient with the given external ID does not yet exist, it will be created.
If a visit for the given date already exists, you may edit this visit.

Call entry.cgi with mode=visit and your chosen parameters for external_id, sex, consanguinity and visit_date.

Parameters:

  • external_id is the only obligatory parameter.
  • sex can take the values m for male or f for female. If no parameter is given the sex is recorded as other/unknown. If a new patient is created, this value will be used. Note that this does not change the sex of an exisiting patient with this external id.
  • consanguinity can be true, if the patient has consanguineous patients or false if the patient has non-consanguineous parents. If no parameter is given the consanguinity is recorded as unknown. Note that this does not change the consanguinity of an exisiting patient with this external id.
  • visit_date is the date of the visit that you want to create or edit. Provide the date in the following format: yyyy-mm-dd (e.g. 2023-01-05 for fifth of January 2022). Note that if you do not provide the date here, it is possible that you will overwrite an existing visit.

Example link:
https://www.genecascade.org/sams-cgi/entry.cgi?external_id=myPatID&sex=m&consanguinity=true&visit_date=2023-07-12&mode=visit

Link directly to a specific questionnaire. These can normally be found by clicking "Pre-defined questionnaire". (If you would like to set up your own questionnaire, please contact us.
Call entry.cgi with mode=questionnaire and the additional parameter disease_group_number. These can be found by navigating to the table of questionnaires at https://www.genecascade.org/sams-cgi/ChooseDiseaseGroup.cgi. All other parameters are equivalent with mode=visit.

Example link:
https://www.genecascade.org/sams-cgi/entry.cgi?external_id=myPatID&sex=m&consanguinity=true&visit_date=2023-07-12&disease_group_number=1&mode=questionnaire

Link to the overview of all previous visits of a specific patient.

Call entry.cgi with mode=show and your external_id.

Example link:
https://www.genecascade.org/sams-cgi/entry.cgi?external_id=myPatID&mode=show

Export all recorded visits of a specific patient as a GA4GH Phenopacket in JSON format.

Call ExportPhenopacket.cgi with your external_id.

Example link:
https://www.genecascade.org/sams-cgi/ExportPhenopacket.cgi?external_id=myPatID

Downloading and uploading data via the command line interface

Disclaimer: Please be aware that you are responsible for obtaining patient consent for all usage of their data including data sharing and research purposes.

Python Wrapper

If you would like to use Python to interact with the SAMS database, this Python package may help: simple_sams_api.
Otherwise, just use the command line as explained below.

Currently, you have to provide your credentials (username and password) to obtain a session cookie to be able to use these command line functions. You may also use the option api to receive a less verbose output (no html).

curl -X POST -L -c sams_cookie.txt -d email=USERNAME -d password=PASSWORD -d api=1 https://www.genecascade.org/sams-cgi/login.cgi

The sams_cookie.txt file contains the session cookie.

Download phenopackets

Now you can use the obtained session cookie to proceed with a direct HTTP-Request to an Export-Script:

curl -b sams_cookie.txt https://www.genecascade.org/sams-cgi/ExportPhenopacket.cgi?external_id=PATIENTID

Or get the session cookie from the file and replace "SECRET_ID" with it:

curl --cookie "SAMSI=SECRET_ID" https://www.genecascade.org/sams-cgi/ExportPhenopacket.cgi?external_id=PATIENTID

You may of course also use the functionality to export all phenopackets created by one user using the following URL instead

https://www.genecascade.org/sams-cgi/ExportPhenopacket.cgi?export_all=1

Upload Phenopackets

Replace the code below with your chosen parameters.

Note that the parameter confirmed must always be 1.
You may additionally use the parameter -F phenopacket_id_radio=phenopacket_id if you want to use the Phenopacket ID instead of the subject ID as the patient's ID in SAMS.

Upload one Phenopacket

Note that the parameter api must be 1. This also provides a less verbose output (no html).

curl -b sams_cookie.txt -F phenopacket_json=@path/phenopacket_to_import.json -F confirmed=1 -F api=1 https://www.genecascade.org/sams-cgi/import_phenopacket.cgi
Upload multiple Phenopackets

The parameter phenopacket_prefix is optional. It can be used to add a prefix to all the patient IDs in SAMS which originate from this upload.

curl -b sams_cookie.txt  -F "phenopacket_json=@/path/phenopackets_to_import.json" -F "phenopacket_prefix=batch_" -F "confirmed=1" https://www.genecascade.org/sams-cgi/import_phenopacket.cgi

Integrating SAMS into your sytems

Please contact us.