utils

Functions

`calculate_active_hours`(df)	Calculates the total active hours for different entities based on a DataFrame.
`change_directory_settings`(new_path)	Update all directory settings based on a new project root path.
`change_system_directory_settings`()	Updates the system directory setting and renames the directory if it changed.
`create_directories`()	Create all necessary system directories if they do not exist.
`create_directories_from_path`(p)	Creates a standard directory structure rooted at the given path.
`create_pixmap`(fig)	Creates a QPixmap from a matplotlib Figure.
`delete_all_elements_from_layout`(layout)	Recursively removes all widgets and sub-layouts from a QLayout.
`download_github_repositories`(repositories)	Clone a list of GitHub repositories into the user's village_projects directory.
`get_x_value_interp`(x, y, y_target)	Find the x-value corresponding to a target y-value using interpolation.
`has_low_disk_space`([threshold_gb])	Checks if the root partition has low disk space.
`interpolate`(x, y[, points])	Perform PCHIP interpolation on specific data points.
`is_active`(value)	Check if a schedule string dictates activity at the current time.
`is_active_regular`(value)	Checks if the current day allows activity based on a simple schedule.
`reformat_trial_data`(data, date, trial, ...)	Reformats raw trial data into a flattened dictionary structure.
`setup_logging`(logs_subdirectory)	Configure the logging system to write to a timestamped file.
`transform_raw_to_clean`(df)	Transforms raw Bpod trial data into a clean, wide-format DataFrame.

change_directory_settings(new_path: str) → None[source]

Update all directory settings based on a new project root path.

Parameters:: new_path (str) – The absolute path to the new project root directory.

change_system_directory_settings() → None[source]

Updates the system directory setting and renames the directory if it changed.

This handles cases where the SYSTEM_NAME setting might have been updated.

create_directories() → None[source]

Create all necessary system directories if they do not exist.

Uses paths defined in the global settings.

create_directories_from_path(p: str) → bool[source]

Creates a standard directory structure rooted at the given path.

Parameters:: p (str) – Root path for the new directory structure.
Returns:: True if successful, False if an exception occurred.
Return type:: bool

download_github_repositories(repositories: list[str]) → None[source]

Clone a list of GitHub repositories into the user’s village_projects directory.

If a repository already exists and is not empty, it is skipped. Updates the ‘GITHUB_REPOSITORIES_DOWNLOADED’ setting upon success.

Parameters:: repositories (list[str]) – A list of GitHub repository URLs.

is_active_regular(value: str) → bool[source]

Checks if the current day allows activity based on a simple schedule.

Parameters:: value (str) – “ON”, “OFF”, or a hyphen-separated list of active days (e.g., “Mon-Wed-Fri”).
Returns:: True if active today, False otherwise.
Return type:: bool

is_active(value: str) → bool[source]

Check if a schedule string dictates activity at the current time.

The value can be “ON”, “OFF”, or a range of days (e.g., “Mon-Fri”). Uses DAYTIME and NIGHTTIME settings to determine active hours within those days.

Parameters:: value (str) – The schedule string to evaluate.
Returns:: True if active right now, False otherwise.
Return type:: bool

calculate_active_hours(df: pandas.DataFrame) → dict[str, int][source]

Calculates the total active hours for different entities based on a DataFrame.

The DataFrame is expected to have ‘name’ and ‘active’ columns.

Parameters:: df (pd.DataFrame) – Input dataframe with schedule information.
Returns:: Dictionary mapping names to total active hours.
Return type:: dict[str, int]

delete_all_elements_from_layout(layout: <MagicMock name = 'mock.QLayout' id='140286154219088'>) → None[source]

Recursively removes all widgets and sub-layouts from a QLayout.

Parameters:: layout (QLayout) – The layout to clear.

reformat_trial_data(data: dict, date: str, trial: int, subject: str, task: str, system_name: str) → dict[source]

Reformats raw trial data into a flattened dictionary structure.

Parameters:

data (dict) – Raw data dictionary containing events and states.
date (str) – Date string.
trial (int) – Trial number.
subject (str) – Subject identifier.
task (str) – Task identifier.
system_name (str) – System name.

Returns:

Flattened dictionary including formatted start/end times.

Return type:

dict

transform_raw_to_clean(df: pandas.DataFrame) → pandas.DataFrame[source]

Transforms raw Bpod trial data into a clean, wide-format DataFrame.

Processes MSG, START, and END columns to create specific start/end columns for each message type.

Parameters:: df (pd.DataFrame) – Raw input DataFrame.
Returns:: Cleaned and pivoted DataFrame.
Return type:: pd.DataFrame

setup_logging(logs_subdirectory: str) → tuple[str, FileHandler][source]

Configure the logging system to write to a timestamped file. Creates the log directory if needed, resets existing handlers, and suppresses verbose logs from external libraries (urllib3, telegram, etc.).

Parameters:

logs_subdirectory (str) – The name of the subdirectory in the system folder where logs should be stored.

Returns:

A tuple containing the log filename and: the created FileHandler instance.

Return type:

tuple[str, logging.FileHandler]

has_low_disk_space(threshold_gb=10) → bool[source]

Checks if the root partition has low disk space.

Parameters:: threshold_gb (int, optional) – The threshold in GB. Defaults to 10.
Returns:: True if free space is below the threshold, False otherwise.
Return type:: bool

interpolate(x: Any, y: Any, points: int = 100) → tuple[numpy.ndarray, numpy.ndarray][source]

Perform PCHIP interpolation on specific data points.

Sorts the data, averages y-values for duplicate x-values, and generates interpolated points.

Parameters:

x (Any) – Input x coordinates (array-like).
y (Any) – Input y coordinates (array-like).
points (int, optional) – Number of interpolated points to generate. Default: 100.

Returns:

A tuple (x_fit, y_fit) of interpolated arrays, or (None, None) if insufficient data points.

Return type:

tuple[np.ndarray, np.ndarray]

get_x_value_interp(x: Any, y: Any, y_target: float) → float | None[source]

Find the x-value corresponding to a target y-value using interpolation.

Useful for finding thresholds (e.g., x value where y crosses 50%).

Parameters:

x (Any) – Input x coordinates.
y (Any) – Input y coordinates.
y_target (float) – The target y value to search for.

Returns:

The estimated x value, or None if the target is out of range or interpolation fails.

Return type:

float | None

create_pixmap(fig: matplotlib.figure.Figure) → <MagicMock name='mock.QPixmap' id='140286154219216'>[source]

Creates a QPixmap from a matplotlib Figure.

Parameters:: fig (Figure) – The matplotlib figure.
Returns:: The generated QPixmap, or an empty QPixmap if an error occurs.
Return type:: QPixmap