Exam Tracking

Overview

DataMed’s exam tracking system helps clinical staff monitor which examinations and interventions have been completed for each patient throughout their 18-month capita cycle, ensuring comprehensive care and program compliance.

All exam tracking is organized by active Ingreso (admission cycle). Historical exams from previous cycles are preserved separately.

Exam Types Tracked

The system tracks completion of seven clinical examination categories:

Diagnostic Studies

Baseline Polysomnography (PSG Basal)
Titration Polysomnography (PSG Titulación)

Technical Assessments

Technical Monitoring (Adaptación)
Medical Equipment Assignment

Multidisciplinary Care

Psychology Sessions
Nutrition Consultations
Pulmonology Consultations

Follow-Up Documentation

Adaptation Follow-up Notes
General Follow-up Appointments (Seguimiento)

Clinical Record Dashboard

The clinical record view (patient_clinical.html) serves as the central tracking interface for all patient examinations.

Accessing the Dashboard

Navigate to Patient

From Patients → Patient List, click on the patient name

Open Clinical History

Click Clinical History or Historia Clínica button

View Exam Status

The dashboard displays:

All completed exams for the active cycle
Quick-access buttons to register new exams
Chronological listing of each exam type
Last follow-up appointment date

Data Loading Logic

The system uses cycle-specific filtering to display only relevant exams:

# Core tracking logic from views.py:13-58
ingreso_actual = patient.ingresos.filter(estado='ACTIVO').first()

if ingreso_actual:
    # Load all exam types filtered by active admission
    monitoreos = Monitoreo.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    sesiones_psicologia = Psicologia.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    sesiones_nutricion = Nutricion.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    sesiones_neumologia = Neumologia.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    basales = PolisomnografiaBasal.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    titulaciones = PolisomnografiaTitulacion.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    equipos_medicos = EquipoMedico.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    seguimientos_adaptacion = SeguimientoAdaptacion.objects.filter(
        ingreso=ingreso_actual
    ).order_by('-id')
    
    ultima_cita = ingreso_actual.seguimientos.all().order_by(
        '-created_at'
    ).first()
else:
    # No active admission = no exams to display
    monitoreos = sesiones_psicologia = sesiones_nutricion = \
    sesiones_neumologia = basales = titulaciones = \
    equipos_medicos = seguimientos_adaptacion = []
    ultima_cita = None

Key Design Decision: By filtering exams by ingreso=ingreso_actual, the system ensures that when a patient starts a new 18-month cycle (Mes 1), they begin with a clean exam history. Previous cycle data remains in the database but isn’t displayed, preventing confusion.

Exam Completion Indicators

The clinical dashboard provides visual indicators for exam completion status:

Completed Exams
Missing Exams
Last Follow-Up

Each exam type displays:

Count: Number of times exam has been performed this cycle
Latest Date: Most recent exam date
Chronological List: All instances ordered by creation date (newest first)
Details: Key metrics from each exam

Special tracking for the most recent follow-up:

ultima_cita = ingreso_actual.seguimientos.all().order_by(
    '-created_at'
).first()

Displays:

Date of last contact
Type of service provided
Days since last contact

Standard Exam Schedule

While DataMed doesn’t enforce a strict exam schedule, typical sleep apnea programs follow this pattern:

Initial Phase (Months 1-3)

Month 1: Diagnosis

Required Exams:

✅ Baseline Polysomnography
✅ Initial Psychology Assessment
✅ Initial Nutrition Assessment
✅ Pulmonology Consultation

Month 1-2: Titration

Required Exams:

✅ Titration Polysomnography
✅ Medical Equipment Assignment

Month 2-3: Initial Adaptation

Required Exams:

✅ First Technical Monitoring (Week 2)
✅ Follow-up Adaptation Notes
✅ Second Technical Monitoring (Month 1)

Maintenance Phase (Months 3-18)

Quarterly Reviews

Every 3 months:

Technical Monitoring
Psychology (as needed)
Nutrition (as needed)

Ongoing Support

As needed:

Follow-up notes
Equipment adjustments
Pulmonology consults

