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 $m_{z}$ 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 $H (ω)$ (clause 5.2, Formula 1) maps the measured seat acceleration $a_{z} (t)$ to the spinal response acceleration

A_{z} (t) = F^{- 1} [H (ω) F [a_{z} (t)]] (Formula 2)

The standard assumes a conditioned input: $H$ has unity transmissibility at 0 Hz, so any DC offset in the record (e.g. the gravity component of a non-AC-coupled accelerometer) passes straight into $A_{z} (t)$ and corrupts the response peaks; remove the mean (high-pass) before processing. The acceleration dose is

D_{z} = 1.07 (i \sum A_{z, i}^{6})^{1/6} (Formula 3)

over the positive response peaks, scaled to a daily dose

D_{z d} = D_{z} (t_{d} / t_{m})^{1/6} (Formula 4/5)

Annex C turns the daily dose into an injury risk: the daily compressive stress $S_{d}$ (Formula C.1), the age-cumulated stress variable $R$ (Formulae C.3/C.4) and the Weibull probability of lumbar injury $P$ (Formula C.5, Table C.1):

S_{d} = m_{z} D_{z d} (Formula C.1)

R = [i \sum (S_{d} N^{1/6} / (S_{u, i} - S_{stat}))^{6}]^{1/6} (Formulae C.3/C.4)

P = 1 - exp (- (R / α)^{β}) (Formula C.5)

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

acceleration_dose(acceleration: ArrayLike, fs: float) -> float

Acceleration dose $D_{z}$ 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 (DC-removed); see spinal_response.

Parameters

Name	Description
`acceleration`	Measured, conditioned (zero-mean) vertical seat acceleration $a_{z} (t)$ , m/s2.
`fs`	Sampling frequency, in hertz.

Returns: The acceleration dose $D_{z}$ , m/s2.

compression_dose

compression_dose(daily_dose_value: float, *, mz: float = 0.029) -> float

Daily compressive stress $S_{d}$ (Annex C, Formula C.1).

Parameters

Name	Description
`daily_dose_value`	The daily acceleration dose $D_{z d}$ , m/s2.
`mz`	Stress conversion $m_{z}$ (MPa per m/s2); default the 82 kg male value `MZ_MALE`. See `MZ_FEMALE`.

Returns: The daily compressive stress $S_{d} = m_{z} D_{z d}$ , MPa.

daily_dose

daily_dose(
    dose: float,
    exposure_time: float,
    measurement_time: float,
) -> float

Daily acceleration dose $D_{z d}$ (clause 5.3, Formula 4).

Parameters

Name	Description
`dose`	The measured acceleration dose $D_{z}$ , m/s2.
`exposure_time`	Daily exposure period $t_{d}$ (any time unit).
`measurement_time`	Period $t_{m}$ over which $D_{z}$ was measured (same unit as `exposure_time`).

Returns: The daily dose $D_{z d} = D_{z} (t_{d} / t_{m})^{1/6}$ , m/s2.

daily_dose_multi

daily_dose_multi(
    doses: ArrayLike,
    exposure_times: ArrayLike,
    measurement_times: ArrayLike,
) -> float

Daily dose from several exposure conditions (clause 5.3, Formula 5).

Parameters

Name	Description
`doses`	Acceleration dose $D_{z, j}$ of each condition, m/s2.
`exposure_times`	Daily exposure duration $t_{d, j}$ of each condition.
`measurement_times`	Measurement duration $t_{m, j}$ of each condition.

Returns: The combined daily dose $D_{z d} = [\sum_{j} D_{z, j}^{6} (t_{d, j} / t_{m, j})]^{1/6}$ , m/s2.

dose_from_peaks

dose_from_peaks(peaks: ArrayLike) -> float

Acceleration dose $D_{z}$ from response peaks (clause 5.3, Formula 3).

Parameters

Name	Description
`peaks`	The positive response peaks $A_{z, i}$ , m/s2.

Returns: The acceleration dose $D_{z} = 1.07 (\sum A_{z, i}^{6})^{1/6}$ , m/s2.

injury_probability

injury_probability(
    risk: ArrayLike,
    *,
    sex: Literal['male', 'female'] = 'male',
) -> np.ndarray | float

Probability of lumbar injury $P (R)$ (Annex C, Formula C.5).

Parameters

Name	Description
`risk`	The stress variable $R$ (see `injury_risk`); scalar or array-like.
`sex`	`"male"` or `"female"` (sets the Weibull coefficients).

Returns: The injury probability $P = 1 - exp (- (R / α)^{β})$ in 0-1; a float for a scalar input, otherwise an array. Negative $R$ gives 0.

injury_risk

injury_risk(
    daily_compression: float,
    *,
    start_age: float,
    years: int,
    days_per_year: float,
    sex: Literal['male', 'female'] = 'male',
    mz: float | None = None,
) -> float

