ecg-records API (ecgfeat)¶
Module ecgfeat — version 0.3.2.
| Name | Kind | Signature | Summary |
|---|---|---|---|
ecg_record |
function | (ecg: 'Any', *, sampling_rate: 'float \| None' = None, lead_names: 'Sequence[str] \| str \| None' = None, amplitude_unit: 'str \| None' = None, patient: 'Any' = None, method: 'str' = 'default', profile: 'str' = 'summary', config: 'ECGConfig \| None' = None, input_mode: 'str \| None' = None, record_id: 'str \| None' = None) -> 'ECGRecord' |
Measure an ECG and return one validated, versioned ECG Record. |
record_from_file |
function | (path: 'str \| Path', *, sampling_rate: 'float \| None' = None, lead_names: 'Sequence[str] \| None' = None, amplitude_unit: 'str \| None' = None, channels: 'Sequence[str] \| None' = None, start_s: 'float' = 0.0, end_s: 'float \| None' = None, **options: 'Any') -> 'ECGRecord' |
Read an ECG file with :func:ecgfeat.read_signal and measure it with :func:ecgfeat.ecg_record. |
ecg_record_segments |
function | (ecg: 'Any', *, segment_s: 'float' = 10.0, step_s: 'float \| None' = None, min_segment_s: 'float \| None' = None, sampling_rate: 'float \| None' = None, lead_names: 'Sequence[str] \| str \| None' = None, amplitude_unit: 'str \| None' = None, **options: 'Any') -> 'Iterator[ECGRecord]' |
Yield one ECG Record per segment_s-second window of a long signal. |
read_signal |
function | (path: 'str \| Path', *, sampling_rate: 'float \| None' = None, lead_names: 'Sequence[str] \| None' = None, amplitude_unit: 'str \| None' = None, channels: 'Sequence[str] \| None' = None) |
Read an ECG file into :class:ecgfeat.io.SignalData (channel-major mV, rate, lead names). |
SignalData |
class | (values: 'np.ndarray', sampling_rate: 'float', lead_names: 'tuple[str, ...]', amplitude_unit: 'str', metadata: 'Mapping[str, Any]' = <factory>) -> None |
A decoded ECG: channel-major values, sampling_rate (Hz), one name per row. |
SignalFormatError |
class | (*args: 'str', code: 'str' = 'invalid_signal_file', **details: 'object') -> 'None' |
A signal file could not be read or decoded. |
normalize_lead_name |
function | (name: 'str') -> 'str' |
Canonical spelling of a standard lead name ("AVR" -> "aVR"); other names unchanged. |
load_example |
function | (name: 'str' = 'sinus') |
Load an example ECG as :class:ecgfeat.io.SignalData (channel-major mV). |
list_examples |
function | () -> 'list[str]' |
Names accepted by :func:load_example. |
ecg_prepare |
function | (ecg: 'Any', *, sampling_rate: 'float \| None' = None, lead_names: 'Sequence[str] \| str \| None' = None, amplitude_unit: 'str \| None' = None, patient: 'Any' = None, input_mode: 'str' = 'standard_12') -> 'ECGInput' |
Validate and normalize signal, channel, unit and patient metadata into an immutable input. |
ecg_measure |
function | (prepared: 'ECGInput', *, method: 'str' = 'default', config: 'ECGConfig \| None' = None) -> 'ECGMeasurements' |
Run the measurement pipeline and return measurements plus provenance before profile projection. |
ecg_emit |
function | (measurements: 'ECGMeasurements', *, profile: 'str' = 'summary') -> 'ECGRecord' |
Assemble and validate a versioned ECG Record for profile from measured quantities. |
ecg_dump |
function | (record: 'ECGRecord', destination: 'Any', *, indent: 'int \| None' = None) -> 'None' |
Serialize an ECG Record as UTF-8 JSON without changing its content (compact unless indent). |
load_record |
function | (source: 'str \| Any \| Mapping[str, Any]', *, validate: "Literal['strict', 'schema', 'none']" = 'strict', sidecar: 'str \| Any \| bytes \| None' = None) -> 'ECGRecord' |
Load a record; a dense NPZ sidecar is resolved next to a record file. |
validate_record |
function | (record: 'ECGRecord \| Mapping[str, Any]', *, level: "Literal['strict', 'schema']" = 'strict') -> 'ECGRecord' |
Validate a record (strict adds cross-field checks) and return it as an ECGRecord. |
record_to_dict |
function | (record: 'ECGRecord') -> 'dict[str, Any]' |
Return a detached mapping without re-projecting the record profile. |
parse_address |
function | (value: 'str') -> 'RecordAddress' |
Parse and validate one canonical ecg-record:<record_id>@<schema_version>#<pointer> address. |
resolve_address |
function | (record: 'ECGRecord', address: 'str \| RecordAddress') -> 'AddressResolution' |
Resolve a canonical address against a loaded record after identity and version checks. |
query_measurement |
function | (record: 'ECGRecord', name: 'str', *, lead: 'str \| None' = None, beat: 'int \| None' = None) -> 'MeasurementResult' |
Return one measurement cell with unit, absence state, provenance and validation status. |
query_many |
function | (record: 'ECGRecord', queries: 'Sequence[MeasurementQuery]') -> 'tuple[MeasurementResult, ...]' |
Evaluate measurement queries in input order. |
select_measurements |
function | (record: 'ECGRecord', queries: 'Sequence[MeasurementQuery]') -> 'MeasurementSelection' |
Create an immutable selection of measurement results for export. |
dump_measurements |
function | (selection: 'MeasurementSelection', destination: 'str \| Path \| Any', *, format: "Literal['json', 'jsonl']" = 'json') -> 'None' |
Serialize a measurement selection as JSON or JSON Lines, keeping units, absence and provenance. |
iter_leads |
function | (record: 'ECGRecord') -> 'Iterator[LeadView]' |
Iterate named leads in the record's declared lead order. |
iter_beats |
function | (record: 'ECGRecord', *, lead: 'str \| None' = None) -> 'Iterator[BeatView]' |
Iterate beats (globally or for one lead) using stable beat indices. |
ECGRecord |
class | (record_id: 'str', schema_version: 'str', profile: 'str' = 'all', acquisition: 'Mapping[str, Any]' = <factory>, axes: 'Mapping[str, Any]' = <factory>, quality: 'Mapping[str, Any]' = <factory>, provenance: 'Mapping[str, Any] \| Provenance' = <factory>, delineation: 'Mapping[str, Any]' = <factory>, measurements: 'Mapping[str, Any]' = <factory>, artifacts: 'Mapping[str, Any]' = <factory>, metadata: 'Mapping[str, Any]' = <factory>, validation: 'Mapping[str, FieldValidation]' = <factory>, sidecars: 'tuple[RecordSidecar, ...]' = (), extensions: 'Mapping[str, Any]' = <factory>, debug: 'Mapping[str, Any]' = <factory>, extra_members: 'Mapping[str, Any]' = <factory>, present_optional: 'tuple[str, ...]' = (), sidecar_source: 'Any' = None) -> None |
ECGRecord(record_id: 'str', schema_version: 'str', profile: 'str' = 'all', acquisition: 'Mapping[str, Any]' = |
ECGInput |
class | (signal: 'np.ndarray', sampling_rate: 'float', lead_names: 'tuple[str, ...]', amplitude_unit: 'str', patient: 'Any' = None, input_mode: 'str' = 'standard_12') -> None |
ECGInput(signal: 'np.ndarray', sampling_rate: 'float', lead_names: 'tuple[str, ...]', amplitude_unit: 'str', patient: 'Any' = None, input_mode: 'str' = 'standard_12') |
ECGMeasurements |
class | (prepared: 'ECGInput', legacy_features: 'Any', config: 'ECGConfig', provenance: 'Mapping[str, Any]') -> None |
ECGMeasurements(prepared: 'ECGInput', legacy_features: 'Any', config: 'ECGConfig', provenance: 'Mapping[str, Any]') |
RecordAddress |
class | (record_id: 'str', schema_version: 'str', pointer: 'str') -> None |
RecordAddress(record_id: 'str', schema_version: 'str', pointer: 'str') |
AddressResolution |
class | (address: 'RecordAddress', value: 'Any', node_kind: "Literal['record', 'measurement', 'metadata', 'provenance', 'debug']") -> None |
AddressResolution(address: 'RecordAddress', value: 'Any', node_kind: "Literal['record', 'measurement', 'metadata', 'provenance', 'debug']") |
MeasurementQuery |
class | (name: 'str', lead: 'str \| None' = None, beat: 'int \| None' = None) -> None |
MeasurementQuery(name: 'str', lead: 'str | None' = None, beat: 'int | None' = None) |
MeasurementResult |
class | (name: 'str', address: 'RecordAddress', value: 'int \| float \| str \| bool \| None', unit: 'str \| None', lead: 'str \| None', beat: 'int \| None', absence: 'NullAbsence \| UnmeasurableAbsence \| NotApplicableAbsence \| None', provenance: 'MeasurementProvenance', validation: 'ValidationStatus', feature_state: 'Mapping[str, Any] \| None' = None) -> None |
MeasurementResult(name: 'str', address: 'RecordAddress', value: 'int | float | str | bool | None', unit: 'str | None', lead: 'str | None', beat: 'int | None', absence: 'NullAbsence | UnmeasurableAbsence | NotApplicableAbsence | None', provenance: 'MeasurementProvenance', validation: 'ValidationStatus', feature_state: 'Mapping[str, Any] | None' = None) |
MeasurementSelection |
class | (record_id: 'str', schema_version: 'str', results: 'tuple[MeasurementResult, ...]') -> None |
MeasurementSelection(record_id: 'str', schema_version: 'str', results: 'tuple[MeasurementResult, ...]') |
NullAbsence |
class | (kind: "Literal['null']" = 'null') -> None |
NullAbsence(kind: "Literal['null']" = 'null') |
UnmeasurableAbsence |
class | (reason: 'str', kind: "Literal['unmeasurable']" = 'unmeasurable') -> None |
UnmeasurableAbsence(reason: 'str', kind: "Literal['unmeasurable']" = 'unmeasurable') |
NotApplicableAbsence |
class | (reason: 'str', kind: "Literal['not_applicable']" = 'not_applicable') -> None |
NotApplicableAbsence(reason: 'str', kind: "Literal['not_applicable']" = 'not_applicable') |
MeasurementProvenance |
class | (method_requested: 'str', method_resolved: 'str', config_hash: 'str', fallback_path: 'tuple[str, ...]', field_ref: 'str \| None' = None, field_method: 'str \| None' = None) -> None |
MeasurementProvenance(method_requested: 'str', method_resolved: 'str', config_hash: 'str', fallback_path: 'tuple[str, ...]', field_ref: 'str | None' = None, field_method: 'str | None' = None) |
ValidationStatus |
class | (tier: "Literal['validated', 'partially_validated', 'unvalidated']", evidence: 'str \| None' = None) -> None |
ValidationStatus(tier: "Literal['validated', 'partially_validated', 'unvalidated']", evidence: 'str | None' = None) |
ECGConfig |
class | (input_mode: "Literal['standard_12', 'limited']" = 'standard_12', fs_internal: 'float \| None' = None, mains_frequency_hz: 'Literal[50, 60] \| None' = 50, refinement: 'RefinementConfig' = <factory>, p_wave: 'PWaveConfig' = <factory>, st_amplitude_source: 'STAmplitudeSource' = 'analysis', pacing_detection: "Literal['legacy', 'revised']" = 'revised') -> None |
ECGConfig(input_mode: "Literal['standard_12', 'limited']" = 'standard_12', fs_internal: 'float | None' = None, mains_frequency_hz: 'Literal[50, 60] | None' = 50, refinement: 'RefinementConfig' = |
RefinementConfig |
class | (p_model_arbitration: bool = False, p_multiple_candidates: bool = False, p_boundary_correction: bool = False, t_onset_change_point: bool = False, t_bidirectional: bool = False, t_correlated_fusion: bool = False, qrs_terminal_multiscale: bool = False, qrs_quality_reference: bool = False, representative_robust: bool = False, grouping_outliers: bool = False, p_phasor_candidates: bool = False, t_boundary_projection: bool = False, t_sequence_selection: bool = False, t_projection_offset_only: bool = False, t_sequence_offset_only: bool = False, qrs_adaptive_consensus: bool = False, p_pathology_candidates: bool = False, atrial_event_validation: bool = False, incomplete_rbbb_aha_range: bool = False, preexcitation_strict: bool = False, pr_beat_supported_extremes: bool = False) -> None |
RefinementConfig(p_model_arbitration: bool = False, p_multiple_candidates: bool = False, p_boundary_correction: bool = False, t_onset_change_point: bool = False, t_bidirectional: bool = False, t_correlated_fusion: bool = False, qrs_terminal_multiscale: bool = False, qrs_quality_reference: bool = False, representative_robust: bool = False, grouping_outliers: bool = False, p_phasor_candidates: bool = False, t_boundary_projection: bool = False, t_sequence_selection: bool = False, t_projection_offset_only: bool = False, t_sequence_offset_only: bool = False, qrs_adaptive_consensus: bool = False, p_pathology_candidates: bool = False, atrial_event_validation: bool = False, incomplete_rbbb_aha_range: bool = False, preexcitation_strict: bool = False, pr_beat_supported_extremes: bool = False) |
PWaveConfig |
class | (enabled: 'bool' = True, validate_waveform: 'bool' = True, allow_residual_analysis: 'bool' = True, min_support_beats: 'int' = 1) -> None |
PWaveConfig(enabled: 'bool' = True, validate_waveform: 'bool' = True, allow_residual_analysis: 'bool' = True, min_support_beats: 'int' = 1) |
PatientMeta |
class | (age: 'Optional[float]' = None, age_days: 'Optional[float]' = None, sex: 'Optional[str]' = None, meds: 'Optional[List[str]]' = None, clinical_classifications: 'Optional[List[str]]' = None, device: 'Optional[str]' = None, acquisition_time: 'Optional[str]' = None, amplitude_unit: 'str' = 'mV', gain_uv_per_lsb: 'Optional[float]' = None, adc_full_scale_mv: 'Optional[float]' = None, filter_highpass_hz: 'Optional[float]' = None, filter_lowpass_hz: 'Optional[float]' = None, muscle_filter_enabled: 'Optional[bool]' = None, patient_id: 'Optional[str]' = None) -> None |
PatientMeta(age: 'Optional[float]' = None, age_days: 'Optional[float]' = None, sex: 'Optional[str]' = None, meds: 'Optional[List[str]]' = None, clinical_classifications: 'Optional[List[str]]' = None, device: 'Optional[str]' = None, acquisition_time: 'Optional[str]' = None, amplitude_unit: 'str' = 'mV', gain_uv_per_lsb: 'Optional[float]' = None, adc_full_scale_mv: 'Optional[float]' = None, filter_highpass_hz: 'Optional[float]' = None, filter_lowpass_hz: 'Optional[float]' = None, muscle_filter_enabled: 'Optional[bool]' = None, patient_id: 'Optional[str]' = None) |
STANDARD_12_LEADS |
constant | = ('I', 'II', 'III', 'aVR', 'aVL', 'aVF', 'V1', 'V2', 'V3', 'V4', 'V5', 'V6') |
|
ECGInputError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
Base class for public ECG Record and extraction errors. |
SignalShapeError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
Signal rank, orientation, length, or channel count is invalid. |
LeadNameError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
Lead names are missing, duplicated, or inconsistent with rows. |
SamplingRateError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
Sampling rate or resampling configuration is invalid. |
AmplitudeUnitError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
The declared amplitude unit is unsupported. |
ConfigurationError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A method or configuration value is unsupported or inconsistent. |
RecordValidationError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
An ECG Record violates the supported schema or invariants. |
RecordIdentityError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A canonical address targets another record or schema version. |
AddressSyntaxError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
An ECG Record address or JSON Pointer is malformed. |
AddressNotFoundError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A valid JSON Pointer does not exist in the supplied record. |
MeasurementNotFoundError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A requested published measurement is not present. |
MeasurementSelectorError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A lead or beat selector is invalid for the record axes. |
ComputationInvariantError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A computation invariant prevents trustworthy record construction. |
ECGWarning |
class | `` | Base class for actionable non-fatal ECG API warnings. |
ECGCompatibilityWarning |
class | `` | A legacy compatibility behavior was used. |
ECGDeprecationWarning |
class | `` | A legacy API is scheduled for removal. |
EngineNotInstalledError |
class | (message: 'str', *, code: 'str' = 'engine_not_installed', **details: 'object') -> 'None' |
The numerical engine (ecg-records-engine) is not installed. |
EngineVersionError |
class | (message: 'str', *, code: 'str' = 'engine_version_mismatch', **details: 'object') -> 'None' |
An installed ecg-records-engine does not match this ecg-records version. |
license_info |
function | () -> dict |
Licence status of the installed numerical engine (ecg-records-engine). |
ECGRecordExtractor |
class | (config: 'Any' = None) -> 'None' |
Reusable, stateless extractor around the public record boundary. |
dumps_record |
function | (record: 'ECGRecord', *, profile: 'RecordProfile \| None' = None, indent: 'int \| None' = None) -> 'bytes' |
Canonical UTF-8 JSON bytes of a record: sorted keys, no NaN, compact unless indent. |
loads_record |
function | (data: 'bytes \| str', *, validate: "Literal['strict', 'schema', 'none']" = 'strict') -> 'ECGRecord' |
Parse ECG Record JSON (duplicate members rejected) and validate at validate level. |
serialize_record |
function | (record: 'ECGRecord', *, profile: 'RecordProfile \| None' = None, sidecar_uri: 'str \| None' = None) -> 'SerializedRecord' |
Canonical JSON, optionally moving dense beat/lead matrices to an NPZ sidecar. |
materialize_record |
function | (record: 'ECGRecord') -> 'ECGRecord' |
Return an inline record with every sidecar-backed matrix restored. |
SidecarError |
class | (*args: 'str', code: 'str' = 'ecg_input_error', **details: 'object') -> 'None' |
A sidecar is missing, does not match its descriptor, or is inconsistent. |
Deprecated legacy names¶
Kept for the compatibility window; functions warn on use (ECGDeprecationWarning) and are removed no earlier than 0.3.0. ecgfeat.compat provides the exact legacy contract without warnings.
ECGFeatureExtractorto_dictinterpretload_wfdb_matparse_wfdb_headerplot_beatplot_beat_all_leadsplot_rep_beatplot_quality_summaryECGFeaturesECGInterpretationGlobalFeaturesGroupFeaturesLeadBeatFeaturesLeadQualityPWaveBeatAssessmentPWaveLeadBoundaryQRSDetectorResultQRSCandidateWindowRepresentativeLeadFeaturesWaveBounds