treble_tsdk.collections.scene_collection

Classes

SceneCollection

class treble_tsdk.collections.scene_collection.SceneCollection

__init__(client: TSDKClient | None = None, data_loader: IRDataLoader = None, description: str = '')

Create a collection of AudioScene objects that can be rendered together.

Parameters:

client – TSDKClient used to resolve simulations/devices and to drive remote optimization.
data_loader – IRDataLoader used to load and cache IR data.
description – Free-text description stored in the collection metadata.

add_column(name: str, mapper: Callable[[T], Any], dtype: polars.DataType | None = None)

Add a column to the collection using a mapper function.

Parameters:

name (str) – Name of the column.
mapper (Callable[[T], Any]) – Mapper function to get a value. Called for each row in the collection with the item (e.g. Simulation or IRInfo) as a parameter.
dtype (pl.DataType) – Data type of the column. If not provided the mapper function will be used to determine the data type.

add_scene(scene: AudioScene)

Append a scene to the collection.

Parameters:: scene – The AudioScene to add.

apply(func: Callable[[polars.DataFrame], polars.DataFrame]) → _Self

Apply a DataFrame transformation and return a new collection of the same type.

The returned collection shares cached objects with the original but has an independent DataFrame. The transformation must preserve the required columns.

Parameters:: func (Callable[[pl.DataFrame], pl.DataFrame]) – A function that receives the underlying Polars DataFrame and returns a transformed DataFrame.
Returns:: A new collection of the same type with the transformed DataFrame.

Example:

filtered = coll.apply(lambda df: df.filter(pl.col("x") > 5).sort("y"))

as_remote_optimization_live_progress(): Display a live, auto-refreshing progress view for the remote optimization job.

cancel_remote_optimization()

copy_custom_columns(other_collection: CollectionBase, key_columns: list[str] | None = None, columns_to_copy: list[str] | None = None)

enrich_with_predicted_snr(target_selection: int | str | list[int], show_progress: bool = True)

Predict the SNR of each scene for a given target and append the result as a new entry in the predicted_snr column.

Each struct in predicted_snr is keyed by target_selection and holds the predicted SNR (in dB) for that target. Calling this again with the same target_selection skips the matching entry; a different target_selection accumulates as an additional list entry.

SNR prediction requires the IRs to carry per-band spl values (added via IRCollection.enrich_with_acoustic_parameters()) and the audio sources to carry SPL metadata (added via AudioDataset.enrich_with_spl()).

Parameters:

target_selection – Track index, source group name, or list of track indices designating the target.
show_progress – If True, show a progress bar while iterating scenes.

Return a new collection keeping only scenes whose predicted SNR falls within [min_db, max_db].

Parameters:

min_db – Lower bound on predicted SNR in dB. If None, no lower bound is applied.
max_db – Upper bound on predicted SNR in dB. If None, no upper bound is applied.
target_selection – The target used during enrich_with_predicted_snr(). Required when scenes carry more than one predicted-SNR entry; may be omitted when each scene has a single entry, in which case that entry is used.

Returns:

A new SceneCollection with the matching scenes.

filter_collection(*args, **kwargs) → _Self

Filter the collection and return a new collection with matching rows.

Accepts the same arguments as polars.DataFrame.filter().

Returns:: A new collection of the same type containing only the matching rows.

Example:

nearby = coll.filter_collection(pl.col("source_receiver_dist") < 5.0)

get_predicted_snr(scene_id: str, target_selection: int | str | list[int] | None = None) → float | None

Retrieve a predicted SNR value for the scene with id scene_id.

When the scene has only one predicted-SNR entry, target_selection may be omitted. When multiple entries exist, supply target_selection to select the matching one.

Parameters:

scene_id – The id of the scene in the collection.
target_selection – The target selection used during enrich_with_predicted_snr(). Required when the scene has more than one predicted-SNR entry.

Returns:

The predicted SNR in dB, or None when it could not be estimated.

get_remote_optimization_progress() → OneOffTaskBundleProgress | None

Fetch a point-in-time progress snapshot for the remote optimization job.

Returns:: The OneOffTaskBundleProgress, or None when no eligible remote render has been started.

get_remote_optimization_token_cost() → Decimal: Estimate the token cost of running the remote optimization for this collection.

Retrieve a rendered audio entry for the scene with id scene_id.

When the scene has only one render entry, no recipe arguments are needed. When multiple entries exist, narrow the result by supplying one or more recipe arguments.

Parameters:

scene_id – The id of the scene in the collection.
sampling_rate – Filter by output sampling rate in Hz.
render_mode – Filter by render mode.
target_selection – Filter by target selection. Required when the scene has more than one render entry.
target_render_mode – Filter by target render mode.

Returns:

A dict with keys noisy_audio (AudioSignal), clean_audio (AudioSignal or None), separated_track_audio (list of AudioSignal or None), and snr (float or None).

head(n: int = 5) → _Self

Return a new collection with the first n rows.