Cumulative injury stress variable $R$ (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 $S_{d}$ , MPa.
`start_age`	Age $b$ at which the exposure started, in years.
`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 $S_{stat} = m_{z} \cdot 9.81$ ; defaults to the sex-specific value.

Returns: The stress variable $R$ .

Raises

Exception	When
ValueError	if `years` is not positive or the spine strength is exhausted ( $S_{u} - S_{stat} \leq 0$ ) within the exposure period.

multiple_shock_assessment

multiple_shock_assessment(
    acceleration: ArrayLike,
    fs: float,
    *,
    start_age: float,
    years: int,
    days_per_year: float,
    exposure_time: float | None = None,
    measurement_time: float | None = None,
    sex: Literal['male', 'female'] = 'male',
    mz: float | None = None,
) -> MultipleShockResult

Full 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 $R$ (C.3) and injury probability (C.5). The input must be conditioned (DC-removed); 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`	Measured, conditioned (zero-mean) vertical seat acceleration $a_{z} (t)$ , m/s2.
`fs`	Sampling frequency, in hertz.
`start_age`	Age `b` at which the exposure started, in years.
`years`	Number of exposure years `n`.
`days_per_year`	Number of exposure days per year `N`.
`exposure_time`	Daily exposure period $t_{d}$ ; 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 $t_{m}$ over which the record was measured.
`sex`	`"male"` or `"female"`.
`mz`	Stress conversion $m_{z}$ (MPa per m/s2); defaults to the sex-specific value.

Returns: The MultipleShockResult.

MultipleShockResult

MultipleShockResult(
    sex: Literal['male', 'female'],
    acceleration_dose: float,
    daily_dose: float,
    compression_dose: float,
    risk: float,
    probability: float,
    start_age: float,
    years: int,
    days_per_year: float,
    peaks: np.ndarray,
    risk_thresholds: tuple[float, float, float],
)

Multiple-shock health assessment (ISO 2631-5:2018, Clause 5 + Annex C).

Attributes

Name	Description
`sex`	`"male"` or `"female"`.
`acceleration_dose`	The acceleration dose $D_{z}$ , m/s2.
`daily_dose`	The daily acceleration dose $D_{z d}$ , m/s2.
`compression_dose`	The daily compressive stress $S_{d}$ , MPa.
`risk`	The cumulative stress variable $R$ .
`probability`	The probability of lumbar injury $P (R)$ in 0-1.
`start_age`	Age at which the exposure started, in years.
`years`	Number of exposure years.
`days_per_year`	Number of exposure days per year.
`peaks`	The positive response peaks $A_{z, i}$ used for the dose, m/s2.
`risk_thresholds`	The $R$ values for 10 %, 50 % and 90 % risk of injury for this sex (Table C.2).

MultipleShockResult.plot()

MultipleShockResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the injury-probability curve with this assessment’s $R$ .

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

MultipleShockResult.report()

MultipleShockResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render 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 $D_{z}$ of Formula 3, the daily dose $D_{z d}$ of Formula 4, the daily compressive stress $S_{d}$ of Formula C.1, the cumulative stress variable $R$ of Formula C.3 and the probability of lumbar injury $P$ of Formula C.5), the injury-probability chart, the boxed $R$ and $P$ 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: $R$ 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 (`pip install "phonometry[report,plot]"`).

response_peaks

response_peaks(response: ArrayLike) -> np.ndarray

Positive response peaks $A_{z, i}$ (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 $A_{z} (t)$ .

Returns: The positive peak values, in the order they occur.

seat_to_spine_transfer

seat_to_spine_transfer(frequencies: ArrayLike) -> np.ndarray

Seat-to-spine transfer function $H (ω)$ (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.

spinal_response

spinal_response(acceleration: ArrayLike, fs: float) -> np.ndarray

Vertical spinal response $A_{z} (t)$ (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 be conditioned (DC-removed): the transfer function is unity at 0 Hz by design (clause 5.2), so a DC offset (e.g. the 1 g gravity component of a DC-coupled accelerometer) is passed unattenuated and produces a spurious constant shift in $A_{z} (t)$ that corrupts the positive response peaks of the dose. Subtract the mean (or high-pass) of $a_{z} (t)$ before calling.

Parameters

Name	Description
`acceleration`	Measured, conditioned (zero-mean) vertical seat acceleration $a_{z} (t)$ , m/s2.
`fs`	Sampling frequency, in hertz.

Returns: The spinal response acceleration $A_{z} (t)$ , m/s2, same length.

static_stress

static_stress(mz: float = 0.029) -> float

Static compressive stress $S_{stat} = m_{z} \cdot 9.81$ (Annex C), MPa.

ultimate_strength

ultimate_strength(
    age: ArrayLike,
    *,
    sex: Literal['male', 'female'] = 'male',
) -> np.ndarray

Ultimate lumbar strength $S_{u}$ at an age (Annex C, Formula C.4).

Parameters

Name	Description
`age`	Age $b + i$ , in years.
`sex`	`"male"` or `"female"` (sets the age slope $S_{age}$ ).

Returns: The ultimate strength $S_{u} = 6.75 - S_{age} (b + i)$ , MPa.

Created and maintained by José Manuel Requena Plens ORCID All projects