Patients#
The module patients provides functions related to Patients section of
cBioPortal Web Public API.
- pybioportal.patients.fetch_patients(patient_identifiers=None, unique_patient_keys=None, projection='SUMMARY')#
Fetch patients.
- Parameters:
patient_identifiers (list of dict) –
List of Patient ID / Study ID pairs.
Each dict should have the following format:
- patient_identifiers=[
- {“patient_ids”: [‘TCGA-3C-AAAU’,’TCGA-3C-AALI’],
“study_id”: “brca_tcga”},
- {“patient_ids”: [‘TCGA-A1-A0SB’,’TCGA-A1-A0SD’],
“study_id”: “brca_tcga_pub”}
]
unique_patient_keys – List of Unique Patient Keys, e.g. [‘VENHQS0zQy1BQUFVOmJyY2FfdGNnYQ’, ‘VENHQS1BMS1BMFNEOmJyY2FfdGNnYV9wdWI’].
:type unique_patient_keys: list of str
:param projection: Level of detail of the response.
Possible values:
“DETAILED”: Detailed information.
“ID”: Information with only IDs.
“META”: Metadata information.
“SUMMARY”: Summary information (default).
- Returns:
A DataFrame containing list of patients.
- Return type:
pandas.DataFrame
- pybioportal.patients.get_all_patients(projection='SUMMARY', direction='ASC', keyword=None, pageNumber=0, pageSize=10000000, sortBy=None)#
Get all patients.
- Parameters:
projection (str) –
Level of detail of the response.
Possible values:
”DETAILED”: Detailed information.
”ID”: Information with only IDs.
”META”: Metadata information.
”SUMMARY”: Summary information (default).
direction (str) –
Direction of the sort.
Possible values:
”ASC”: Ascending (default).
”DESC”: Descending.
keyword (str) – Search keyword that applies to ID of the patients.
pageNumber (int) –
Page number of the result list.
Minimum value is 0.
pageSize (int) –
Page size of the result list.
Minimum value is 1, maximum value is 10000000.
sortBy (str) –
Name of the property that the result list is sorted by.
Possible values:
”patientId”
- Returns:
A DataFrame containing list of patients.
- Return type:
pandas.DataFrame
- pybioportal.patients.get_all_patients_in_study(study_id, direction='ASC', pageNumber=0, pageSize=10000000, projection='SUMMARY', sortBy=None)#
Get all patients in a study.
- Parameters:
study_id (str) – Study ID (e.g., “acc_tcga”).
direction (str) –
Direction of the sort.
Possible values:
”ASC”: Ascending (default).
”DESC”: Descending.
pageNumber (int) –
Page number of the result list.
Minimum value is 0.
pageSize (int) –
Page size of the result list.
Minimum value is 1, maximum value is 10000000.
projection (str) –
Level of detail of the response.
Possible values:
”DETAILED”: Detailed information.
”ID”: Information with only IDs.
”META”: Metadata information.
”SUMMARY”: Summary information (default).
sortBy (str) –
Name of the property that the result list is sorted by.
Possible values:
”patientId”: Sort by patient ID.
- Returns:
A DataFrame containing list of patients in the specified study.
- Return type:
pandas.DataFrame
- pybioportal.patients.get_patient_in_study(study_id, patient_id)#
Get a patient in a study.
- Parameters:
study_id (str) – Study ID (e.g., “acc_tcga”).
patient_id (str) – Patient ID (e.g., “TCGA-OR-A5J2”).
- Returns:
A DataFrame containing details of the specified patient in the study.
- Return type:
pandas.DataFrame
Examples#
from pybioportal import patients as pts
df1 = pts.get_all_patients(keyword="TCGA")
df1
| uniquePatientKey | patientId | studyId | |
|---|---|---|---|
| 0 | VENHQS0wMi0wMDAxOmdibV90Y2dhX3B1Yg | TCGA-02-0001 | gbm_tcga_pub |
| 1 | VENHQS0wMi0wMDAxOmdibV90Y2dhX3B1YjIwMTM | TCGA-02-0001 | gbm_tcga_pub2013 |
| 2 | VENHQS0wMi0wMDAxOmxnZ2dibV90Y2dhX3B1Yg | TCGA-02-0001 | lgggbm_tcga_pub |
| 3 | VENHQS0wMi0wMDAxOmdibV90Y2dhX3Bhbl9jYW5fYXRsYX... | TCGA-02-0001 | gbm_tcga_pan_can_atlas_2018 |
| 4 | VENHQS0wMi0wMDAxOmdibV90Y2dh | TCGA-02-0001 | gbm_tcga |
| ... | ... | ... | ... |
| 33581 | SURUQ0dBLTAyOm1peGVkX21za190Y2dhXzIwMjE | IDTCGA-02 | mixed_msk_tcga_2021 |
| 33582 | SURUQ0dBLTAzOm1peGVkX21za190Y2dhXzIwMjE | IDTCGA-03 | mixed_msk_tcga_2021 |
| 33583 | SURUQ0dBLTA0Om1peGVkX21za190Y2dhXzIwMjE | IDTCGA-04 | mixed_msk_tcga_2021 |
| 33584 | SURUQ0dBLTA1Om1peGVkX21za190Y2dhXzIwMjE | IDTCGA-05 | mixed_msk_tcga_2021 |
| 33585 | SURUQ0dBLTA2Om1peGVkX21za190Y2dhXzIwMjE | IDTCGA-06 | mixed_msk_tcga_2021 |
33586 rows × 3 columns
df2a = pts.fetch_patients(patient_identifiers=[
{"patient_ids": ["TCGA-3C-AAAU","TCGA-3C-AALI"],
"study_id": "brca_tcga"},
{"patient_ids": ["TCGA-A1-A0SB","TCGA-A1-A0SD"],
"study_id": "brca_tcga_pub"}
])
df2a
| uniquePatientKey | patientId | studyId | |
|---|---|---|---|
| 0 | VENHQS0zQy1BQUFVOmJyY2FfdGNnYQ | TCGA-3C-AAAU | brca_tcga |
| 1 | VENHQS0zQy1BQUxJOmJyY2FfdGNnYQ | TCGA-3C-AALI | brca_tcga |
| 2 | VENHQS1BMS1BMFNEOmJyY2FfdGNnYV9wdWI | TCGA-A1-A0SD | brca_tcga_pub |
| 3 | VENHQS1BMS1BMFNCOmJyY2FfdGNnYV9wdWI | TCGA-A1-A0SB | brca_tcga_pub |
df2b = pts.fetch_patients(unique_patient_keys=["VENHQS0zQy1BQUFVOmJyY2FfdGNnYQ",
"VENHQS1BMS1BMFNEOmJyY2FfdGNnYV9wdWI"], projection="DETAILED")
df2b
| uniquePatientKey | cancerStudy_name | cancerStudy_description | cancerStudy_publicStudy | cancerStudy_groups | cancerStudy_status | cancerStudy_importDate | cancerStudy_readPermission | cancerStudy_studyId | cancerStudy_cancerTypeId | cancerStudy_referenceGenome | patientId | studyId | cancerStudy_pmid | cancerStudy_citation | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | VENHQS0zQy1BQUFVOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-3C-AAAU | brca_tcga | NaN | NaN |
| 1 | VENHQS1BMS1BMFNEOmJyY2FfdGNnYV9wdWI | Breast Invasive Carcinoma (TCGA, Nature 2012) | Whole-exome sequencing (510 samples with match... | True | PUBLIC | 0 | 2023-06-21 17:11:52 | True | brca_tcga_pub | brca | hg19 | TCGA-A1-A0SD | brca_tcga_pub | 23000897 | TCGA, Nature 2012 |
df3 = pts.get_all_patients_in_study(study_id="brca_tcga", projection="DETAILED")
df3
| uniquePatientKey | cancerStudy_name | cancerStudy_description | cancerStudy_publicStudy | cancerStudy_groups | cancerStudy_status | cancerStudy_importDate | cancerStudy_readPermission | cancerStudy_studyId | cancerStudy_cancerTypeId | cancerStudy_referenceGenome | patientId | studyId | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | VENHQS1BUi1BMUFSOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-AR-A1AR | brca_tcga |
| 1 | VENHQS1CSC1BMUVPOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-BH-A1EO | brca_tcga |
| 2 | VENHQS1CSC1BMUVTOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-BH-A1ES | brca_tcga |
| 3 | VENHQS1CSC1BMUVUOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-BH-A1ET | brca_tcga |
| 4 | VENHQS1CSC1BMUVVOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-BH-A1EU | brca_tcga |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |
| 1096 | VENHQS1FMi1BMUI0OmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-E2-A1B4 | brca_tcga |
| 1097 | VENHQS1FMi1BMUI1OmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-E2-A1B5 | brca_tcga |
| 1098 | VENHQS1FMi1BMUI2OmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-E2-A1B6 | brca_tcga |
| 1099 | VENHQS1FMi1BMUJDOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-E2-A1BC | brca_tcga |
| 1100 | VENHQS1FMi1BMUJEOmJyY2FfdGNnYQ | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-E2-A1BD | brca_tcga |
1101 rows × 13 columns
df4 = pts.get_patient_in_study(patient_id="TCGA-3C-AAAU", study_id="brca_tcga")
df4
| cancerStudy_name | cancerStudy_description | cancerStudy_publicStudy | cancerStudy_groups | cancerStudy_status | cancerStudy_importDate | cancerStudy_readPermission | cancerStudy_studyId | cancerStudy_cancerTypeId | cancerStudy_referenceGenome | patientId | studyId | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | Breast Invasive Carcinoma (TCGA, Firehose Legacy) | TCGA Breast Invasive Carcinoma. Source data fr... | True | PUBLIC | 0 | 2023-11-09 17:45:45 | True | brca_tcga | brca | hg19 | TCGA-3C-AAAU | brca_tcga |