Monitoring Module

Overview

The Monitoring module tracks patient adherence to PAP (Positive Airway Pressure) therapy and measures treatment effectiveness through residual apnea indices. It combines technical device data with clinical outcomes to ensure successful therapy adaptation. Model: Monitoreo
Location: apps/exams/models.py:8-64

Monitoring data is automatically linked to the patient’s active admission to ensure proper data isolation between treatment cycles.

Core Data Fields

Adherence Metrics

uso_diario

DecimalField

required

Daily Usage Percentage - Percentage of days the patient used their device

Format: Decimal (5 digits, 2 decimal places)
Range: 0.00 - 100.00
Form Label: “Porcentaje(%) Uso Diario”
Clinical Significance: Primary adherence indicator

dias_uso_horas_4

DecimalField

required

Days with >4 Hours Usage - Percentage of days with at least 4 hours of device use

Format: Decimal (5 digits, 2 decimal places)
Range: 0.00 - 100.00
Form Label: “Porcentaje(%) días uso > 4 horas”
Clinical Standard: Medicare and insurance typically require ≥4 hours/night for 70% of nights

horas_uso_diario

DecimalField

required

Average Daily Usage Hours - Mean hours of device use per night

Format: Decimal (5 digits, 2 decimal places)
Unit: Hours
Form Label: “Horas de uso diario”
Target: ≥4 hours minimum, 6-8 hours optimal

Treatment Effectiveness

hipopnea_basal

DecimalField

required

Baseline AHI - Original apnea-hypopnea index from basal polysomnography

Format: Decimal (5 digits, 2 decimal places)
Form Label: “Indice de apneas BASAL”
Source: Automatically copied from PolisomnografiaBasal.iah
Help Text: “Copiado de la PSG Basal al momento del registro”
UI Behavior: Read-only field (pre-filled from basal study)

hipopnea_residual

DecimalField

required

Residual AHI - Current apnea-hypopnea index while using PAP therapy

Format: Decimal (5 digits, 2 decimal places)
Form Label: “Indice de apneas RESIDUAL”
Clinical Significance: Measures how well treatment controls apnea events
Target: < 5 events/hour indicates effective therapy

porcentaje_correccion

DecimalField

required

Correction Percentage - Percentage improvement in apnea index

Format: Decimal (5 digits, 2 decimal places)
Calculation: ((Basal - Residual) / Basal) × 100
Form Label: “Porcentaje de corrección”
Help Text: “Calculado automáticamente: ((Basal - Residual) / Basal) * 100”
UI Behavior: Auto-calculated, read-only field
Interpretation: Higher is better (>80% is excellent)

Device Settings

Ventilatory Mode

modo_ventilatorio

CharField

required

Type of positive airway pressure therapy being monitoredAvailable Choices:

CPAP - Continuous Positive Airway Pressure (single pressure level)
BPAP - Bilevel Positive Airway Pressure (two pressure levels)
BPAP ST - BiPAP with Spontaneous/Timed backup rate

Form Label: “Modo Ventilatorio”

Pressure Settings

presion_ipap

DecimalField

required

Inspiratory Positive Airway Pressure - Pressure delivered during inhalation

Format: Decimal (5 digits, 2 decimal places)
Unit: cmH₂O
Form Label: “Presion IPAP”
Range: Typically 4-20 cmH₂O
Note: For CPAP mode, this is the single continuous pressure

presion_epap

DecimalField

Expiratory Positive Airway Pressure - Pressure maintained during exhalation

Format: Decimal (5 digits, 2 decimal places)
Unit: cmH₂O
Form Label: “Presion EPAP”
Range: Typically 4-15 cmH₂O
Optional: Only applicable for BiPAP modes (not used for CPAP)

frecuencia_respiratoria

IntegerField

Respiratory Rate - Backup breaths per minute for BiPAP ST mode

Unit: Respirations per minute (rpm)
Form Label: “Frecuencia Respiratoria”
Help Text: “Respiraciones por minuto (rpm)”
Optional: Only applicable for BiPAP ST mode
Typical Range: 8-20 rpm

Mask Interface

mascara_cpap

CharField

required

Type of mask interface the patient is usingAvailable Choices:

