clarity.data.scene_builder_cec2 module

Code for building the scenes.json files.

class clarity.data.scene_builder_cec2.InterfererType(value)

Bases: Enum

Enum for interferer types.

MUSIC = 'music'

NOISE = 'noise'

SPEECH = 'speech'

class clarity.data.scene_builder_cec2.RoomBuilder

Bases: object

Functions for handling rooms.

build_from_rpf(rpf_location, n_interferers=3, n_rooms=10000, start_room=1)

Build a list of rooms by extracting info from RAVEN rpf files.

Parameters:

• rpf_location (str) – path to where rpf files are stored

• n_interferers (int, optional) – number of interferer definitions to expect. Defaults to N_INTERFERERS.

• n_rooms (int, optional) – number of scenes to expect. Defaults to N_SCENES.

• start_room (int, optional) – index of the first room to expect

get_room(name: str)

Get a room by name.

Parameters:

name (str) – Name of room to extract.

Returns:

load(filename) → None

Load the list of room from a JSON file.

Parameters:

filename (str) – filename to JSON file from which room data is loaded.

rebuild_dict()

Build room dictionary.

save_rooms(filename)

Save the list of rooms to a JSON file.

Parameters:

filename (str) – filename to JSON file to which room data is saved.

class clarity.data.scene_builder_cec2.RoundingFloat(x=0, /)

Bases: float

Round a float to 4 decimal places.

class clarity.data.scene_builder_cec2.SceneBuilder(rb, scene_datasets, target, interferer, snr_range, listener, shuffle_rooms=None)

Bases: object

Class with methods for building a list of scenes.

add_SNR_to_scene(snr_range: list)

Add the Signal Noise Ratio (SNR) info to the scenes.

Parameters:

snr_range (list) – Range of values from which SNR will be sampled.

Returns:

add_interferer_to_scene(speech_interferers: str, noise_interferers: str, music_interferers: str, number: list, start_time_range: list, end_early_time_range: list)

Add interferer to the scene description file.

Parameters:

• speech_interferers (str) – Path to speech interferer to load.

• noise_interferers (str) – Path to noise interferer to load.

• music_interferers (str) – Path to music interferer to load

• number (list) – Number of interefers to be added.

• start_time_range (list) – Range for randomly selecting start point.

• end_early_time_range (list) – Range for randomly selecting end point.

Returns:

None

add_listener_details_to_scene(heads, channels, relative_start_time_range: list, duration_mean: float, duration_sd: float, angle_initial_mean: float, angle_initial_sd: float, angle_final_range: tuple)

Add the listener info to the scenes.

Parameters:

• () (channels)

• ()

• relative_start_time_range (list) – Range from which start time is selected at random.

• duration_mean (float) – mean of the time offset for start of turn

• duration_sd (float) – standard deviation of the time offset for start of turn

• angle_initial_mean (float)

• angle_initial_sd (float)

• angle_final_range (tuple)

Returns:

None

add_target_to_scene(dataset: str, target_speakers: str, target_selection: str, pre_samples_range: list, post_samples_range: list)

Add target info to the scenes.

Uses target speaker file set via config.

Parameters:

• dataset (str) – dataset to be added.

• target_speakers (str)

• target_selection (str) – Type of target to be added, valid values are ‘SEQUENTIAL’ and ‘RANDOM’.

• pre_samples_range (list) – Parameters for number of samples prior to target onset.

• post_samples_range (list) – Parameters for number of samples to continue player after target offsets.

Raises: TypeError if room_selection is not SEQUENTIAL or RANDOM

initialise_scenes(dataset, n_scenes: int, room_selection: str, scene_start_index: int)

Initialise the scenes for a given dataset.

Parameters:

• dataset – train, dev, or eval set

• n_scenes (int) – number of scenes to generate

• room_selection (str) – SEQUENTIAL or RANDOM

• scene_start_index (int) – index to start for scene IDs

Raises: TypeError if room_selection is not SEQUENTIAL or RANDOM

instantiate_scenes(dataset) → None

Instantiate scenes with targets, interferers, SNR and listeners.

Parameters:

dataset

save_scenes(filename: str) → None

Save the list of scenes to a JSON file.

Parameters:

filename (str) – Filename to save scenes to.

Returns:

None

clarity.data.scene_builder_cec2.add_interferer_to_scene_inner(scene: dict, interferers: dict, number: list, start_time_range: list[int], end_early_time_range: list[int])

Randomly select interferers and add them to the given scene. A random number of interferers is chosen, then each is given a random type selected from the possible speech, nonspeech, music types. Interferers are then chosen from the available lists according to the type and also taking care to match the scenes ‘dataset’ field, ie. train, dev, test. The interferer data is supplied as a dictionary of lists of lists. The key being “speech”, “nonspeech”, or “music”, and the list of list being a partitioned list of interferers for that type. The idea of using a list of lists is that interferers can be split by subcondition and then the randomization draws equally from each subcondition, e.g. for nonspeech there is “washing machine”, “microwave” etc. This ensures that each subcondition is equally represented even if the number of exemplars of each subcondition is different. Note, there is no return. The scene is modified in place.

Parameters:

• scene (dict) – the scene description

• interferers (dict) – the interferer metadata

• number (list) – number of interferers

• start_time_range (list) – range of starting points as integers, a random number is selected between these.

• end_early_time_range (list) – range of end points as integers, a random number is selected between these.

clarity.data.scene_builder_cec2.add_this_target_to_scene(target: dict, scene: dict, pre_samples_range: list, post_samples_range: list)

Add the target details to the scene dict.

