Patient Methods

The getPatients() method can provide insight to the patient metadata available in the NBIA database.

NBIAClient.getPatients(Collection: str = '', return_type: ReturnType | str | None = None) → List[dict[Any, Any]] | DataFrame

Retrieves a list of patients from the NBIA API.

Parameters:

• Collection (str, optional) – The name of the collection to filter the patients. Defaults to “”.

• return_type (Optional[Union[ReturnType, str]], optional) – The desired return type. Defaults to None.

Returns:

A list of patient dictionaries or a pandas DataFrame, depending on the return type.

Return type:

List[dict[Any, Any]] | pd.DataFrame

By default, the getPatients() method will return all patients in the NBIA database. However, the method can be filtered by Collection.

Python

Get all patientsFilter by Collection

with NBIAClient(return_type="dataframe") as client:
   patients = client.getPatients()

print(patients.head())

        PatientId PatientName  ... EthnicGroup PatientBirthDate
0  LIDC-IDRI-0001              ...         NaN              NaN
1  LIDC-IDRI-0002              ...         NaN              NaN
2  LIDC-IDRI-0003              ...         NaN              NaN
3  LIDC-IDRI-0004              ...         NaN              NaN
4  LIDC-IDRI-0005              ...         NaN              NaN

[5 rows x 9 columns]

For more granular filtering, the getPatientsByCollectionAndModality() method can be used to filter by Collection and Modality as both are required. Unlike the getPatients() method which returns additional metadata such as SpeciesCode, SpeciesDescription, PatientSex, and EthnicGroup, this method will only return a list of Patient IDs.

NBIAClient.getPatientsByCollectionAndModality(Collection: str, Modality: str, return_type: ReturnType | str | None = None) → List[dict[Any, Any]] | DataFrame

Retrieves patients by collection and modality.

Parameters:

• Collection (str) – The collection name.

• Modality (str) – The modality name.

• return_type (Optional[Union[ReturnType, str]], optional) – The desired return type. Defaults to None.

Returns:

The list of patients or a pandas DataFrame, depending on the return type.

Return type:

List[dict[Any, Any]] | pd.DataFrame

Raises:

AssertionError – If Collection or Modality is None.

Python

with NBIAClient(return_type="dataframe") as client:
   patients = client.getPatientsByCollectionAndModality(Collection = "TCGA-BLCA", Modality = "MR")

print(patients.head())

      PatientId
0  TCGA-4Z-AA87
1  TCGA-4Z-AA89
2  TCGA-ZF-AA4T
3  TCGA-ZF-AA4W
4  TCGA-ZF-A9RF

NBIAClient.getNewPatients(Collection: str, Date: str | datetime, return_type: ReturnType | str | None = None) → List[dict[Any, Any]] | DataFrame

Retrieves new patients from the NBIA API based on the specified collection and date.

Parameters:

• Collection (str) – The name of the collection to retrieve new patients from.

• Date (Union[str, datetime]) – The date to filter the new patients. Can be a string in the format “YYYY/MM/DD” or a datetime object.

• return_type (Optional[Union[ReturnType, str]]) – The desired return type. Defaults to None.

Returns:

A list of dictionaries or a pandas DataFrame containing the new patients.

Return type:

List[dict[Any, Any]] | pd.DataFrame

Raises:

AssertionError – If the Date argument is None.

The getNewPatients() method can be used to retrieve a list of patients that have been added to the NBIA database within a specified time frame.

Python

with NBIAClient(return_type="dataframe") as client:
    patients = client.getNewPatients(
        Collection="CMB-LCA",
        Date="2022/12/06",
    )

print(patients.head())

           PatientId        PatientName  ... SpeciesCode SpeciesDescription
0  CMB-LCA-MSB-04332  CMB-LCA-MSB-04332  ...   337915000       Homo sapiens
1  CMB-LCA-MSB-01649  CMB-LCA-MSB-01649  ...   337915000       Homo sapiens
2  CMB-LCA-MSB-02118  CMB-LCA-MSB-02118  ...   337915000       Homo sapiens
3  CMB-LCA-MSB-01413  CMB-LCA-MSB-01413  ...   337915000       Homo sapiens
4  CMB-LCA-MSB-00939  CMB-LCA-MSB-00939  ...   337915000       Homo sapiens

[5 rows x 8 columns]