PILLOW NASAL - Nasal pillow (minimalist, inserted into nostrils)
NASAL - Nasal mask (covers nose only)
ORONASAL - Full face mask (covers nose and mouth)

Form Label: “Máscara de CPAP” Display Labels:

PILLOW NASAL → “Pillow nasal”
NASAL → “Nasal”
ORONASAL → “Oronasal”

tamano_mascara

CharField

required

Size of the mask fitted to the patientAvailable Choices:

SMALL - Small
MEDIUM - Medium
LARGE - Large

Form Label: “Tamaño de Máscara”

Mask type and size tracking is crucial for troubleshooting adherence issues. Ill-fitting masks are a common cause of poor compliance.

Advanced Monitoring

etco2_promedio

DecimalField

End-Tidal CO₂ Average - Average carbon dioxide levels at the end of exhalation

Format: Decimal (5 digits, 2 decimal places)
Unit: mmHg
Form Label: “EtCO2 Promedio”
Optional: Advanced monitoring for hypoventilation concerns
Normal Range: 35-45 mmHg
Clinical Use: Monitors for CO₂ retention in complex cases

Relationships

ingreso

ForeignKey

Links to the patient’s active admission recordRelated Name: monitoreos
On Delete: CASCADE

registrado_por

ForeignKey

User who registered this monitoring recordRelated Name: monitoreos_registrados
On Delete: SET_NULL

created_at

DateTimeField

Timestamp when this monitoring record was createdAuto-generated: Automatically set on record creation

Registration Workflow

Dual-Form Interface

View: register_monitoreo (apps/exams/views.py:62-117) The monitoring registration page handles two forms simultaneously:

Technical Monitoring Form (MonitoreoForm) - Device data and adherence metrics
Follow-up Notes Form (SeguimientoAdaptacionForm) - Clinical observations

def register_monitoreo(request, patient_id):
    patient = get_object_or_404(Patient, id=patient_id)
    ingreso_actual = patient.ingresos.filter(estado='ACTIVO').first()
    
    # Auto-populate basal IAH from last polysomnography
    psg = PolisomnografiaBasal.objects.filter(
        ingreso=ingreso_actual
    ).last()
    valor_basal = psg.iah if psg else 0
    
    form = MonitoreoForm(initial={'hipopnea_basal': valor_basal})
    seguimiento_form = SeguimientoAdaptacionForm()
    active_tab = 'tecnico'
    
    if request.method == 'POST':
        # Technical monitoring form submitted
        if 'btn_monitoreo' in request.POST:
            form = MonitoreoForm(request.POST)
            if form.is_valid():
                monitoreo = form.save(commit=False)
                monitoreo.ingreso = ingreso_actual
                monitoreo.registrado_por = request.user
                monitoreo.save()
                return redirect('patient_clinical', patient_id=patient.id)
            active_tab = 'tecnico'
        
        # Follow-up notes form submitted
        elif 'btn_contacto' in request.POST:
            seguimiento_form = SeguimientoAdaptacionForm(request.POST)
            if seguimiento_form.is_valid():
                seguimiento = seguimiento_form.save(commit=False)
                seguimiento.ingreso = ingreso_actual
                seguimiento.registrado_por = request.user
                seguimiento.save()
                return redirect('patient_clinical', patient_id=patient.id)
            active_tab = 'contacto'

Key Workflow Features

Automatic Basal IAH Retrieval:

System automatically fetches the last basal polysomnography IAH
Pre-fills hipopnea_basal field (read-only in UI)
Located at apps/exams/views.py:77-79

Tab State Preservation:

active_tab variable maintains which form was submitted
Ensures users stay on the correct tab if validation fails
Technical form errors keep “tecnico” tab active
Follow-up form errors keep “contacto” tab active

Button-Based Form Detection:

btn_monitoreo button submits technical monitoring data
btn_contacto button submits follow-up notes
Prevents form submission conflicts on same page

Clinical Interpretation

Adherence Guidelines

Excellent Adherence

70% or more nights with 4+ hours use, averaging 6-8 hours per night. Meets insurance compliance requirements.

Poor Adherence

Less than 50% of nights with 4+ hours use, averaging under 3 hours per night. Requires intervention and troubleshooting.

