Ir al contenido

vibration.human.multiple_shock

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

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(
acceleration_m_s2: Signal | NumericArrayLike,
fs: float | None = None,
) -> float

Acceleration 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(daily_dose_value: float, *, mz: float = 0.029) -> float

Daily 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(
dose: float,
exposure_time: float,
measurement_time: float,
) -> float

Daily 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(
doses: NumericArrayLike,
exposure_times: NumericArrayLike,
measurement_times: NumericArrayLike,
) -> float

Daily 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(peaks: NumericArrayLike) -> float

Acceleration 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(
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(
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,
) -> float

Cumulative 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(
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 = ...,
) -> 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 (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(
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(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot 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(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = '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 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(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(
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(
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(mz: float = 0.029) -> float

Static compressive stress (Annex C), MPa.

Raises

Exception When
TypeError if mz is not a single number.
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.