ambiscape 0.41.0

Changed

• starss.frame_azimuths returns three values, not two. It now yields
  (az_deg, energy, diffuseness); callers unpacking two will break.
  Diffuseness is 1 - |I| / E per frame, returned so a caller can withhold an
  estimate where the field is too diffuse to carry a direction. The function
  also takes method="intensity" (the default, unchanged behaviour) or
  "energy", and a sub_s sub-frame length.
• onset_lead takes a crossing fraction per modality. New optional
  first_rise and second_rise arguments; the default remains the symmetric
  rise=ONSET_RISE, so existing calls are unaffected. Motion and audio series
  do not reach a given fraction of their own range at comparable moments, and
  one number for both was hiding that.
• AUDIO_RISE is no longer used as a default. It remains exported at 0.75,
  now labelled provisional.

Fixed

• The justification for the audio crossing fraction was wrong, and the error
  was the kind that reads as validation. The figure quoted for 0.75 —
  landing within 0.01 s where 0.25 lands 1.78 s early — compares the rule
  against another algorithmic onset, not against anyone's ear or eye; the
  word "hand-checked" attached to it somewhere between the measurement and the
  docstring. The agreement is also partly an artefact: the two passes used dB
  and linear energy, on which the same fraction lands tens of frames apart, so
  the 0.01 s was two mismatches cancelling. MOTION_RISE is validated (median
  0.06 s against onsets marked by eye); AUDIO_RISE is not, and the docstring
  now says not to publish a figure that depends on it.

Documentation

• floor_suspicion's justification was written from one room and stated as a
  property of a corpus. Re-measured across all 84 SINS node-sessions: median
  spread per octave band runs 5.17, 4.54, 2.76, 2.96, 1.85, 1.54, 0.51, 0.34,
  0.29 dB from 32 Hz to 8 kHz. The old claim that "every band below 1 kHz
  varies by 2.4--5.3 dB" is true of that room and false of the corpus, where
  500 Hz and 1 kHz sit at 1.85 and 1.54. The separation the check actually
  relies on --- above hf_min_hz, 0.29--0.51 dB against a 1.5 dB threshold ---
  is intact, so no default changed and no behaviour changed. The docstring now
  carries the corpus figures and notes that the check is conservative at 2 kHz,
  whose 95th percentile of 1.67 dB escapes flagging in a minority of sessions.
• floor_suspicion cannot be cited as evidence about SINS, because its
  threshold was chosen from SINS. Recorded in the docstring and in the wiki's
  Design Decisions, because the flag reads like independent confirmation and is
  not.
• modulation.profile cannot resolve a period longer than a quarter of the
  record, and does not say so. Each scale's band starts at four cycles, so a
  one-day session's macro band begins at 21600 s and a diurnal peak falls
  outside it; the function returns the strongest thing in the remaining band
  without warning. The module docstring now says this and points at the
  stitch-the-week-first approach, with the two controls such a record needs.