poulet_py.tools package#

check_or_create(path)[source]#

Function to check whether a folder exists. If it does NOT exist, it is created

define_folder_name(name, *, add_date=True)[source]#
Return type:

str

generate_stimulus_sequence(n, *, stimuli_options, mode='random')[source]#

Generate a list of trials with specified stimuli distribution.

Parameters:

  • n (int) – Number of trials to generate. Must be divisible by the number of stimuli options when mode is ‘random’ or when multiple stimuli are provided in ‘fixed’ mode.

  • stimuli_options (List[Any]) – List of possible stimulus values. For a single stimulus, all trials will use it. For multiple stimuli, distribution depends on mode.

  • mode ({'random', 'fixed'}, optional) – Distribution mode: - ‘random’: Shuffled trials with equal representation of each stimulus - ‘fixed’: Trials use stimuli in sequence (or single stimulus repeated) (default: ‘random’)

Returns:

Generated list of stimuli for each trial

Return type:

List[Any]

Raises:

ValueError – If n is not divisible by number of stimuli options (for relevant modes), or if mode is invalid.

Notes

  • For ‘random’ mode with multiple stimuli, each appears exactly

    n//len(stimuli_options) times.

  • For ‘fixed’ mode with multiple stimuli, stimuli are repeated in sequence

    until n is reached.

  • For ‘fixed’ mode with single stimulus, that stimulus is repeated n times.

Examples

>>> generate_trials(4, stimuli_options=[1, 2], mode="random")
[2, 1, 2, 1]  # Random order with equal representation

>>> generate_trials(3, stimuli_options=[5], mode="fixed")
[5, 5, 5]
go_to(key, *, path=None)[source]#

Change the current working directory to the level containing a specified key in a path.

Parameters:

  • key (str) – The directory name to search for in the path (e.g., “neuropixels”).

  • path (Path or str, optional) – The input path to analyze. Defaults to the caller script’s location (__file__).

Returns:

True if the directory was changed successfully, False otherwise.

Return type:

bool

Examples

>>> change_dir_to_key("neuropixels", path="/project/neuropixels/src/file.py")
True  # Changes CWD to "/project/neuropixels"
json_serializer(data, file=None)[source]#

Serialize data to JSON.

Features: - Efficient serialization using orjson (faster than standard json module) - Built-in numpy array support via orjson’s native serialization - Returns bytes if no file provided, writes to file otherwise

Return type:

bytes | None

Args:
data: Dictionary containing data to serialize.

Numpy arrays are automatically supported.

file: Output file

If None, returns serialized bytes instead of writing to file. Must end with ‘.json’ extension if provided.

Returns:

bytes | None: Serialized JSON as bytes if file is None, otherwise None.

Raises:

ValueError: If provided file doesn’t end with ‘.json’ extension TypeError: If data contains non-serializable types JSONEncodeError: If serialization fails for other reasons

Example:
>>> data = {"array": np.array([1, 2, 3])}
>>> # Write to file
>>> json_serializer(data, "output.json")
>>> # Get bytes
>>> json_bytes = json_serializer(data)
sanitize_path(path, *, add_timestamp=False)[source]#

Sanitize a full path by making all components filesystem-friendly and optionally adding a timestamp to the last component (file or folder).

Parameters:

  • path (str) – The input path to sanitize (can include folders and filename)

  • add_timestamp (bool, optional) – If True, prepend timestamp in YYYYMMDD format to the last component

Returns:

Sanitized path with all special characters replaced by underscores and optional timestamp on the last component

Return type:

str

Examples

>>> sanitize_path("/s$ss!on1/d%ta/345.pkl", add_timestamp=True)
'/s_ss_on1/d_ta/20250503_345.pkl'

>>> sanitize_path("my@project/data#files")
'my_project/data_files'
save_metadata_exp(metadata, path, name)[source]#

Submodules#