>Welcome to MedictModelQuestionnaires & Assessments

Questionnaires & Assessments

Learn how to create and manage patient questionnaires and clinical assessments using FHIR resources.

Overview

Questionnaires and assessments are essential tools for collecting structured patient data, conducting clinical evaluations, and monitoring patient outcomes. Medict supports FHIR Questionnaire and QuestionnaireResponse resources for comprehensive assessment workflows.

Creating Questionnaires

Basic Questionnaire Structure

const questionnaire = await client.createResource({
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'PHQ-9 Depression Screening',
  description: 'Patient Health Questionnaire for depression screening',
  subjectType: ['Patient'],
  item: [
    {
      linkId: '1',
      text: 'Over the last 2 weeks, how often have you been bothered by little interest or pleasure in doing things?',
      type: 'choice',
      required: true,
      answerOption: [
        { valueCoding: { code: '0', display: 'Not at all' } },
        { valueCoding: { code: '1', display: 'Several days' } },
        { valueCoding: { code: '2', display: 'More than half the days' } },
        { valueCoding: { code: '3', display: 'Nearly every day' } }
      ]
    },
    {
      linkId: '2',
      text: 'Over the last 2 weeks, how often have you been bothered by feeling down, depressed, or hopeless?',
      type: 'choice',
      required: true,
      answerOption: [
        { valueCoding: { code: '0', display: 'Not at all' } },
        { valueCoding: { code: '1', display: 'Several days' } },
        { valueCoding: { code: '2', display: 'More than half the days' } },
        { valueCoding: { code: '3', display: 'Nearly every day' } }
      ]
    }
  ]
});

Advanced Questionnaire Features

const advancedQuestionnaire = await client.createResource({
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'Comprehensive Health Assessment',
  description: 'Multi-section health assessment form',
  subjectType: ['Patient'],
  item: [
    {
      linkId: 'demographics',
      text: 'Demographics',
      type: 'group',
      item: [
        {
          linkId: 'age',
          text: 'Age',
          type: 'integer',
          required: true,
          validation: {
            minValue: 0,
            maxValue: 120
          }
        },
        {
          linkId: 'gender',
          text: 'Gender',
          type: 'choice',
          required: true,
          answerOption: [
            { valueCoding: { code: 'male', display: 'Male' } },
            { valueCoding: { code: 'female', display: 'Female' } },
            { valueCoding: { code: 'other', display: 'Other' } }
          ]
        }
      ]
    },
    {
      linkId: 'symptoms',
      text: 'Current Symptoms',
      type: 'group',
      item: [
        {
          linkId: 'symptom_list',
          text: 'Please select all symptoms you are currently experiencing:',
          type: 'choice',
          repeats: true,
          answerOption: [
            { valueCoding: { code: 'fever', display: 'Fever' } },
            { valueCoding: { code: 'cough', display: 'Cough' } },
            { valueCoding: { code: 'headache', display: 'Headache' } },
            { valueCoding: { code: 'fatigue', display: 'Fatigue' } }
          ]
        },
        {
          linkId: 'symptom_severity',
          text: 'Rate the severity of your most concerning symptom:',
          type: 'choice',
          enableWhen: [
            {
              question: 'symptom_list',
              operator: 'exists',
              answerBoolean: true
            }
          ],
          answerOption: [
            { valueCoding: { code: '1', display: 'Mild' } },
            { valueCoding: { code: '2', display: 'Moderate' } },
            { valueCoding: { code: '3', display: 'Severe' } }
          ]
        }
      ]
    }
  ]
});

Questionnaire Responses

Creating a Response

const questionnaireResponse = await client.createResource({
  resourceType: 'QuestionnaireResponse',
  status: 'completed',
  questionnaire: 'Questionnaire/questionnaire-id',
  subject: {
    reference: 'Patient/patient-id'
  },
  author: {
    reference: 'Practitioner/practitioner-id'
  },
  authored: new Date().toISOString(),
  item: [
    {
      linkId: '1',
      answer: [
        {
          valueCoding: {
            code: '2',
            display: 'More than half the days'
          }
        }
      ]
    },
    {
      linkId: '2',
      answer: [
        {
          valueCoding: {
            code: '1',
            display: 'Several days'
          }
        }
      ]
    }
  ]
});

