Simulate Localization Responses

This guide shows how to generate predicted sound-localisation responses for a given HRTF and set of model parameters. The output is a pyfar.Coordinates object of simulated pointing directions, from which standard localisation metrics (lateral RMS error, polar RMS error, quadrant error rate) can be computed.

The workflow has three steps: feature preparation, Bayesian inference, and motor noise sampling.

Prepare features

compute_template computes ITD, ILD, and spectral cues from the HRTF and interpolates them onto a uniform spherical template grid.

    from bayesian_listener import BayesianListener

    listener = BayesianListener(sofa_path)
    listener.compute_template(interpolation="SHMAX")

Run inference

infer computes the MAP direction for each source position, repeated repetitions times to account for sensory noise.

    posterior = listener.infer(repetitions=1, prior="horizontal", seed=0)
    # posterior shape: (n_targets, repetitions) — argmax indices into template grid

Sample motor responses

estimate adds von Mises–Fisher motor noise to each MAP estimate and returns pointing directions.

    responses = listener.estimate(posterior, seed=0)
    # responses: pyfar.Coordinates, shape (n_targets, repetitions, 3)

Note

Pass kappa_motor=False to disable motor noise and recover the pure MAP estimate — useful for debugging or comparing against noiseless model predictions.

Compute localisation metrics

Use localization_error to compute standard metrics one at a time. The function expects flat pyfar.Coordinates of the same length, so repeat the target directions to match the response array.

    from bayesian_listener.metrics import localization_error

    # Ground-truth target directions (same order as listener.target.coords)
    targets = listener.target.coords   # pyfar.Coordinates, shape (n_targets,)

    le = localization_error(targets, responses, metric="rmsL", degrees = True)
    pe = localization_error(targets, responses, metric="rmsPmedianlocal", degrees = True)
    qe = localization_error(targets, responses, metric="querrMiddlebrooks", degrees = True)
    print(f"LE={le:.1f}°  PE={pe:.1f}°  QE={qe:.1f}%")

What to do next

Use fitted parameters from Fit the Model to Your Own HRTF to make the simulation listener-specific. Full API documentation is in BayesianListener and localization_error.