Tracking by Capita Month

The system calculates the current capita month for scheduling:

# From models.py:167-178
@property
def mes_capita(self):
    """Calcula el mes actual del programa (1 al 18)"""
    if not self.fecha_inicio:
        return 0
    
    hoy = date.today()
    # Cálculo de meses transcurridos
    meses = (hoy.year - self.fecha_inicio.year) * 12 + \
            (hoy.month - self.fecha_inicio.month) + 1
    
    if meses < 1: return 1
    if meses > 18: return 18
    return meses

Capita Month Tracking Examples

Scenario 1: New Patient

Admission date: January 15, 2026
Current date: January 20, 2026
Capita month: 1
Expected exams: Baseline PSG, initial assessments

Scenario 2: Mid-Cycle Patient

Admission date: July 1, 2025
Current date: January 15, 2026
Capita month: 7
Expected exams: Quarterly monitoring

Scenario 3: End of Cycle

Admission date: August 1, 2024
Current date: March 1, 2026
Capita month: 18 (capped)
Action needed: Close cycle or extend

Quick Registration Actions

From the clinical dashboard, staff can quickly register new exams:

Register Basal PSG

Route: /exams/register-basal/<patient_id>/

Register Titulation

Route: /exams/register-titulacion/<patient_id>/

Register Monitoring

Route: /exams/register-monitoreo/<patient_id>/

Register Psychology

Route: /exams/register-psicologia/<patient_id>/

Register Nutrition

Route: /exams/register-nutricion/<patient_id>/

Register Pulmonology

Route: /exams/register-neumologia/<patient_id>/

Assign Equipment

Route: /exams/register-equipo-medico/<patient_id>/

Auto-linking to Active Admission

All exam registration forms automatically link records to the active admission:

Form Processing
Safety Checks

# Standard pattern from views.py
def register_[exam_type](request, patient_id):
    patient = get_object_or_404(Patient, id=patient_id)
    
    # Always get the active admission first
    ingreso_actual = patient.ingresos.filter(
        estado='ACTIVO'
    ).first()
    
    if request.method == 'POST':
        form = [ExamType]Form(request.POST)
        if form.is_valid():
            exam = form.save(commit=False)
            exam.ingreso = ingreso_actual  # Link to active cycle
            exam.registrado_por = request.user  # Audit trail
            exam.save()
            
            messages.success(request, 'Exam registered successfully')
            return redirect('patient_clinical', patient_id=patient.id)

Before registering any exam, verify active admission exists:

if not ingreso_actual:
    messages.error(
        request, 
        'No active admission found for this patient. '
        'Please create a new admission cycle first.'
    )
    return redirect('patients_list')

The commit=False pattern is critical - it prevents immediate database save, allowing the view to set the ingreso relationship and registrado_por audit field before saving.

Exam History Preservation

When a patient completes an 18-month cycle and starts a new one:

Current Cycle Closure

The current admission is marked as TERMINADO:

ingreso.estado = 'TERMINADO'
ingreso.fecha_fin = closure_date
ingreso.motivo = closure_reason
ingreso.save()

New Cycle Creation

A new admission is created:

Ingreso.objects.create(
    paciente=patient,
    fecha_inicio=new_cycle_start_date,
    estado='ACTIVO'
)

Exam History Separation

All previous exams remain linked to the old ingreso_id:

Old exams are NOT visible in the clinical dashboard
New exams are linked to the new ingreso_id
Historical data is preserved for reporting/audits

Querying Historical Exams

To retrieve exams from all cycles (not just active):

# Get all monitoring sessions across all admissions
all_monitoreos = Monitoreo.objects.filter(
    ingreso__paciente=patient
).select_related('ingreso').order_by('-created_at')

# Group by admission cycle
from collections import defaultdict
by_cycle = defaultdict(list)
for mon in all_monitoreos:
    by_cycle[mon.ingreso.id].append(mon)

Completion Reporting

While DataMed doesn’t currently have built-in completion reports, the data structure supports queries like:

Patient Exam Summary
Cohort Completion Rates
Exam Volume by Month

