RodTracker.backend.rod_data

Main classes and methods used in RodTracked for manipulation with particles coordinate data.

Author: Adrian Niemann (adrian.niemann@ovgu.de)

Date: 2022-2024

rod_data

Stores loaded/generated position data of rods. The column naming must comply with DEFAULT_COLUMNS for most functions to work as intended.

Type:

DataFrame | None

lock

Lock to protect access to rod_data during read and write operations.

Type:

QReadWriteLock

POSITION_SCALING: float = 1.0

Scale factor for loaded position data.

Type:

float

RE_2D_POS: Pattern = re.compile('[xy][12]_.+')

Pattern for columns containing 2D position information.

Type:

Pattern

RE_3D_POS: Pattern = re.compile('[xyz][12]')

Pattern for columns containing 3D position information.

Type:

Pattern

RE_COLOR_DATA: Pattern = re.compile('rods_df_\\w+\\.csv')

Pattern how the rod position data file names are expected.

Type:

Pattern

RE_SEEN: Pattern = re.compile('seen_.+')

Pattern for columns indicating a particle’s seen status.

Pattern for column names in the rod position data indicating whether a particle was seen in the a specific camera.

Type:

Pattern

class RodData(*args, **kwargs)[source]

Bases: QObject

Object for rod position data management.

A RodData object handles the loading, selection, changing and saving of rod position data, that are meant to be displayed by RodImageWidget and View3D objects.

Parameters:

  • *args (iterable) – Positional arguments for the QObject superclass.

  • **kwargs (dict) – Keyword arguments for the QObject superclass.

Signals

Slots

folder

Path to the folder the position data is loaded from.

Type:

Path | None

out_folder

Path to the (automatically) selected folder for later output of the corrected dataset.

Type:

Path | None

threads

Thread pool for asynchronous tasks.

Type:

QThreadPool

frame

Frame number of the currently provided position data.

Type:

int | None

color_2D

Color of the currently provided 2D position data.

Type:

str | None

color_3D

Color of the currently provided 3D position data. None, if all colors are provided.

Type:

str | None

rod_2D

Rod number of the corrently provided 2D position data. None, if all rods are provided.

Type:

str | None

rod_3D

Rod number of the corrently provided 3D position data. None, if all rods are provided.

Type:

str | None

cols_2D

Columns of the loaded DataFrame relevant for 2D data display.

Type:

List[str]

cols_3D

Columns of the loaded DataFrame relevant for 3D data display.

Type:

List[str]

add_data(data: DataFrame)[source]

Integrates new rod position data into the main data.

This method is mainly for receiving newly created position data, i.e. automatically generated data. There are four distinct situations this function is intended for:

  • Receiving detection results without having any data loaded yet.

  • Receiving detection results for a camera (ID) that is not yet present in the loaded data.

  • Receiving detection results for frames that are not yet part of the loaded dataset.

  • Receiving automatic detection results that must be integrated into the already existing dataset, potentially overwriting data.

Parameters:

data (DataFrame) – New (automatically generated) data, that needs to be integrated into the (potentially not existing) dataset.

Hint

Emits

See also

catch_data(), catch_number_switch()

batch_update

Send update for seen tree for multiple changed or new particles.

See also

batch_update_tree(), extract_seen_information()

Type:

pyqtSignal(dict, list)

catch_data(change: Action) → None[source]

Change the loaded data according to the performed Action.

Change the loaded data according to the performed Action and notify other objects about this update.

Parameters:

change (Action)

Hint

Emits

catch_number_switch(mode: NumberChangeActions, old_id: int, new_id: int, cam_id: str, color: str | None = None, frame: int | None = None)[source]

Change of rod numbers for more than one frame or camera.

Exchanges rod numbers in more than one frame or camera according to the given mode.

Parameters:

  • mode (NumberChangeActions) –

    Possible modes are:

    • ALL,

    • ALL_ONE_CAM, and

    • ONE_BOTH_CAMS.

  • old_id (int)

  • new_id (int)

  • cam_id (str)

  • color (str, optional) – By default None.

  • frame (int, optional) – By default None.

clean_data()[source]

Deletes unused rods from the loaded dataset.

Unused rods are identified by not having positional data in the gp_ columns of the dataset. This assumed when only NaN or 0 is present in all these columns for a given rod/row. The user is asked to confirm these deletions and has the opportunity to exclude identified candidates from deletion. All confirmed rows are then deleted from the main dataset in RAM and therefore propagated to disk on the next saving operation.

Returns:

None

data_2d

Provide 2D rod position data for other objects to display, defined by frame, color_2D, and rod_2D.

Type:

pyqtSignal

data_3d

