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][source]

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][source]

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][source]

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[source]

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][source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

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