dosertools.file_handling package — dosertools 2022 documentation

# dosertools.file_handling package

## Submodules

## dosertools.file_handling.folder module

dosertools.file_handling.folder.identify_background_video_folder(parent_folder: Union[str, bytes, os.PathLike], fname: str, fname_format: str, optional_settings: dict = {}) → Tuple[bool, str]

  Identifies a background folder that matches a given experimental fname.

  Identifies a background folder tagged with appropriate parameters such that it matches the given base folder name for an experimental video.

  Parameters

    - parent_folder (path-like) – Path in which to look for background video folders.

    - fname (str) – The base name of the experimental video folder. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. Must contain the “vtype” tag. ex. “date_sampleinfo_fps_run_vtype”

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - fname_split (string) – The deliminator for splitting folder/file names, used in fname_format. Default is “_”.

    - background_tag (string) – The tag for identifying background videos. May not be empty. Default is “bg”.

    - one_background (bool) – True to use one background for a group of experiments only differing by run number. False to pair backgrounds and experiments 1:1. Default is False.

  Returns

    - matched_bg (bool) – True if a matching background is found, False otherwise.

    - bg_folder (string) – Name of background folder if a matching one is found, ‘’ otherwise.

  Raises

    ValueError – If the given fname_format does not contain the tag “vtype.”

  Warns

    UserWarning – If multiple matched backgrounds are found for a given fname.

dosertools.file_handling.folder.identify_experimental_video_folder(folder: str, fname_format: str, optional_settings: dict = {}) → Tuple[str, bool]

  Identifies if a given folder is an experimental video folder.

  Using the given fname_format, identifies if the given folder is an experimental video folder.

  Parameters

    - folder (str) – Folder to check if it matches the format for the experimental video.

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. Must contain the “vtype” tag. ex. “date_sampleinfo_fps_run_vtype”

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - fname_split (string) – The deliminator for splitting folder/file names, used in fname_format. Default is “_”.

    - experiment_tag (string) – The tag for identifying experimental videos. May be empty (“”). Default is “exp”.

  Returns

    - fname (string) – Base name of the folder if the given folder matches the pattern for an experimental folder, ‘’ otherwise.

    - exp_video (bool) – True if the folder matches the pattern for an experimental folder, False otherwise.

  Raises

    ValueError – If the given fname_format does not contain the tag “vtype.”:

dosertools.file_handling.folder.make_destination_folders(save_location: Union[str, bytes, os.PathLike], optional_settings: dict = {}) → Tuple[bool, bool, bool]

  Creates destination folders for binary files (crop and bg_sub optional)

  Creates the folder save_location if it does not yet exist, then within save_location makes the folder ‘bin’ (additionally ‘crop’ and ‘bg_sub’ if those optional settings are True). Warns if any of the folders already exist. Returns True for folders that exist or do not need to be created because of optional_settings.

  Parameters

    save_location (path-like) – Path to folder in which to save the sub folders. If it does not exist, function will create it (as long as rest of path already exists).

  Optional Settings and Defaults

    - save_crop (bool) – True to save intermediate cropped images (i.e. experimental video images cropped but not background-subtracted or binarized). Default is False.

    - save_bg_sub (bool) – True to save background-subtracted images (i.e. experimental video images cropped and background-subtracted but not binarized). Default is False.

  Returns

    - bin_exists (bool) – True if binary folder already exists, False if does not exist

    - crop_exists (bool) – True if save_crop is True or crop folder already exists, False otherwise

    - bg_sub_exists (bool) – True if save_bg_sub is True or bg_sub folder already exists, False otherwise

dosertools.file_handling.folder.make_folder(save_location: Union[str, bytes, os.PathLike], folder_tag: str) → bool

  Creates directory in save_location, returns False if already exists

  Parameters

    - save_location (path-like) – path to folder in which to save the sub folders

    - folder_tag (str) – sub folder name

  Returns

    make_folder (bool) – returns True if makes directory, False if it already exists

dosertools.file_handling.folder.select_video_folders(parent_folder: Union[str, bytes, os.PathLike], fname_format: str, optional_settings: dict = {}) → Tuple[list, list, list]

  Pairs experimental and background videos in a given folder.

  Iterates through every folder in a given folder, checks if the folder matches the pattern for an experimental video folder, looks for a matching background video folder if it is, and returns three matched lists, a list of base folder names, a list of paths to experimental video folders, and a list of paths to background video folders.

  Parameters

    - parent_folder (path-like) – Path in which to look for experimental and background video folder pairs.

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. Must contain the “vtype” tag. ex. “date_sampleinfo_fps_run_vtype”

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - fname_split (string) – The deliminator for splitting folder/file names, used in fname_format. Default is “_”.

    - experiment_tag (string) – The tag for identifying experimental videos. May be empty (“”). Default is “exp”.

    - background_tag (string) – The tag for identifying background videos. May not be empty. Default is “bg”.

    - one_background (bool) – True to use one background for a group of experiments only differing by run number. False to pair backgrounds and experiments 1:1. Default is False.

  Returns

    - fnames (list of strings) – List of base folder names for each matched pair of experimental and background folders.

    - exp_videos (list of paths) – List of paths to experimental video folders that were matched with backgrounds.

    - bg_videos (list of paths) – List of paths to background video folders matched with exp_videos.

  Examples