Provide 2D rod position data for other objects to display, defined by frame, color_3D, and rod_3D.

Type:

pyqtSignal[DataFrame]

data_loaded

Propagates information about loaded position data.

  • [Path, Path, list]:

    The payload is the folder the loaded data is read from, the folder any data changes will be written to (at that moment), and a list of the rod colors found during reading of the data.

  • [list]:

    The payload is a list of the rod colors found during reading of the data.

  • [int, int, list]:

    The payload is the lowest and highest frame and the rod colors found during reading of the data.

  • [str, str]:

    The payload are the camera IDs that have been identified during reading of the data.

Type:

pyqtSignal

data_update

Notify objects about updates in the 'seen'/'unseen' status of rods.

dict -> Information about the rod, whos 'seen' status has changed.

Mandatory keys: "frame", "cam_id", "color", "seen", "rod_id"

Type:

pyqtSignal

delete_data(frame: int | None = None, particle_class: str | None = None, particle: int | None = None, all: bool = False)[source]

Delete parts of the currently loaded position data.

Parameters:

  • frame (Union[int, None], optional) – Frame on which to delete data. The currently displayed frame is chosen, if none is given. By default None.

  • particle_class (Union[str, None], optional) – Class of particles to delete on the given frame. All available classes are deleted if None is given. By default None.

  • particle (Union[int, None], optional) – TBD (meant for deletion of particular particles - not used at the moment) By default None.

  • all (bool, optional) – Flag whether to delete all currently loaded data. By default False.

static extract_seen_information(data: DataFrame | None = None) → Tuple[Dict[int, Dict[str, Dict[int, list]]], list][source]

Extracts the seen/unseen parameter for all rods in rod_data.

Returns:

  • Dict[int, Dict[str, Dict[int, list]]] – Frame[Color[RodNo.]] -> out[501]["red"][1] = ["seen", "unseen"]

  • list – out_list = ["gp1_seen", "gp2_seen"]

static find_unused_rods() → DataFrame[source]

Searches for unused rods in the rod_data dataset.

Marks and returns unused rods by verifying that the columns _gp in the dataset contain only 0 or NaN.

Returns:

DataFrame – The rows from the given dataset that were identified as not being used.

static folder_has_data(path: Path) → bool[source]

Checks a folder for file(s) that match the rod position data naming.

Parameters:

path (Path) – Folder path that shall be checked for files matching the pattern in RE_COLOR_DATA.

Returns:

bool – True, if at least 1 file matching the pattern was found. False, if no file was found or the folder does not exist.

Raises:

NotADirectoryError – Is raised if the given path exists but is not a directory.

static get_color_data(read_dir: Path) → Tuple[DataFrame, List[str]][source]

Reads rod data files from a directory.

Checks all *.csv files for the rod data naming convention (see RE_COLOR_DATA), loads and concatenates them, and extracts the corresponding color from the file names.

Parameters:

read_dir (str) – Path to the directory to read position data files from.

Returns:

Tuple[DataFrame, List[str]] – Concatenated dataset and list of all found colors.

get_data(frames: List[int] | None = None, colors: List[str] | None = None, rods: List[int] | None = None, callback: callable | None = None, data_2d: bool = True, data_3d: bool = True) → DataFrame[source]

Get part of the loaded rod position data.

Parameters:

  • frames (List[int], optional) – List of frames to select from the loaded dataset. All are returned, if no list is given. By default None.

  • colors (List[str], optional) – List of colors to select from the loaded dataset. All are returned, if no list is given. By default None.

  • rods (List[int], optional) – List of rod numbers to select from the loaded dataset. All are returned, if no list is given. By default None.

Returns:

pd.DataFrame – Copy of a slice of the loaded data.

Hint

Emits

is_busy

Notifies when a background task is started/finished.

Type:

pyqtSignal(bool)

property logger: ActionLogger
open_rod_folder(chosen_folder: Path) → bool[source]

Attempts to open a folder with potential rod position data.

It is evaluated which files in the folder are valid data files and what colors they describe. The data discovery/loading is logged.

Parameters:

chosen_folder (Path) – Path to a folder with files in the format of RE_COLOR_DATA.

Returns:

bool – True, if loading successful. False, if loading aborted.

Hint

Emits

provide_data(data_2d: bool = True, data_3d: bool = True)[source]

Slice the loaded DataFrame and send update signals for 2D/3D data.

Slice the loaded data according to frame, color_2D, rod_2D, color_3D, rod_3D and send signals with this payload for 2D and 3D display.

Parameters:

  • data_2d (bool, optional) – Flag, whether to send 2D data. By default True.

  • data_3d (bool, optional) – Flag, whether to send 3D data. By default True.

