Export & work with data

Obtaining results

As a simulation is completed, the results can be downloaded into a directory of choice. A Results class exists to work with results and it has a wealth of functionalities which are explained in this section.

A simulation result can either be downloaded via the Simulation class or the results from all completed simulations in a single project can be downloaded from the Project class. When downloading results from a whole project, the files get written into subfolders called after the respective simulation ids.

By default result files get named after source ids, but by supplying a ResultsRenameRule, this can be changed to naming them by source labels.

# Download results from a single simulation
destination_directory = "result_directory"
results = simulation.download_results(destination_directory, rename_rule=treble.ResultsRenameRule.by_label)

# Download all available results from a proejct
project.download_results(destination_directory, rename_rule=treble.ResultsRenameRule.by_label)

The Results class

An instance of the Results class can always be created by pointing to a directory with result files, so there is no need to redownload every time.

results = simulation.get_results_object(destination_directory)

The Results class includes methods to plot, export to files and to numpy arrays. To retrieve individual parts of the dataset, there are a few options.

Impulse responses

Firstly, there are the impulse response retrievals, get_mono_ir() and get_spatial_ir(). The input to those methods are source and receiver which can either be labels, ids or elements of the lists accessed via simulation.sources and simulation.receivers

# Define source labels
receiver = "receiver_1"
source = "source_1"

# Works for all receivers
mono_ir: MonoIR = results.get_mono_ir(source=source, receiver=receiver)

# Works for spatial receivers
spatial_ir: SpatialIR = results.get_spatial_ir(source=source, receiver=receiver)

It's important to note that Impulse responses do not start at time zero. We apply zero padding at the beginning and end of the impulse responses to mitigate potential unphysical effects of acausal filtering when source-recevier distance is short. The IR classes include information on the zero padding, the time array and additionally include methods of retrieving the unpadded data and time. All IR classes contain methods to export data to numpy arrays or to wav files. When exporting to wav files, the impulse response get's normalized and trimmed to start from time zero by default.

# Mono impulse array:
mono_ir.data
# The associated time vector
mono_ir.time
# Sampling rate
mono_ir.sampling_rate
# Frequency response
mono_ir.frequency_response
# Associated frequency array
mono_ir.frequency

# Export to wav file
mono_ir.write_to_wav(path_to_file="mono_ir.wav")

# Normalization coefficient used to normalize wav export
mono_ir.normalization_coefficient

# Get unpadded array
data = mono_ir.unpadded_data()
time = mono_ir.unpadded_time()

Acoustic Parameters

The acoustic parameters can be retrieved from the Results class instance by running

ap = results.get_acoustic_parameters(source=source, receiver=receiver)

where acoustic parameters can be accessed via the AcousticParameters dataclass. Each parameter comes as a list where each element in the list is either associated with an octave band or a noise criterion (only for STI). The respective octave band central frequencies.