# Count exams for a patient's active cycle
ingreso = patient.ingreso_activo
if ingreso:
    summary = {
        'basal_psg': ingreso.polisomnografias_basales.count(),
        'titulacion_psg': ingreso.polisomnografias_titulaciones.count(),
        'monitoring': ingreso.monitoreos.count(),
        'psychology': ingreso.psicologias.count(),
        'nutrition': ingreso.nutriciones.count(),
        'pulmonology': ingreso.neumologias.count(),
        'equipment': ingreso.equipos_medicos.count(),
        'followups': ingreso.seguimientos_adaptaciones.count()
    }

# Find patients in month 6 with incomplete baseline PSG
from django.db.models import Count

patients_month_6 = Patient.objects.filter(
    ingresos__estado='ACTIVO'
).annotate(
    basal_count=Count('ingresos__polisomnografias_basales')
).filter(
    basal_count=0  # No baseline PSG recorded
)

# Filter manually by capita month
incomplete = []
for p in patients_month_6:
    if p.ingreso_activo and p.ingreso_activo.mes_capita >= 6:
        incomplete.append(p)

# Count exams registered per calendar month
from django.db.models.functions import TruncMonth

monthly_monitoring = Monitoreo.objects.annotate(
    month=TruncMonth('created_at')
).values('month').annotate(
    count=Count('id')
).order_by('month')

Best Practices

Check exam status before each patient visit

Before any clinical encounter, review the clinical dashboard to identify:

Which exams are overdue
Which exams can be scheduled
What data is needed for treatment decisions

Enter exam data immediately after completion to:

Maintain accurate tracking
Enable data-driven follow-up decisions
Ensure audit trail integrity

Use capita month for scheduling

Schedule exams based on the patient’s current capita month:

Months 1-3: Intensive evaluation phase
Months 4-18: Maintenance monitoring

Verify active admission before registration

Always confirm the patient has an active admission before attempting to register exams. The system requires an active cycle for data association.

Get Started

Core Features

User Guides

Medical Modules

Overview

Exam Types Tracked

Diagnostic Studies

Technical Assessments

Multidisciplinary Care

Follow-Up Documentation

Clinical Record Dashboard

Accessing the Dashboard

Data Loading Logic

Exam Completion Indicators

Standard Exam Schedule

Initial Phase (Months 1-3)

Maintenance Phase (Months 3-18)

Quarterly Reviews

Ongoing Support

Tracking by Capita Month

Quick Registration Actions

Register Basal PSG

Register Titulation

Register Monitoring

Register Psychology

Register Nutrition

Register Pulmonology

Assign Equipment

Auto-linking to Active Admission

Exam History Preservation

Completion Reporting

Best Practices

Next Steps

Clinical Records

Follow-Up System

Build docs developers (and LLMs) love

Get Started

Core Features

User Guides

Medical Modules

Documentation Index

​Overview

​Exam Types Tracked

Diagnostic Studies

Technical Assessments

Multidisciplinary Care

Follow-Up Documentation

​Clinical Record Dashboard

​Accessing the Dashboard

​Data Loading Logic

​Exam Completion Indicators

​Standard Exam Schedule

​Initial Phase (Months 1-3)

​Maintenance Phase (Months 3-18)

Quarterly Reviews

Ongoing Support

​Tracking by Capita Month

​Quick Registration Actions

Register Basal PSG

Register Titulation

Register Monitoring

Register Psychology

Register Nutrition

Register Pulmonology

Assign Equipment

​Auto-linking to Active Admission

​Exam History Preservation

​Completion Reporting

​Best Practices

​Next Steps

Clinical Records

Follow-Up System

Build docs developers (and LLMs) love

Overview

Exam Types Tracked

Clinical Record Dashboard

Accessing the Dashboard

Data Loading Logic

Exam Completion Indicators

Standard Exam Schedule

Initial Phase (Months 1-3)

Maintenance Phase (Months 3-18)

Tracking by Capita Month

Quick Registration Actions

Auto-linking to Active Admission

Exam History Preservation

Completion Reporting

Best Practices

Next Steps