Treatment Effectiveness Thresholds

Residual AHI	Interpretation	Action Required
< 5	Excellent control	Continue current therapy
5-10	Adequate control	Monitor closely, minor adjustments if symptoms persist
10-15	Suboptimal control	Pressure adjustment or mask refit needed
> 15	Poor control	Urgent evaluation - check mask leak, pressure settings, compliance

Correction Percentage

# Formula (automatically calculated)
porcentaje_correccion = ((hipopnea_basal - hipopnea_residual) / hipopnea_basal) * 100

Example:

Basal AHI: 32 (severe sleep apnea)
Residual AHI: 3 (excellent control)
Correction: ((32 - 3) / 32) × 100 = 90.6%

A correction percentage of ≥80% indicates highly effective therapy. Lower percentages suggest the need for pressure adjustments, mask refitting, or evaluation for persistent central apnea.

Common Issues and Troubleshooting

Low Adherence Despite Good Residual AHI

Possible Causes:

Mask discomfort or air leak
Claustrophobia
Aerophagia (air swallowing)
Bed partner concerns

Actions:

Check mask fit and size (see mascara_cpap and tamano_mascara fields)
Consider different mask type
Add humidification
Psychology consultation for anxiety (see Psychology Module)

Good Adherence but High Residual AHI

Possible Causes:

Insufficient pressure (IPAP/EPAP too low)
Significant mask leak
Positional apnea
Central sleep apnea component

Actions:

Increase CPAP/BiPAP pressures
Refit mask or change size
Consider switching CPAP → BiPAP or BiPAP → BiPAP ST
Pulmonology referral (see Pulmonology Module)

Elevated EtCO2

Clinical Significance:

EtCO2 > 45 mmHg suggests hypoventilation
Common in obesity hypoventilation syndrome (OHS)
May require BiPAP ST with backup rate

Actions:

Increase pressure support (IPAP - EPAP difference)
Add backup respiratory rate
Consider volumetric modes
Evaluate for supplemental oxygen

Data Retrieval

View: patient_clinical (apps/exams/views.py:28)

# Get all monitoring records for active admission
monitoreos = Monitoreo.objects.filter(
    ingreso=ingreso_actual
).order_by('-id')

Monitoring records are filtered by the patient’s active admission and ordered by ID (most recent first) to show the latest adherence data at the top.

Polysomnography

Basal IAH automatically pulled from basal study

Medical Equipment

Device and mask specifications tracked here

Psychology

Mental health support for adherence issues

Get Started

Core Features

User Guides

Medical Modules

Monitoring Module

Overview

Core Data Fields

Adherence Metrics

Treatment Effectiveness

Device Settings

Ventilatory Mode

Pressure Settings

Mask Interface

Advanced Monitoring

Relationships

Registration Workflow

Dual-Form Interface

Clinical Interpretation

Adherence Guidelines

Excellent Adherence

Poor Adherence

Treatment Effectiveness Thresholds

Correction Percentage

Common Issues and Troubleshooting

Data Retrieval

Polysomnography

Medical Equipment

Psychology

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Medical Modules

Documentation Index

​Overview

​Core Data Fields

​Adherence Metrics

​Treatment Effectiveness

​Device Settings

​Ventilatory Mode

​Pressure Settings

​Mask Interface

​Advanced Monitoring

​Relationships

​Registration Workflow

​Dual-Form Interface

​Clinical Interpretation

​Adherence Guidelines

Excellent Adherence

Poor Adherence

​Treatment Effectiveness Thresholds

​Correction Percentage

​Common Issues and Troubleshooting

​Data Retrieval

​Related Modules

Polysomnography

Medical Equipment

Psychology

Build docs developers (and LLMs) love

Overview

Core Data Fields

Adherence Metrics

Treatment Effectiveness

Device Settings

Ventilatory Mode

Pressure Settings

Mask Interface

Advanced Monitoring

Relationships

Registration Workflow

Dual-Form Interface

Clinical Interpretation

Adherence Guidelines

Treatment Effectiveness Thresholds

Correction Percentage

Common Issues and Troubleshooting

Data Retrieval

Related Modules