## dosertools.file_handling.tags module

dosertools.file_handling.tags.check_fname_format_for_tag(fname_format: str, tag: str, fname_split: str = '_') → bool

  Checks if given tag is in a given fname_format string.

  Parameters

    - fname_format (str) – The format of a fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to check for in fname_format.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    check_fname_format_for_tag (bool) – Returns True if fname_format contains tag, False otherwise.

dosertools.file_handling.tags.get_tag_from_fname(fname: str, fname_format: str, tag: str, fname_split: str = '_') → list

  Returns value(s) of given tag in fname.

  Parameters

    - fname (str) – The name of the file/folder to get values of a tag from. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to get values for from fname.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    get_tag_from_fname (list of strings) – List of values in fname corresponding to each occurence of given tag in fname_format.

dosertools.file_handling.tags.identify_tag_in_fname_format(fname_format: str, tag: str, fname_split: str = '_') → list

  Identifies indices of a tag in a given fname_format.

  Parameters

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to identify in fname_format.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    identify_tag_in_fname_format (list of integers) – Indices of given tag in fname_format. Empty if tag not present.

dosertools.file_handling.tags.insert_tag_in_fname(fname: str, fname_format: str, tag: str, value: str, fname_split: str = '_') → list

  Insert tag into fname with given value.

  Parameters

    - fname (str) – The name of the file/folder to insert value in. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to insert in fname.

    - value (str) – String to insert at location of given tag in fname.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    insert_tag_from_fname (list of strings) – Inputted tag with given value inserted at location of given tag in fname_format

dosertools.file_handling.tags.parse_fname(fname: str, fname_format: str, sampleinfo_format: str, optional_settings: dict = {}) → dict

  Parses folder/file names into a dictonary of parameters using supplied format.

  Parameters

    - fname (str) – The name of the file/folder to parse. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - sampleinfo_format (str) – The format of the sampleinfo section of the fname separated by the deliminator specified by sample_split.

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    - fname_split (string) – The deliminator for splitting folder/file names, used in fname_format. Default is “_”.

    - sample_split (string) – The deliminator for splitting sampleinfo tag in folder/file names, used in sampleinfo_format. Default is “-“.

  Returns

    parse_fname (dict) – Dictionary of parameters from fname.

dosertools.file_handling.tags.remove_tag_from_fname(fname: str, fname_format: str, tag: str, fname_split: str = '_') → str

  Removes given tag from a folder/file name.

  Parameters

    - fname (str) – The name of the file/folder to remove a tag from. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to remove from fname.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    remove_tag_from_fname (str) – Inputted fname with every occurence of given tag removed.

  Warns

    UserWarning – Returns a warning if the given tag is not present.

  Examples

  fname: “20210929_6M-PEO_fps-25k_1” fname_format: “date_sampleinfo_fps_run” tag: “run” result: “20210929_6M-PEO_fps-25k”

  fname: “20210929_6M-PEO_fps-25k_1_2503_2354” fname_format: “date_sampleinfo_fps_run_remove_remove” tag: “remove” result: “20210929_6M-PEO_fps-25k_1”

  fname: “20210929_6M-PEO_fps-25k_1” fname_format: “date_sampleinfo_fps_run” tag: “remove” result: “20210929_6M-PEO_fps-25k_1” and warning

dosertools.file_handling.tags.replace_tag_in_fname(fname: str, fname_format: str, tag: str, value: str, fname_split: str = '_') → str

  Replace value(s) of given tag in fname with given value.

  Parameters

    - fname (str) – The name of the file/folder to replace values in. ex. “20210929_6M-PEO_fps-25k_1”

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - tag (str) – Tag to replace in fname.

    - value (str) – String to use to replace value of given tag in fname.

    - fname_split (str, optional) – The deliminator for splitting the fname (default is “_”).

  Returns

    replace_tag_in_fname (string) – Inputted fname with every occurence of the given tag replaced with given value

dosertools.file_handling.tags.shorten_fname_format(fname_format: str, optional_settings: dict = {}) → str

  Shortens the fname_format to remove the “vtype” and “remove” tags.

  Parameters

    - fname_format (str) – The format of the fname with parameter names separated by the deliminator specified by fname_split. ex. “date_sampleinfo_fps_run”

    - optional_settings (dict) – A dictionary of optional settings.

  Optional Settings and Defaults

    fname_split (string) – The deliminator for splitting folder/file names, used in fname_format. Default is “_”.

  Returns

    shorten_fname_format (str) – fname_format with “vtype” and “remove” tags removed.

## Module contents