Miscellaneous utilities

Common exception types

exception ramutils.exc.CommandLineError

Raised when there are CLI-related errors.

exception ramutils.exc.DataLoadingError

Raised when when unable to load expected files

exception ramutils.exc.MissingArgumentsError

Raised when an optional argument is not optional for certain cases but is not specified.

Example: when not giving trigger pairs for PS5 experiments.

exception ramutils.exc.MissingFileError

Raised when a required file doesn’t appear to exist.

exception ramutils.exc.MultistimNotAllowedException

Raised when attempting to define multiple stim sites for an experiment which doesn’t support it.

exception ramutils.exc.RamException

Base exception class for custom exceptions.

exception ramutils.exc.RetrievalBaselineError

Raised when something goes wrong with adding baseline events during

the retrieval period

exception ramutils.exc.TooManyExperimentsError

Raised when too many experiments are included with events.

exception ramutils.exc.TooManySessionsError

Raised when too many sessions’ worth of data are passed as an argument.

exception ramutils.exc.UnableToReloadClassifierException

Raised when processing cannot load or use the actual classifier from a session.

exception ramutils.exc.UnsupportedExperimentError

Raised when trying to do something with an experiment that is not yet supported.

exception ramutils.exc.ValidationError

Raised when validation checks fail.

Logging

class ramutils.log.RamutilsStreamHandler(*args, **kwargs)

Custom stream handler used by ramutils loggers.

class ramutils.log.RamutilsFileHandler(filename)

Custom rotating file handler used by ramutils loggers.

Parameters:filename (str) – Base filename for logs.

ramutils.log.get_logger(name='ramutils')

Returns a configured logger to be used throughout the ramutils package.

Parameters:name (str) – Name for the logger (default: 'ramutils')

Everything else

Constants

Constants that may be used throughout ramutils. Constants that are defined here include:

• EXPERIMENTS - a dictionary of all experiments that can be processed by ramutils

Utility functions

ramutils.utils.bytes_to_str(istring, encoding='utf-8')

Converts bytes to str in a version-neutral way.

Parameters:

• istring (bytes or str) – Input string
• encoding (str) – Encoding to use when decoding (default: ‘utf-8’).

Returns:

string

Return type:

str

ramutils.utils.combine_tag_names(tag_name_list)

Generate sensible output from a list of tuples containing anode and cathode contact names.

ramutils.utils.encode_file(fd)

Produces a base64-encoded version of the data inside the file-like object fd. :param fd: :return: str

ramutils.utils.extract_experiment_series(experiment)

Extract the experiment series number from experiment name

Parameters:experiment (str) – Name of the experiment Returns:Series number in string format (to accommodate PS2.1). If experiment was invalid, None is returned Return type:str

ramutils.utils.extract_report_info_from_path(file_path)

Exploit the naming convention to parse underlying data into its components

ramutils.utils.extract_subject_montage(subject_id)

Extract the subject ID and montage number from the subject ID

Parameters:subject_id (str) – Subject identifier Returns:

• str – Subject identifier with montage information removed
• int – Montage number

ramutils.utils.get_completed_sessions(subject, experiment, rootdir='/')

Get a list of sessions completed of a given experiment by a subject

ramutils.utils.get_session_str(session_list)

Combine session numbers into ‘_’ separated string. Used for saving underlying data

ramutils.utils.is_stim_experiment(experiment)

Returns whether or not the given experiment is a stim experiment

Parameters:experiment (str) – Name of the experiment Returns:Indicator for if the given experiment is a stimulation experiment Return type:bool

ramutils.utils.load_event_test_data(datapath, rootdir)

Modify the path stored in the eegfile field to work with any given root directory at runtime. Used in test data suite to allow running tests rom an arbitrary location that has access to RHINO

ramutils.utils.mkdir_p(dirs, mode=511)

Mimic the shell command mkdir -p.

Parameters:

• dirs (str) –
• mode (int) –

ramutils.utils.reindent_json(json_file, indent=2)

Re-indent JSON data preserving order. Useful for removing extraneous whitespace leftover from templates generation.

Parameters:

• json_file (str or file-like) – Path to JSON file or a file-like object containing JSON data.
• indent (int) – Indent width

Returns:

reindented – Re-indented JSON string

Return type:

str

ramutils.utils.safe_divide(a, b=None)

Attempts to perform a/b and catches zero division errors to prevent crashing.

Parameters:

• a (float or callable) – Numerator or the function to wrap when used as a decorator.
• b (float or None) – Denominator or None when used as a decorator.

Returns:

result – 0 if denominator is 0, else a/b

Return type:

float

ramutils.utils.sanitize_comma_sep_list(input_list)

Clean up a string with comma-separated values to remove 0 elements.

ramutils.utils.save_array_to_hdf5(output, data_name, data, overwrite=False)

Save an array of data to hdf5

Parameters:

• output ((str) Path to hdf5 output file) –
• data_name ((str) Name of the dataset) –
• data ((np.ndarray) Data array) –

Notes

Primarily useful for debugging purposes. Could be used to save underlying data for report plots.

ramutils.utils.show_log_handlers()

Prints logging handlers. Used for figuring out what is manipulating logging that shouldn’t be.

ramutils.utils.tempdir()

Create a temporary directory and remove its contents upon completion.

ramutils.utils.timer(message='Elapsed time: %.3f s', logger=None)

Context manager to log the elapsed time of a code block.

Parameters:

• message (str) – Percent-formatted string to display the elapsed time
• logger (str) – Name of logger to use

ramutils.utils.touch(path)

Mimics the unix touch command.