RodTracker.backend.rod_data

TBD

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: Optional[str] = None, frame: Optional[int] = 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

static extract_seen_information(data: Optional[DataFrame] = 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: Optional[List[int]] = None, colors: Optional[List[str]] = None, rods: Optional[List[int]] = None, callback: Optional[callable] = 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)

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: Union[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) –

update_color_2D(color: Optional[str] = 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: Optional[str] = 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, _: Optional[int] = 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(rod: Optional[int] = None)[source]

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

Parameters

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

update_rod_3D(rod: Optional[int] = 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

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: Optional[str] = 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