nbiatoolkit.nbia

Module Contents

Classes

NBIAClient

A client for interacting with the NBIA API.

Functions

downloadSingleSeries(SeriesInstanceUID, downloadDir, ...)

Downloads a single series from the NBIA server.

Attributes

__version__

nbiatoolkit.nbia.__version__ = '1.2.0'
nbiatoolkit.nbia.downloadSingleSeries(SeriesInstanceUID: str, downloadDir: str, filePattern: str, overwrite: bool, api_headers: dict[str, str], base_url: nbiatoolkit.utils.NBIA_BASE_URLS, log: logging.Logger, Progressbar: bool = False)[source]

Downloads a single series from the NBIA server.

Parameters:

  • SeriesInstanceUID (str) – The unique identifier of the series.

  • downloadDir (str) – The directory where the series will be downloaded.

  • filePattern (str) – The desired pattern for the downloaded files.

  • overwrite (bool) – Flag indicating whether to overwrite existing files.

  • api_headers (dict[str, str]) – The headers to be included in the API request.

  • base_url (NBIA_ENDPOINTS) – The base URL of the NBIA server.

  • log (Logger) – The logger object for logging messages.

  • Progressbar (bool, optional) – Flag indicating whether to display a progress bar. Defaults to False.

Returns:

True if the series is downloaded and sorted successfully, False otherwise.

Return type:

bool

class nbiatoolkit.nbia.NBIAClient(username: str = 'nbia_guest', password: str = '', log_level: str = 'INFO', logger: logging.Logger | None = None, return_type: nbiatoolkit.utils.ReturnType | str = ReturnType.LIST)[source]

A client for interacting with the NBIA API.

The NBIAClient class provides a high-level interface for querying the NBIA API and downloading DICOM series.

Parameters:

  • username (str, optional) – The username for authentication. Defaults to “nbia_guest”.

  • password (str, optional) – The password for authentication. Defaults to an empty string.

  • log_level (str, optional) – The log level for the logger. Defaults to “INFO”.

  • return_type (Union[ReturnType, str], optional) – The return type for API responses. Defaults to ReturnType.LIST

OAuth_client

The OAuth2 client used for authentication.

Type:

OAuth2

headers

The API headers.

Type:

dict[str, str]

base_url

The base URL for API requests.

Type:

NBIA_ENDPOINTS

logger

The logger for logging client events.

Type:

Logger

return_type

The current return type for API responses.

Type:

str

property OAuth_client: nbiatoolkit.auth.OAuth2
property headers
property base_url: nbiatoolkit.utils.NBIA_BASE_URLS
property logger: logging.Logger
property return_type: str
__enter__()[source]
__exit__(exc_type, exc_value, traceback) → None[source]
_get_return(return_type: nbiatoolkit.utils.ReturnType | str | None) → nbiatoolkit.utils.ReturnType[source]

helper function to replace the following code: returnType: ReturnType = (

ReturnType(return_type) if return_type is not None else self._return_type

)

query_api(endpoint: nbiatoolkit.utils.NBIA_ENDPOINTS, params: dict = {}) → List[dict[Any, Any]][source]
getCollections(prefix: str = '', return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]

Retrieves the collections from the NBIA server.

Parameters:

  • prefix (str, optional) – Prefix to filter the collections by. Defaults to “”.

  • return_type (Optional[Union[ReturnType, str]], optional) – Return type of the response. Defaults to None which uses the default return type.

Returns:

List of collections or DataFrame containing the collections.

Return type:

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

getCollectionDescriptions(collectionName: str, return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]

Retrieves the description of a collection from the NBIA server.

Parameters:

  • collectionName (str) – The name of the collection.

  • return_type (Optional[Union[ReturnType, str]], optional) – Return type of the response. Defaults to None.

Returns:

List of collection descriptions or DataFrame containing the collection descriptions.

Return type:

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

getCollectionPatientCount(prefix: str = '', return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]

Retrieves the patient count for collections.

Parameters:

  • prefix (str, optional) – Prefix to filter the collections by. Defaults to “”.

  • return_type (Optional[Union[ReturnType, str]], optional) – Return type of the response. Defaults to None which uses the default return type.

Returns:

List of collections and their patient counts or DataFrame containing the collections and their patient counts.

Return type:

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

getModalityValues(Collection: str = '', BodyPartExamined: str = '', Counts: bool = False, return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]

Retrieves possible modality values from the NBIA database.

Parameters:

  • Collection (str, optional) – Collection name to filter by. Defaults to “”.

  • BodyPartExamined (str, optional) – BodyPart name to filter by. Defaults to “”.

  • Counts (bool, optional) – Flag to indicate whether to return patient counts. Defaults to False.

  • return_type (Optional[Union[ReturnType, str]], optional) – Return type of the response. Defaults to None which uses the default return type.

Returns:

List of modality values or DataFrame containing the modality values.

Return type:

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

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

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

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

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.

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

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.

getBodyPartCounts(Collection: str = '', Modality: str = '', return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]
getStudies(Collection: str, PatientID: str = '', StudyInstanceUID: str = '', return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]

Retrieves studies from the NBIA API based on the specified parameters.

Parameters:

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

  • PatientID (str, optional) – The patient ID to filter the studies by. Defaults to “”.

  • StudyInstanceUID (str, optional) – The study instance UID to filter the studies by. Defaults to “”.

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

Returns:

A list of dictionaries or a pandas DataFrame containing the retrieved studies.

Return type:

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

getSeries(Collection: str = '', PatientID: str = '', StudyInstanceUID: str = '', Modality: str = '', SeriesInstanceUID: str = '', BodyPartExamined: str = '', ManufacturerModelName: str = '', Manufacturer: str = '', return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]
getSeriesMetadata(SeriesInstanceUID: str | list[str], return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]
getNewSeries(Date: str | datetime.datetime, return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]
getDICOMTags(SeriesInstanceUID: str, return_type: nbiatoolkit.utils.ReturnType | str | None = None) → List[dict[Any, Any]] | pandas.DataFrame[source]
getRefSeriesUIDs(SeriesInstanceUID: str) → List[str][source]
generateFilePathFromDICOMTags(SeriesInstanceUID: str, filePattern: str = '%PatientName/%Modality-%SeriesNumber-%SeriesInstanceUID/%InstanceNumber.dcm') → str[source]

Generates a file path from DICOM tags.

Parameters:

  • SeriesInstanceUID (str) – The Series Instance UID of the DICOM series.

  • filePattern (str, optional) – The file pattern to use for generating the file path. Defaults to “%PatientName/%Modality-%SeriesNumber-%SeriesInstanceUID/%InstanceNumber.dcm”.

Returns:

The generated file path.

Return type:

str

Note

This only considers the first instance of the series. Meant to be used to determine the dirname of the series files.

downloadSeries(SeriesInstanceUID: str | list, downloadDir: str = './NBIA-Download', filePattern: str = '%PatientName/%Modality-%SeriesNumber-%SeriesInstanceUID/%InstanceNumber.dcm', overwrite: bool = False, nParallel: int = 1, Progressbar: bool = False) → bool[source]
parsePARAMS(params: dict) → dict[source]