Scoring Questionnaires

function calculatePHQ9Score(response) {
  let totalScore = 0;
  
  response.item.forEach(item => {
    if (item.answer && item.answer[0] && item.answer[0].valueCoding) {
      totalScore += parseInt(item.answer[0].valueCoding.code);
    }
  });
  
  let interpretation = '';
  if (totalScore <= 4) {
    interpretation = 'Minimal depression';
  } else if (totalScore <= 9) {
    interpretation = 'Mild depression';
  } else if (totalScore <= 14) {
    interpretation = 'Moderate depression';
  } else if (totalScore <= 19) {
    interpretation = 'Moderately severe depression';
  } else {
    interpretation = 'Severe depression';
  }
  
  return {
    score: totalScore,
    interpretation: interpretation
  };
}

Common Assessment Tools

PHQ-9 Depression Screening

const phq9Questionnaire = {
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'PHQ-9 Depression Screening',
  description: '9-item depression screening tool',
  subjectType: ['Patient'],
  item: [
    {
      linkId: 'q1',
      text: 'Little interest or pleasure in doing things',
      type: 'choice',
      required: true,
      answerOption: [
        { valueCoding: { code: '0', display: 'Not at all' } },
        { valueCoding: { code: '1', display: 'Several days' } },
        { valueCoding: { code: '2', display: 'More than half the days' } },
        { valueCoding: { code: '3', display: 'Nearly every day' } }
      ]
    },
    // ... additional PHQ-9 questions
  ]
};

GAD-7 Anxiety Assessment

const gad7Questionnaire = {
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'GAD-7 Anxiety Assessment',
  description: '7-item generalized anxiety disorder assessment',
  subjectType: ['Patient'],
  item: [
    {
      linkId: 'q1',
      text: 'Feeling nervous, anxious, or on edge',
      type: 'choice',
      required: true,
      answerOption: [
        { valueCoding: { code: '0', display: 'Not at all' } },
        { valueCoding: { code: '1', display: 'Several days' } },
        { valueCoding: { code: '2', display: 'More than half the days' } },
        { valueCoding: { code: '3', display: 'Nearly every day' } }
      ]
    }
    // ... additional GAD-7 questions
  ]
};

Pain Assessment

const painAssessment = {
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'Pain Assessment',
  description: 'Comprehensive pain evaluation',
  subjectType: ['Patient'],
  item: [
    {
      linkId: 'pain_scale',
      text: 'Rate your current pain level (0-10 scale)',
      type: 'integer',
      required: true,
      validation: {
        minValue: 0,
        maxValue: 10
      }
    },
    {
      linkId: 'pain_location',
      text: 'Where is your pain located?',
      type: 'choice',
      repeats: true,
      answerOption: [
        { valueCoding: { code: 'head', display: 'Head' } },
        { valueCoding: { code: 'neck', display: 'Neck' } },
        { valueCoding: { code: 'back', display: 'Back' } },
        { valueCoding: { code: 'chest', display: 'Chest' } },
        { valueCoding: { code: 'abdomen', display: 'Abdomen' } },
        { valueCoding: { code: 'limbs', display: 'Arms/Legs' } }
      ]
    },
    {
      linkId: 'pain_quality',
      text: 'How would you describe your pain?',
      type: 'choice',
      repeats: true,
      answerOption: [
        { valueCoding: { code: 'sharp', display: 'Sharp' } },
        { valueCoding: { code: 'dull', display: 'Dull' } },
        { valueCoding: { code: 'burning', display: 'Burning' } },
        { valueCoding: { code: 'throbbing', display: 'Throbbing' } },
        { valueCoding: { code: 'cramping', display: 'Cramping' } }
      ]
    }
  ]
};

