vibration.human.multiple_shock
Whole-body vibration containing multiple shocks (ISO 2631-5:2018).
Implements the normative Clause 5 spinal-response model and the Annex C
assessment of adverse health effects for the vertical (z) axis.
The 2018 edition is vertical-axis only by design: clause 4 (delineation,
item a) neglects the x and y contributions to spinal compression, the
seat-to-spine transfer function of clause 5.2 is the vertical seat-to-lumbar
response, and the Annex C stress conversion is the vertical one.
The horizontal spinal model of the withdrawn 2004 edition is not reproduced.
Assess horizontal whole-body exposure with the ISO 2631-1 metrics in this
domain instead: the weighted r.m.s. acceleration
(weighted_acceleration) and the vibration dose
value (vibration_dose_value).
A seat-to-spine transfer function (clause 5.2, Formula 1) maps the measured seat acceleration to the spinal response acceleration
The standard assumes the record conditioned as clause 5.1.3 sets out, and the conditioning is the caller’s: has unity transmissibility at 0 Hz, so an offset left in the record (e.g. the gravity component of a non-AC-coupled accelerometer) passes straight into and corrupts the response peaks. The clause asks for an offset correction so that the recorded acceleration, with the accelerometer at rest (or with a symmetric signal), is (0 ± 0.1) m/s2, and notes that subtraction of the mean may not be appropriate if the recorded acceleration is asymmetric. It then band-limits the offset-corrected record with a second-order Butterworth high-pass filter at 0.01 Hz and a fourth-order Butterworth low-pass filter at 80 Hz; the band-limiting and weighting filters of ISO 2631-1 should not be applied. The acceleration dose is
over the positive response peaks, scaled to a daily dose
Annex C turns the daily dose into an injury risk: the daily compressive stress (Formula C.1), the age-cumulated stress variable (Formulae C.3/C.4) and the Weibull probability of lumbar injury (Formula C.5, Table C.1):
The Annex A / Annex E model (intervertebral compressive forces via a finite-element model distributed by ISO) is not reproducible from the standard text and is out of scope.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
acceleration_dose
Section titled “acceleration_dose”acceleration_dose( acceleration_m_s2: Signal | NumericArrayLike, fs: float | None = None,) -> floatAcceleration dose from a seat acceleration time history.
Filters the acceleration through the seat-to-spine transfer function
(Formula 2), takes the positive response peaks and combines them by
Formula 3. The input must be conditioned as clause 5.1.3 sets out; see
spinal_response.
Parameters
| Name | Description |
|---|---|
acceleration_m_s2 |
Measured vertical seat acceleration , conditioned as clause 5.1.3 sets out, m/s2. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this quantity is an acceleration in m/s2 and not a pressure. |
fs |
Sampling frequency, in hertz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
Returns: The acceleration dose , m/s2.
compression_dose
Section titled “compression_dose”compression_dose(daily_dose_value: float, *, mz: float = 0.029) -> floatDaily compressive stress (Annex C, Formula C.1).
Parameters
| Name | Description |
|---|---|
daily_dose_value |
The daily acceleration dose , m/s2. |
mz |
Stress conversion (MPa per m/s2) of Formula C.2; default 0.029, the 82 kg male value, and 0.025 for the female. |
Returns: The daily compressive stress , MPa.
Raises
| Exception | When |
|---|---|
| TypeError | if daily_dose_value or mz is not a single number. |
daily_dose
Section titled “daily_dose”daily_dose( dose: float, exposure_time: float, measurement_time: float,) -> floatDaily acceleration dose (clause 5.3, Formula 4).
Parameters
| Name | Description |
|---|---|
dose |
The measured acceleration dose , m/s2. |
exposure_time |
Daily exposure period (any time unit). |
measurement_time |
Period over which was measured (same unit as exposure_time). |
Returns: The daily dose , m/s2.
Raises
| Exception | When |
|---|---|
| TypeError | if dose, exposure_time or measurement_time is not a single number. |
daily_dose_multi
Section titled “daily_dose_multi”daily_dose_multi( doses: NumericArrayLike, exposure_times: NumericArrayLike, measurement_times: NumericArrayLike,) -> floatDaily dose from several exposure conditions (clause 5.3, Formula 5).
Parameters
| Name | Description |
|---|---|
doses |
Acceleration dose of each condition, m/s2. |
exposure_times |
Daily exposure duration of each condition. |
measurement_times |
Measurement duration of each condition. |
Returns: The combined daily dose , m/s2.
Raises
| Exception | When |
|---|---|
| TypeError | if doses, exposure_times or measurement_times holds a text or a value that is not a real number. |
dose_from_peaks
Section titled “dose_from_peaks”dose_from_peaks(peaks: NumericArrayLike) -> floatAcceleration dose from response peaks (clause 5.3, Formula 3).
Parameters
| Name | Description |
|---|---|
peaks |
The positive response peaks , m/s2. |
Returns: The acceleration dose , m/s2.
Raises
| Exception | When |
|---|---|
| TypeError | if peaks holds a text or a value that is not a real number. |
injury_probability
Section titled “injury_probability”injury_probability( risk: float | np.floating[Any] | np.integer[Any], *, sex: Literal['male', 'female'] = 'male',) -> float
injury_probability( risk: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, sex: Literal['male', 'female'] = 'male',) -> NDArray[np.float64]
injury_probability( risk: NumericArrayLike, *, sex: Literal['male', 'female'] = 'male',) -> float | NDArray[np.float64]Probability of lumbar injury (Annex C, Formula C.5).
Parameters
| Name | Description |
|---|---|
risk |
The stress variable (see injury_risk); scalar or array-like. |
sex |
"male" or "female" (sets the Weibull coefficients). |
Returns: The injury probability in 0-1; a float for a number; an array for a sequence or an array, a zero-dimensional one included. Negative gives 0.
Raises
| Exception | When |
|---|---|
| TypeError | if sex is not a text, or risk holds a text or a value that is not a real number. |
injury_risk
Section titled “injury_risk”injury_risk( daily_compression: float, *, start_age: float, exposure_duration_years: int | np.integer[Any], days_per_year: float, sex: Literal['male', 'female'] = 'male', mz: float | None = None,) -> floatCumulative injury stress variable (Annex C, Formula C.3).
Accumulates the daily compressive stress over the exposure years, each year weighted by the reducing ultimate strength of the ageing spine.
Parameters
| Name | Description |
|---|---|
daily_compression |
The daily compressive stress , MPa. |
start_age |
Age at which the exposure started, in years. |
exposure_duration_years |
Number of exposure years n. |
days_per_year |
Number of exposure days per year N. |
sex |
"male" or "female". |
mz |
Stress conversion for the static stress ; defaults to the sex-specific value. |
Returns: The stress variable .
Raises
| Exception | When |
|---|---|
| ValueError | if exposure_duration_years is not a whole number from 1 or the spine strength is exhausted () within the exposure period. |
| TypeError | if sex is not a text, daily_compression, days_per_year or start_age is not a single number, or exposure_duration_years is a flag, a text or an array where a count of years goes. |
multiple_shock_assessment
Section titled “multiple_shock_assessment”multiple_shock_assessment( acceleration_m_s2: Signal | NumericArrayLike, fs: float | None = None, *, start_age: float, exposure_duration_years: int | np.integer[Any], days_per_year: float, exposure_time: float, measurement_time: float, sex: Literal['male', 'female'] = ..., mz: float | None = ...,) -> MultipleShockResult
multiple_shock_assessment( acceleration_m_s2: Signal | NumericArrayLike, fs: float | None = None, *, start_age: float, exposure_duration_years: int | np.integer[Any], days_per_year: float, sex: Literal['male', 'female'] = ..., mz: float | None = ...,) -> MultipleShockResultFull multiple-shock assessment from a seat acceleration time history.
Chains the Clause 5 dose and the Annex C risk: spinal response
(Formula 2), acceleration dose (Formula 3), daily dose (Formula 4),
compressive stress (C.1), stress variable (C.3) and injury
probability (C.5). The input must be conditioned as clause 5.1.3 sets
out; see spinal_response.
The model is vertical-axis only (clause 4a of the 2018 edition); for
horizontal whole-body exposure use the ISO 2631-1 metrics in this domain
(weighted_acceleration,
vibration_dose_value).
Parameters
| Name | Description |
|---|---|
acceleration_m_s2 |
Measured vertical seat acceleration , conditioned as clause 5.1.3 sets out, m/s2. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this quantity is an acceleration in m/s2 and not a pressure. |
fs |
Sampling frequency, in hertz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
start_age |
Age b at which the exposure started, in years. |
exposure_duration_years |
Number of exposure years n. |
days_per_year |
Number of exposure days per year N. |
exposure_time |
Daily exposure period ; when given with measurement_time the dose is scaled to a daily dose (Formula 4), otherwise the measured dose is taken as the daily dose. |
measurement_time |
Period over which the record was measured. |
sex |
"male" or "female". |
mz |
Stress conversion (MPa per m/s2); defaults to the sex-specific value. |
Returns: The MultipleShockResult.
Raises
| Exception | When |
|---|---|
| ValueError | if only one of exposure_time and measurement_time is given, or exposure_duration_years is not a whole number from 1. |
| TypeError | if sex is not a text, or exposure_duration_years is a flag, a text or an array where a count of years goes. |
MultipleShockResult
Section titled “MultipleShockResult”MultipleShockResult( sex: Literal['male', 'female'], acceleration_dose: float, daily_dose: float, compression_dose: float, risk: float, probability: float, start_age: float, exposure_duration_years: int, days_per_year: float, peaks: NumericArrayLike, risk_thresholds: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],)Multiple-shock health assessment (ISO 2631-5:2018, Clause 5 + Annex C).
Attributes
| Name | Description |
|---|---|
sex |
"male" or "female". |
acceleration_dose |
The acceleration dose , m/s2. |
daily_dose |
The daily acceleration dose , m/s2. |
compression_dose |
The daily compressive stress , MPa. |
risk |
The cumulative stress variable . |
probability |
The probability of lumbar injury in 0-1. |
start_age |
Age at which the exposure started, in years. |
exposure_duration_years |
Number of exposure years. |
days_per_year |
Number of exposure days per year. |
peaks |
The positive response peaks used for the dose, m/s2. |
risk_thresholds |
The values for 10 %, 50 % and 90 % risk of injury for this sex (Table C.2). |
MultipleShockResult.plot()
Section titled “MultipleShockResult.plot()”MultipleShockResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the injury-probability curve with this assessment’s .
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
MultipleShockResult.report()
Section titled “MultipleShockResult.report()”MultipleShockResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender a whole-body multiple-shock health-risk fiche to a PDF.
Writes a one-page health-risk assessment sheet for whole-body vibration
containing multiple shocks (ISO 2631-5:2018): the standard-basis line
(Clause 5 spinal response and Annex C risk model), an optional metadata
header (client, subject, workplace/vehicle, instrumentation,
calibration), the exposure-scenario grid (subject sex, the age
b at which the exposure started, the number of exposure years
n, the number of exposure days per year N and the number
of counted response shocks), the dose-and-stress analysis table
(the acceleration dose of Formula 3, the daily dose
of Formula 4, the daily compressive stress
of Formula C.1, the cumulative stress variable
of Formula C.3 and the probability of lumbar injury
of Formula C.5), the injury-probability chart, the boxed
and with the Annex C risk classification, a
classification table against the Table C.2 risk levels with a zone
row, and a footer identity/disclaimer block.
The Annex C classification is informative (ISO 2631-5:2018 defines no exposure limit), so the fiche carries a risk-band zone row rather than a PASS/FAIL verdict: is placed among the Table C.2 stress variables for 10 / 50 / 90 % risk of injury (low / moderate / high / very high probability of an adverse health effect), the moderate band matching the Annex C worked example.
Parameters
| Name | Description |
|---|---|
path |
Destination path of the PDF file. |
metadata |
Optional ReportMetadata supplying the header identity (client, specimen the subject, test_room the workplace or vehicle) plus the instrumentation and calibration free-text fields and the footer identity. |
engine |
Rendering back end; only "reportlab" is supported. |
verbose |
Accepted for a uniform .report() signature; the fiche has one stacked body layout, so it has no effect. |
language |
Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator). |
Returns: The written path as a str.
Raises
| Exception | When |
|---|---|
| ValueError | If engine is not "reportlab" or language is unknown. |
| ImportError | If reportlab or matplotlib is not installed. The fiche always embeds the injury-probability chart, so both are required (the [report] and [plot] extras). |
response_peaks
Section titled “response_peaks”response_peaks(response: NumericArrayLike) -> NDArray[np.float64]Positive response peaks (clause 5.3).
A peak is the maximum value of the response between two consecutive zero crossings; only positive peaks are counted.
Parameters
| Name | Description |
|---|---|
response |
The spinal response acceleration . |
Returns: The positive peak values, in the order they occur.
Raises
| Exception | When |
|---|---|
| TypeError | if response holds a text or a value that is not a real number. |
seat_to_spine_transfer
Section titled “seat_to_spine_transfer”seat_to_spine_transfer( frequencies: float | np.floating[Any] | np.integer[Any],) -> complex
seat_to_spine_transfer( frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],) -> NDArray[np.complex128]
seat_to_spine_transfer( frequencies: NumericArrayLike,) -> complex | NDArray[np.complex128]Seat-to-spine transfer function (clause 5.2, Formula 1).
A single complex zero and six complex poles map the seat acceleration to the vertical spinal response; the transmissibility is unity at 0 Hz.
Parameters
| Name | Description |
|---|---|
frequencies |
Frequencies at which to evaluate H, in hertz. |
Returns: The complex frequency response, aligned with frequencies. A complex for a number, an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if frequencies holds a text or a value that is not a real number. |
spinal_response
Section titled “spinal_response”spinal_response( acceleration_m_s2: Signal | NumericArrayLike, fs: float | None = None,) -> NDArray[np.float64]Vertical spinal response (clause 5.2, Formula 2).
Applies the seat-to-spine transfer function to the measured conditioned seat acceleration in the frequency domain and returns the time-domain response by the inverse transform.
The input must already be conditioned as clause 5.1.3 sets out; this function does not condition it. The transfer function is unity at 0 Hz by design (clause 5.2), so an offset left in the record (e.g. the 1 g gravity component of a DC-coupled accelerometer) is passed unattenuated and produces a spurious constant shift in that corrupts the positive response peaks of the dose. The clause checks that upward is positive, cuts out the parts with no contact between the seat pad and the subject and conditions each remaining part separately, checks the anti-aliasing of a resampled record, and corrects the offset so that the recorded acceleration, with the accelerometer at rest (or with a symmetric signal), is (0 ± 0.1) m/s2; it notes that subtraction of the mean may not be appropriate if the recorded acceleration is asymmetric. A record whose accelerometer was in motion at its start or end may be tapered, and the offset-corrected record is then band-limited with a second-order Butterworth high-pass filter at 0.01 Hz and a fourth-order Butterworth low-pass filter at 80 Hz; the band-limiting and weighting filters of ISO 2631-1 should not be applied. NOTE 2 of the clause explains the low corner: a 0.5 Hz high-pass shifts a free fall back to zero before the impact and offsets the impact peak by up to +1 g.
Parameters
| Name | Description |
|---|---|
acceleration_m_s2 |
Measured vertical seat acceleration , conditioned as clause 5.1.3 sets out, m/s2. Accepts a phonometry.io.Signal for its rate; a calibration factor it carries is deliberately not applied, because this quantity is an acceleration in m/s2 and not a pressure. |
fs |
Sampling frequency, in hertz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
Returns: The spinal response acceleration , m/s2, same length.
Raises
| Exception | When |
|---|---|
| ValueError | for a record that is not 1-D, is empty or carries non-finite samples. |
static_stress
Section titled “static_stress”static_stress(mz: float = 0.029) -> floatStatic compressive stress (Annex C), MPa.
Raises
| Exception | When |
|---|---|
| TypeError | if mz is not a single number. |
ultimate_strength
Section titled “ultimate_strength”ultimate_strength( age: float | np.floating[Any] | np.integer[Any], *, sex: Literal['male', 'female'] = 'male',) -> float
ultimate_strength( age: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, sex: Literal['male', 'female'] = 'male',) -> NDArray[np.float64]
ultimate_strength( age: NumericArrayLike, *, sex: Literal['male', 'female'] = 'male',) -> float | NDArray[np.float64]Ultimate lumbar strength at an age (Annex C, Formula C.4).
Parameters
| Name | Description |
|---|---|
age |
Age , in years. |
sex |
"male" or "female" (sets the age slope ). |
Returns: The ultimate strength , MPa; a float for a number; an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if sex is not a text, or age holds a text or a value that is not a real number. |