ukbppp_dl.common

Common utility functions for the ukbppp_dl package.

Functions

delete_files(filenames[, verbose])

Delete files from disk.

download_from_synapse(synapse_id[, ...])

Download a Synapse file unless it already exists locally.

save_log(log_fname, log_dict[, overwrite, ...])

Save a JSON log file and optionally rename it when a file exists.
ukbppp_dl.common.save_log(log_fname: str, log_dict: dict[str, Any], overwrite: bool = False, add_date: bool = True, new_name: bool = False, verbose: bool = False) → str | None

Save a JSON log file and optionally rename it when a file exists.

Parameters:

  • log_fname (str) – Target file path for the log file, typically a .json filename.

  • log_dict (dict[str, Any]) – Dictionary of log metadata to serialize. Typical keys include run parameters, status flags, and summary values. The log_filename key is added or updated before writing.

  • overwrite (bool, default=False) – Whether to overwrite an existing log file at log_fname.

  • add_date (bool, default=True) – Whether to append a YYYY-MM-DD--HH:MM:SS timestamp to the filename before saving.

  • new_name (bool, default=False) – Whether to create a new timestamped filename when log_fname already exists and overwrite is False.

  • verbose (bool, default=False) – Whether to print status messages during save operations.

Returns:

The final log filename that was written, or None if saving was skipped.

Return type:

str | None

ukbppp_dl.common.delete_files(filenames: list[str | None], verbose: bool = False) → int

Delete files from disk.

Parameters:

  • filenames (list[str | None]) – File paths to delete. Typical elements are string paths, with None values ignored.

  • verbose (bool, default=False) – Whether to print deletion messages.

Returns:

Number of files successfully deleted.

Return type:

int

ukbppp_dl.common.download_from_synapse(synapse_id: str, download_location: str = './ukb_ppp_dl/data', login_kwargs: dict[str, Any] = {}, verbose: bool = False) → tuple[str, bool]

Download a Synapse file unless it already exists locally.

Parameters:

  • synapse_id (str) – Synapse entity ID for the file to download.

  • download_location (str, default="./ukb_ppp_dl/data") – Directory where the file should be stored. Typical values are local project data folders.

  • login_kwargs (Dict[str, Any], optional) –

    Keyword arguments forwarded to synapseclient.Synapse.login(). Common keys include "authToken" (str), "email" (str) and "profile" (str). See synapseclient.Synapse.login() for more information.

    Alternatively, you can configure your Synapse credentials in a .synapseConfig file and leave this argument empty to use the default login behaviour. You can find more information about .synapseConfig in the Synapse documentation.

  • verbose (bool, default=False) – Whether to print status messages about login and download decisions.

Returns:

A tuple containing the expected or downloaded file path and a boolean flag indicating whether the download was skipped because the file already existed.

Return type:

tuple[str, bool]