Dynamic Questionnaires

Conditional Logic

const conditionalQuestionnaire = {
  resourceType: 'Questionnaire',
  status: 'active',
  title: 'Conditional Health Assessment',
  subjectType: ['Patient'],
  item: [
    {
      linkId: 'has_diabetes',
      text: 'Do you have diabetes?',
      type: 'boolean',
      required: true
    },
    {
      linkId: 'diabetes_management',
      text: 'How do you manage your diabetes?',
      type: 'choice',
      enableWhen: [
        {
          question: 'has_diabetes',
          operator: '=',
          answerBoolean: true
        }
      ],
      answerOption: [
        { valueCoding: { code: 'diet', display: 'Diet only' } },
        { valueCoding: { code: 'oral', display: 'Oral medication' } },
        { valueCoding: { code: 'insulin', display: 'Insulin' } },
        { valueCoding: { code: 'both', display: 'Oral medication and insulin' } }
      ]
    },
    {
      linkId: 'insulin_type',
      text: 'What type of insulin do you use?',
      type: 'choice',
      enableWhen: [
        {
          question: 'diabetes_management',
          operator: '=',
          answerCoding: { code: 'insulin' }
        }
      ],
      answerOption: [
        { valueCoding: { code: 'rapid', display: 'Rapid-acting' } },
        { valueCoding: { code: 'long', display: 'Long-acting' } },
        { valueCoding: { code: 'mixed', display: 'Mixed' } }
      ]
    }
  ]
};

Assessment Workflows

Complete Assessment Workflow

async function completeAssessment(patientId, questionnaireId, responses) {
  // 1. Get the questionnaire
  const questionnaire = await client.readResource('Questionnaire', questionnaireId);
  
  // 2. Create the response
  const response = await client.createResource({
    resourceType: 'QuestionnaireResponse',
    status: 'completed',
    questionnaire: `Questionnaire/${questionnaireId}`,
    subject: { reference: `Patient/${patientId}` },
    authored: new Date().toISOString(),
    item: responses
  });
  
  // 3. Calculate scores if applicable
  const scores = calculateScores(questionnaire, response);
  
  // 4. Create observation for scores
  if (scores.totalScore !== undefined) {
    await client.createResource({
      resourceType: 'Observation',
      status: 'final',
      code: {
        coding: [{
          system: 'http://loinc.org',
          code: questionnaire.code?.coding?.[0]?.code || 'questionnaire-score',
          display: questionnaire.title
        }]
      },
      subject: { reference: `Patient/${patientId}` },
      valueQuantity: {
        value: scores.totalScore,
        unit: 'score'
      },
      interpretation: [{
        coding: [{
          system: 'http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation',
          code: scores.interpretationCode,
          display: scores.interpretation
        }]
      }]
    });
  }
  
  return { response, scores };
}

Assessment Scheduling

async function scheduleAssessment(patientId, questionnaireId, scheduledDate) {
  const task = await client.createResource({
    resourceType: 'Task',
    status: 'requested',
    intent: 'order',
    description: `Complete assessment: ${questionnaireId}`,
    for: { reference: `Patient/${patientId}` },
    executionPeriod: {
      start: scheduledDate
    },
    input: [{
      type: {
        coding: [{
          system: 'http://hl7.org/fhir/ValueSet/task-code',
          code: 'questionnaire-complete'
        }]
      },
      valueReference: {
        reference: `Questionnaire/${questionnaireId}`
      }
    }]
  });
  
  return task;
}

Best Practices

1. Use Standard Questionnaires

Leverage established assessment tools (PHQ-9, GAD-7, etc.) for better clinical validity.

2. Implement Validation

Add client-side and server-side validation for questionnaire responses.

3. Score Calculations

Implement automated scoring for standardized assessments.

4. Progress Tracking

Track assessment completion and scores over time.

5. Integration

Integrate assessments with clinical workflows and decision support.

Next Steps