Adds given target to given scene. Target details will be taken from the target dict but the start time will be according to the CEC2 target start time specification.

Parameters:

• target (dict) – target dict read from target metadata file.

• scene (dict) – complete scene dictionary.

• pre_samples_range (list) – parameters for number of samples prior to target onset

• post_samples_range (list) – parameters for number of samples to continue player after target offsets.

clarity.data.scene_builder_cec2.build_room(target_file: str, interferer_files: list[str]) → dict

Build room json file from contents of related rpf files. Note, there is an rpf file for each source in the scene. All of these files are read and a single scene json file is constructed.

Parameters:

• target_file (str) – rpf file containing the target position

• interferer_files (List[str]) – list of files containing the interferer positions

Returns:

dictionary representation of the scene following CEC2 scene.json format

Return type:

dict

clarity.data.scene_builder_cec2.generate_rotation(scene: dict, relative_start_time_range: list, duration_mean: float, duration_sd: float, angle_initial_mean: float, angle_initial_sd: float, angle_final_range: tuple) → list[dict]

Generate a suitable head rotation for the given scene. Based on behavioural studies by Hadley et al. TODO: find ref

Parameters:

• scene (dict) – the scene description

• relative_start_time_range (list) – Range from which start time is uniformly selected at random.

• duration_mean (float) – mean of the time offset for start of turn

• duration_sd (float) – standard deviation of the time offset for start of turn

• angle_initial_mean (float)

• angle_initial_sd (float)

• angle_final_range (tuple)

Returns:

list of dicts with keys “sample” and “view_vector” specifying the head motion.

Return type:

list(dict)

clarity.data.scene_builder_cec2.generate_snr(snr_range: list[int]) → float

Generate a random Signal Noise Ratio (SNR).

Parameters:

snr_range (list) – Range from which to uniformly sample SNR.

Returns:

random number from uniform distribution in given range.

Return type:

float

clarity.data.scene_builder_cec2.get_num_post_samples(post_samples_range: list) → int

Number of samples to continue player after target offsets.

Parameters:

post_samples_range (list) – parameters for number of samples to continue.

Returns:

clarity.data.scene_builder_cec2.get_num_pre_samples(pre_samples_range: list) → int

Number of samples prior to target onset.

Parameters:

pre_samples_range (list) – parameters for number of samples prior to target onset

Returns:

clarity.data.scene_builder_cec2.get_random_hrir_set(heads, channels)

Get a random HRIR set.

clarity.data.scene_builder_cec2.get_random_interferer_offset(interferer: dict, required_samples: int) → int

Generate a random offset sample for interferer. The offset sample is the point within the masker signal at which the interferer segment will be extracted. Randomly selected but with care for it not to start too late, i.e. such that the required samples would overrun the end of the masker signal will be used is taken.

Parameters:

• interferer (dict) – the interferer metadata

• required_samples (int) – number of samples that is going to be required

Returns:

a valid randomly selected offset

Return type:

int

clarity.data.scene_builder_cec2.get_room_dims(text: str) → list

Find the room dimensions in the rpf file.

Parameters:

text (str) – String to be searched for room dimensions (string to be searched for is of the form ‘ProjectName = CuboidRoom_5.9x3.4186x2.9’).

Returns:

List of the three dimensions of the room.

Return type:

list

clarity.data.scene_builder_cec2.get_room_name(text: str) → str

Find the room name in the rpf file.

Parameters:

text (str) – String to be searched for room name (‘R’ followed by 5 digits).

Returns:

The room name.

Return type:

str

clarity.data.scene_builder_cec2.get_vector(text: str, vector_name: str) → list[float]

Get a vector quantity from the rpf file. Will read rpf vector quantities, eg. “sourceViewVectors = -0.095,-0.995, 0.000”

Parameters:

• text (str) – string contents of the rpf file

• vector_name (str) – name of vector to extract (e.g. “sourceViewVectors”)

Returns:

vector as list of floats

Return type:

List[float]

clarity.data.scene_builder_cec2.make_rpf_filename_dict(rpf_location: str, scene_str: str, n_interferers: int) → dict

Construct dictionary storing all rpf files that will be processed.

Parameters:

• rpf_location (str) – Location

• scene (str) – Scene (as string)

• n_interferers (int) – Number of interferers.

Returns:

Dictionary of rpf files to be processed.

Return type:

dict

clarity.data.scene_builder_cec2.read_rpf_file(rpf_filename: str) → dict

Process an rpf file and return key contents as a dictionary.

Parameters:

rpf_filename (str) – Path to an rpf file to be read.

Returns:

dictionary of rpf file contents

{“position”: sourcePositions, “view_vector”: sourceViewVectors}

Return type:

dict

clarity.data.scene_builder_cec2.select_interferer_types(allowed_n_interferers: list) → list[InterfererType]

Select the interferer types to use.

The number of interferer is drawn randomly from list of allowed valued. The type of each is chosen randomly but there is not allowed to be more than 1 music source.

Parameters:

allowed_n_interferers (list) – list of allowed number of interferers

Returns:

list of interferer types to use

Return type:

list(InterfererType)

clarity.data.scene_builder_cec2.select_random_interferer(interferers: list[list], dataset: str, required_samples: int) → dict

Randomly select an interferer. Interferers stored as list of list. First randomly select a sublist then randomly select an item from sublist matching constraints.

Parameters:

• interferers (list(list)) – interferers as list of lists

• dataset (str) – desired data [train, dev, eval]

• required_samples (int) – required number of samples

Raises:

ValueError – if no suitable interferer is found

Returns:

the interferer dict

Return type:

dict

clarity.data.scene_builder_cec2.set_random_seed(random_seed)