Parameters:: n (int) – Number of rows, defaults to 5.
Returns:: A new collection of the same type.

plot()

Plot the collection using an interactive widget.

Extends CollectionBase.plot() so the SNR columns become plottable:

predicted_snr — one numeric column per distinct target_selection (e.g. predicted_snr ["target"]).
renders — one per-channel snr column per distinct render recipe (e.g. renders snr [mono, 0, wet_mono]).

preload_rendered_irs(): Preload the rendered IR data into the data loader.

print_remote_optimization_token_cost(): Print the token cost of running the remote optimization for this collection.

remove_column(name: str): Remove a column from the collection.

render(sampling_rate: float = 32000, render_mode: RenderMode = RenderMode.AUTO, target_selection: int | str | list[int] | None = None, target_render_mode: TargetRenderMode | WetMonoWindowed | WetDeviceWindowed = TargetRenderMode.WET_MONO, calculate_snr: bool = False, output_separated_tracks: bool = False, max_retries: int = 4320, show_progress: bool = True)

Render the Scene Collection and append the results as a new entry in the renders column (a list of render-result structs, one per render call).

Each struct in renders is keyed by the render parameters (sampling_rate, render_mode, target_selection, target_render_mode) and contains the resulting audio bytes plus optional separated_track_audio and snr fields.

Calling render() again with the same key parameters updates the matching entry in place — e.g. re-rendering with calculate_snr=True fills in the snr field of the existing entry rather than adding a new one. Different key parameters accumulate as additional list entries. A matching entry that already has everything requested (SNR/separated tracks) is skipped entirely.

When the collection has scenes eligible for remote optimization and that work has not yet been kicked off, this method will start it and block until completion.

Parameters:

sampling_rate – Output sampling rate in Hz.
render_mode – Rendering mode for the mixed audio.
target_selection – Track index, source group name, or list of indices to isolate as the clean target. If None, no target/clean output is produced.
target_render_mode – How the isolated target is rendered.
calculate_snr – If True, compute the per-device channel SNR between the rendered target and the noise.
output_separated_tracks – If True, also store each separated track.
max_retries – Maximum number of retries to poll for remote optimization to finish. Each retry waits 20 seconds before re-checking the processing status. By default this allows for up to 24 hours of waiting before giving up.
show_progress – If True, show progress bars/live views during remote rendering and scene rendering.

Sample rows where the specified column follows a target distribution.

Returns a new collection of the same type containing only the sampled rows.

Parameters:

column (str) – The column to sample from.
n_samples (int) – The number of rows to sample.
distribution (Distribution) – Distribution to sample from.

Returns:

A new collection containing the sampled rows.

sample_with_gaussian_distribution(column: str, n_samples: int, target_mean: float, target_std: float, seed: int = 42)

Sample rows where the specified column follows a target Gaussian distribution.

This is a convenience wrapper around sample_with_distribution.

Parameters:

column (str) – The column to sample from.
n_samples (int) – The number of rows to sample.
target_mean (float) – The target mean for the distribution.
target_std (float) – The target standard deviation for the distribution.
seed (int) – The random seed for reproducibility.

start_remote_optimization(show_progress: bool = True)

Start the remote optimization for this scene collection.

Parameters:: show_progress – If True, display a live progress view for the processing tasks.

tail(n: int = 5) → _Self

Return a new collection with the last n rows.

Parameters:: n (int) – Number of rows, defaults to 5.
Returns:: A new collection of the same type.

wait_for_remote_optimization_processing(max_retries=4320) → str | None

Waits until the remote optimization has been completed and then returns the status.

Parameters:: max_retries – Maximum number of retries before stopping, each retry waits 20 seconds. Default is 4320 retries, which is 24 hours.
Returns:: The status of the remote optimization.

write_parquet(path: str | Path, **kwargs)

Write the dataframe to a parquet file.

Parameters:

path (str | Path) – Path to the parquet file.
kwargs – Additional keyword arguments passed to polars.DataFrame.write_parquet.

property columns: list[str]: List of columns in the DataFrame

property compact_columns: dict[str, int]: Columns to truncate when printing, mapped to their max display length in characters.

property dataframe: polars.DataFrame

Get the collection data as a Polars DataFrame.

Returns pl.DataFrame:: DataFrame containing all collection items and computed columns.

property editable_dataframe: polars.DataFrame: DataFrame with only the user-modifiable (non-locked) columns. The key column is always included in the editable dataframe although it is locked.

property lazy_df: polars.LazyFrame: Lazy access to underlying Polars DataFrame

property locked_columns: list[str]: List of locked columns for the collection. Columns in this list are read-only and cannot be modified by the user.

property remote_optimization_status: SolveTaskStatus | None

Return the aggregate status of the remote optimization job.

Returns:: The SolveTaskStatus, or None when no eligible remote render has been started.

property required_columns: list[str]: List of required columns for the collection.

property scenes: list[AudioScene]

The scenes held by this collection, reconstructed from the dataframe.

Returns:: A list of AudioScene, empty when the collection holds no scenes.