Hint

Emits

receive_updated_data(data: DataFrame)[source]

Receives an updated part of the rod position data.

Integrates the received rod position data into the previously loaded dataset, i.e. replacing updated data and appending new data.

Parameters:

data (DataFrame) – Updated/New rod position data

requested_data

Sends a requested rod position data slice.

Type:

pyqtSignal(DataFrame)

save_changes(temp_only: bool = False)[source]

Saves the currently loaded (and altered) position data to disk.

Saves the loaded data with changes made in all views to disk. A warning is issued, if the user tries to overwrite the original data files and they can decide to actually overwrite it or are given a chance to change the output folder.

Parameters:

temp_only (bool) –

Flag to either save to the temporary files only or permanently to the (user-)chosen location.

Default is False.

Hint

Emits

saved

Notify objects, that all changed data has been saved successfully.

Type:

pyqtSignal

seen_loaded

Information of the rod dataset about a rod being 'seen' or 'unseen' for display as a tree.

Dict[int, Dict[str, Dict[int, list]]] -> (frame, color, particle, camera)

list -> List of ‘camera’ IDs on which a rod can be 'seen'/'unseen'

Type:

pyqtSignal

select_rods(pre_selection: str = '')[source]

Lets the user select a folder with rod position data.

Lets the user select a folder with rod position data. The selected folder is probed for eligable files and the user can otherwise try the selection again. After that an attempt to loading the data is started, if that fails, users can try to open another directory.

Parameters:

pre_selection (str) –

Path to a folder that the QFileDialog is attempted to be opened with. By default and as a fallback the current working directory is used.

Default is "".

Returns:

None

set_out_folder(new_folder: str | Path)[source]

Set the output folder for data saving.

Parameters:

new_folder (str | Path)

property show_2D: bool

Flag, whether to send updates of 2D rod data.

Returns:

bool

property show_3D: bool

Flag, whether to send updates of 3D rod data.

Returns:

bool

timerEvent(event: QEvent)[source]

Handle timer events.

Handles QTimerEvent, i.e. those that indicate the request for saving the currently loaded data automatically.

Parameters:

event (QtCore.QEvent)

undo_action(action: Action) → None[source]

Reverts an Action performed on the loaded data.

Parameters:

action (Action) – An Action that was logged previously. It will only be reverted, if it associated with this object.

update_color_2D(color: str | None = None)[source]

Update the color for 2D data sending and trigger sending of 2D data.

Parameters:

color (str | None) – Color to display in 2D. Default is None.

update_color_3D(color: str | None = None, send: bool = True)[source]

Update the color for 3D data sending(, trigger sending of 3D data).

Parameters:

  • color (str | None) – Color to display in 3D. If no color is given all colors are selected. Default is None.

  • send (bool) – Flag, whether to send a signal with the updated 3D data. Default is True.

update_frame(frame: int, _: int | None = None)[source]

Update the frame for data sending and trigger data sending.

Parameters:

  • frame (int) – Frame to send data for.

  • _ (int) – Index of the frame in the loaded dataset. Is not used here and just there to match a signal signature.

update_rod_2D(class_ID: str | None = None, rod_ID: int | None = None)[source]

Update the rod for 2D data sending and trigger sending of 2D data.

Parameters:

  • class_ID (str | None) – Class (rod color) to display in 2D. If no class is given all classes are selected. Default is None.

  • rod_ID (int | None) – Rod number to display in 2D. If no number is given all rods are selected. Default is None.

update_rod_3D(rod: int | None = None, send: bool = True)[source]

Update the rod for 3D data sending(, trigger sending of 3D data).

Parameters:

  • rod (int | None) – Rod number to display in 3D. If no number is given all rods are selected. Default is None.

  • send (bool) – Flag, whether to send a signal with the updated 3D data. Default is True.

update_settings(settings: dict)[source]

Catches updates of the settings from a Settings class.

Checks for the keys relevant to itself and updates the corresponding attributes. Redraws itself with the new settings in place, if settings were changed.

Parameters:

settings (dict)

Returns:

None

update_tree_data() → None[source]

Update the seen values of the currently loaded data for display as a tree.

change_data(new_data: dict) → None[source]

Changes or extends the rod_data dataset with the given new data.

Parameters:

new_data (dict) – Dictionary describing the new/changed rod data. Must contain the fields "frame", "cam_id", "color", "position", "rod_id".

rod_number_swap(mode: NumberChangeActions, previous_id: int, new_id: int, color: str, frame: int, cam_id: str | None = None) → DataFrame[source]

Change of rod numbers for more than one frame or camera.

Exchanges rod numbers in more than one frame or camera according to the given mode.

Parameters: