diff --git a/docs/InitializeClient.rst b/docs/InitializeClient.rst index 3553e70..3dcc207 100644 --- a/docs/InitializeClient.rst +++ b/docs/InitializeClient.rst @@ -1,6 +1,10 @@ -Initialize Client +Setup ----------------- -By default, nbiatoolkit uses the guest account to access all collections in the API that are publicly available. + +Initialize Client +^^^^^^^^^^^^^^^^^ + +By default, the `NBIAClient` uses the guest account to access all collections in the API that are publicly available. If you have a user account that has been granted specific access to a collection, you can use your credentials to initialize the client when performing a query. @@ -71,11 +75,58 @@ This is especially useful when using the client in a script with a predefined sc The context manager is not available in the command line interface. +Return Types of Methods +^^^^^^^^^^^^^^^^^^^^^^^ +By default, most functions that query the API for metadata will return a list of dictionaries. +Available return types are made available through the `ReturnType` Enum which can be passed in as a parameter, +or its string representation. The available options as of writing are "list", and "dataframe". + +If you would like to return the data as a pandas DataFrame, you can pass the +`return_type` argument to the respective class method: + +.. tabs:: + + .. tab:: Python + + .. code-block:: python + + from nbiatoolkit import NBIAClient + from nbiatoolkit.utils import ReturnType + + client = NBIAClient() + client.getCollections(prefix='TCGA', return_type='dataframe') + # equivalent to + client.getCollections(prefix='TCGA', return_type=ReturnType.DATAFRAME) + + .. tab:: Command Line + + Return types are not yet available in the command line interface. + Feel free to open an issue on the GitHub repository if you would like to see this feature added. + + +Alternatively, you can set the return type for all methods by passing the `return_type` argument to the NBIAClient class. + +.. tabs:: + + .. tab:: Python + + .. code-block:: python + + from nbiatoolkit import NBIAClient + + client = NBIAClient(return_type='dataframe') + client.getCollections(prefix='TCGA') + + .. tab:: Command Line + + Return types are not yet available in the command line interface. + Feel free to open an issue on the GitHub repository if you would like to see this feature added. + Logging ^^^^^^^ The client can be initialized with a log level to control the verbosity of the logs. This is primarily intended for debugging and development purposes. -The default log level is 'INFO' and the available log levels are 'DEBUG', 'INFO', 'WARNING', 'ERROR'. +The default log level is 'INFO' and the available log levels are `DEBUG`, `INFO`, `WARNING`, `ERROR`. .. tabs:: @@ -85,9 +136,10 @@ The default log level is 'INFO' and the available log levels are 'DEBUG', 'INFO' from nbiatoolkit import NBIAClient - client = NBIAClient(log_level='DEBUG) + client = NBIAClient(log_level='DEBUG') client.getCollections(prefix='TCGA') .. tab:: Command Line - Logging is not yet available in the command line interface. Feel free to open an issue on the GitHub repository if you would like to see this feature added. + Logging is not yet available in the command line interface. + Feel free to open an issue on the GitHub repository if you would like to see this feature added. diff --git a/docs/markdowns/Installation.md b/docs/markdowns/Installation.md index 3f359a9..159d3f4 100644 --- a/docs/markdowns/Installation.md +++ b/docs/markdowns/Installation.md @@ -1,9 +1,8 @@ # Installation -> [!WARNING] -> `nbiatoolkit` is currently under development and is not guaranteed to be stable. -> Please refer to the [1.0.0 Stable Release Milestone](https://github.com/jjjermiah/nbia-toolkit/milestone/1) for the roadmap -> to the first stable release. +`nbiatoolkit` is currently under development and is not guaranteed to be stable. +Please refer to the [1.0.0 Stable Release Milestone](https://github.com/jjjermiah/nbia-toolkit/milestone/1) for the roadmap +to the first stable release. ## PyPi diff --git a/src/nbiatoolkit/nbia.py b/src/nbiatoolkit/nbia.py index 158a3bd..978ece8 100644 --- a/src/nbiatoolkit/nbia.py +++ b/src/nbiatoolkit/nbia.py @@ -36,6 +36,20 @@ def conv_response_list( response_json: List[dict[Any, Any]], return_type: ReturnType, ) -> List[dict[Any, Any]] | pd.DataFrame: + """ + Convert a response JSON to a list or a pandas DataFrame based on the specified return type. + + Args: + response_json (List[dict[Any, Any]]): The response JSON to be converted. + return_type (ReturnType): The desired return type (LIST or DATAFRAME). + + Returns: + List[dict[Any, Any]] | pd.DataFrame: The converted response in the specified return type. + + Raises: + AssertionError: If the response JSON is not a list. + + """ assert isinstance(response_json, list), "The response JSON must be a list" if return_type == ReturnType.LIST: @@ -53,7 +67,21 @@ def downloadSingleSeries( base_url: NBIA_ENDPOINTS, log: Logger, ): - + """ + Downloads a single series from the NBIA server. + + Args: + 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. + + Returns: + bool: True if the series is downloaded and sorted successfully, False otherwise. + """ # create query_url query_url: str = base_url.value + NBIA_ENDPOINTS.DOWNLOAD_SERIES.value