from reportlab.lib import colors
from reportlab.lib.pagesizes import A4
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.lib.enums import TA_CENTER
from reportlab.lib.units import cm
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak, Table, TableStyle, KeepTogether
from reportlab.pdfbase.ttfonts import TTFont
from reportlab.pdfbase import pdfmetrics
from reportlab.lib.colors import HexColor
from reportlab.pdfbase.pdfmetrics import stringWidth
from pathlib import Path

OUT = Path('/tmp/workspace/respiratory-basics-guide/output/Respiratory_Basics_3rd_Year_Study_Guide.pdf')
OUT.parent.mkdir(parents=True, exist_ok=True)

NAVY=HexColor('#12304A'); TEAL=HexColor('#087E8B'); PALE=HexColor('#EAF4F5'); GOLD=HexColor('#F4B942'); RED=HexColor('#B42318'); INK=HexColor('#1E2933'); GREY=HexColor('#59636C')
styles=getSampleStyleSheet()
styles.add(ParagraphStyle(name='Title2', parent=styles['Title'], fontName='Helvetica-Bold', fontSize=25, leading=30, textColor=NAVY, alignment=TA_CENTER, spaceAfter=12))
styles.add(ParagraphStyle(name='Sub', parent=styles['Normal'], fontName='Helvetica', fontSize=11, leading=15, textColor=GREY, alignment=TA_CENTER))
styles.add(ParagraphStyle(name='H1x', parent=styles['Heading1'], fontName='Helvetica-Bold', fontSize=17, leading=22, textColor=NAVY, spaceBefore=10, spaceAfter=9))
styles.add(ParagraphStyle(name='H2x', parent=styles['Heading2'], fontName='Helvetica-Bold', fontSize=12, leading=16, textColor=TEAL, spaceBefore=8, spaceAfter=5))
styles.add(ParagraphStyle(name='Bodyx', parent=styles['BodyText'], fontName='Helvetica', fontSize=9.35, leading=13.2, textColor=INK, spaceAfter=5))
styles.add(ParagraphStyle(name='Small', parent=styles['BodyText'], fontName='Helvetica', fontSize=8.2, leading=10.8, textColor=INK, spaceAfter=3))
styles.add(ParagraphStyle(name='Call', parent=styles['BodyText'], fontName='Helvetica-Bold', fontSize=9.4, leading=13, textColor=NAVY))

def P(x, style='Bodyx'): return Paragraph(x, styles[style])
def bullets(items): return [P('• '+x, 'Bodyx') for x in items]
def tbl(data, widths=None, fs=8.1):
    t=Table([[P(str(c),'Small') for c in row] for row in data], colWidths=widths, repeatRows=1, hAlign='LEFT')
    t.setStyle(TableStyle([('BACKGROUND',(0,0),(-1,0),NAVY),('TEXTCOLOR',(0,0),(-1,0),colors.white),('FONTNAME',(0,0),(-1,0),'Helvetica-Bold'),('VALIGN',(0,0),(-1,-1),'TOP'),('GRID',(0,0),(-1,-1),0.3,HexColor('#B8C6CC')),('ROWBACKGROUNDS',(0,1),(-1,-1),[colors.white,PALE]),('LEFTPADDING',(0,0),(-1,-1),5),('RIGHTPADDING',(0,0),(-1,-1),5),('TOPPADDING',(0,0),(-1,-1),4),('BOTTOMPADDING',(0,0),(-1,-1),4)]))
    return t
def box(title, text, color=PALE):
    t=Table([[P(title,'Call')],[P(text,'Bodyx')]],colWidths=[17.2*cm])
    t.setStyle(TableStyle([('BACKGROUND',(0,0),(-1,0),color),('BACKGROUND',(0,1),(-1,1),HexColor('#F9FCFC')),('BOX',(0,0),(-1,-1),0.5,TEAL),('LEFTPADDING',(0,0),(-1,-1),8),('RIGHTPADDING',(0,0),(-1,-1),8),('TOPPADDING',(0,0),(-1,-1),6),('BOTTOMPADDING',(0,0),(-1,-1),6)]))
    return t
def header_footer(canvas, doc):
    canvas.saveState(); w,h=A4
    canvas.setStrokeColor(TEAL); canvas.setLineWidth(0.8); canvas.line(1.8*cm,h-1.25*cm,w-1.8*cm,h-1.25*cm)
    canvas.setFillColor(NAVY); canvas.setFont('Helvetica-Bold',8); canvas.drawString(1.8*cm,h-0.9*cm,'RESPIRATORY BASICS | 3RD-YEAR STUDY GUIDE')
    canvas.setFillColor(GREY); canvas.setFont('Helvetica',8); canvas.drawRightString(w-1.8*cm,0.8*cm,f'Page {doc.page}')
    canvas.restoreState()

doc=SimpleDocTemplate(str(OUT),pagesize=A4,rightMargin=1.8*cm,leftMargin=1.8*cm,topMargin=1.7*cm,bottomMargin=1.45*cm)
story=[]
# Cover
story += [Spacer(1,2.7*cm), P('RESPIRATORY BASICS','Title2'), P('A focused clinical study guide for 3rd-year students','Sub'), Spacer(1,.5*cm)]
story.append(Table([[P('<b>What this guide covers</b><br/>Applied anatomy, mechanics of breathing, lung volumes, gas exchange, oxygen transport, control of ventilation, respiratory history and examination, chest X-ray approach, spirometry, ABG interpretation, and common clinical patterns.','Bodyx')]],colWidths=[15.7*cm],style=[('BACKGROUND',(0,0),(-1,-1),PALE),('BOX',(0,0),(-1,-1),0.6,TEAL),('LEFTPADDING',(0,0),(-1,-1),13),('RIGHTPADDING',(0,0),(-1,-1),13),('TOPPADDING',(0,0),(-1,-1),12),('BOTTOMPADDING',(0,0),(-1,-1),12)]))
story += [Spacer(1,.8*cm), P('<b>How to use it</b>', 'H2x')]
story += bullets(['Read the physiology sections first, then practise the clinical examination aloud in the exact order shown.', 'Use the investigation tables as rapid revision tools. Values are adult reference approximations: follow local laboratory and guideline ranges in clinical practice.', 'This is an educational guide, not a prescribing or emergency protocol. Escalate an acutely unwell patient to local senior/emergency care.'])
story += [Spacer(1,1.5*cm), P('Prepared September 2026', 'Sub'), PageBreak()]
# contents
story += [P('Contents','H1x')]
for x in ['1. The respiratory system at a glance','2. Applied anatomy and airway defence','3. Mechanics of breathing and lung volumes','4. Gas exchange, V/Q and oxygen carriage','5. Control of breathing and acid-base basics','6. Respiratory history and examination','7. Core investigations: CXR, pulse oximetry and spirometry','8. Arterial blood gases: a practical method','9. Symptom patterns and red flags','10. OSCE checklist, viva questions and self-test','References']:
    story.append(P(x,'Bodyx'))
story += [Spacer(1,.2*cm),box('Exam strategy','For every respiratory presentation answer six questions: <b>Where is the lesion?</b> (airway, alveoli, pleura, vessels, chest wall, neuromuscular); <b>what is the physiological problem?</b> (obstruction, restriction, V/Q mismatch, shunt, hypoventilation); <b>is the patient hypoxemic or hypercapnic?</b>; <b>what examination signs support it?</b>; <b>which test confirms it?</b>; and <b>is there a time-critical threat?</b>.')]
# 1
story += [PageBreak(),P('1. The respiratory system at a glance','H1x'),P('The respiratory system brings oxygen (O<sub>2</sub>) to blood and removes carbon dioxide (CO<sub>2</sub>). This requires a patent airway, ventilated alveoli, perfused pulmonary capillaries, an intact alveolar-capillary membrane, adequate hemoglobin and cardiac output, and tissues able to use oxygen.','Bodyx')]
story.append(tbl([['Level','Main role','Clinical examples'],['Conducting zone: nose to terminal bronchioles','Warms, humidifies, filters and conducts air. No gas exchange.','Upper-airway obstruction, asthma/COPD, mucus retention.'],['Respiratory zone: respiratory bronchioles to alveoli','Gas exchange across a very thin membrane.','Pneumonia, pulmonary edema, interstitial lung disease.'],['Pulmonary circulation','Carries deoxygenated blood to alveoli; low-pressure system.','Pulmonary embolism, pulmonary hypertension.'],['Pump: CNS, nerves, muscles, chest wall','Creates pressure changes that ventilate lungs.','Neuromuscular weakness, obesity hypoventilation, chest-wall disease.']],[3.2*cm,6.7*cm,7.3*cm]))
story += [P('Key equations','H2x'),P('<b>Minute ventilation (V̇E)</b> = respiratory rate × tidal volume (V<sub>T</sub>).<br/><b>Alveolar ventilation (V̇A)</b> = respiratory rate × (V<sub>T</sub> − dead-space volume).<br/><b>PaCO<sub>2</sub></b> is inversely proportional to alveolar ventilation: hypoventilation raises PaCO<sub>2</sub>; hyperventilation lowers it.','Bodyx'),box('High-yield distinction','A rapid shallow pattern can maintain minute ventilation but deliver poor alveolar ventilation because a larger fraction of each breath occupies anatomical dead space. A larger tidal volume at the same minute ventilation is more efficient for CO<sub>2</sub> clearance, but may increase work of breathing.','HexColor('#FFF7E0'))]
#2
story += [P('2. Applied anatomy and airway defence','H1x'),P('Air passes from nose/mouth to pharynx, larynx, trachea, main bronchi, progressively smaller bronchi and bronchioles, then alveoli. The right main bronchus is shorter, wider and more vertical than the left, so aspirated material more often enters the right lung, commonly lower-lobe segments in an upright patient.','Bodyx')]
story.append(tbl([['Structure','Clinical relevance'],['Pleura','Visceral pleura covers lung; parietal pleura lines chest wall. The potential space normally contains a small amount of fluid. Air causes pneumothorax; fluid causes pleural effusion.'],['Alveoli','Type I pneumocytes form the gas-exchange surface. Type II cells produce surfactant, reducing surface tension and preventing alveolar collapse.'],['Mucociliary escalator','Ciliated epithelium moves mucus and trapped particles upward. Smoking impairs this defence.'],['Cough reflex','Protects lower airways. Ineffective cough risks secretion retention and atelectasis.'],['Pulmonary vs bronchial circulation','Pulmonary circulation enables gas exchange; bronchial circulation nourishes airway tissues and may be a source of hemoptysis.']],[4.2*cm,13*cm]))
story += [box('Surface anatomy to remember','Apices extend about 2-3 cm above medial clavicles. Inferior lung border in quiet breathing: approximately 6th rib midclavicular, 8th rib midaxillary, 10th rib posteriorly. The posterior chest gives the best access to lower lobes. The right middle lobe and lingula are mainly assessed anteriorly/laterally.')]
#3
story += [PageBreak(),P('3. Mechanics of breathing and lung volumes','H1x'),P('Inspiration is normally active: diaphragm contraction increases thoracic volume and makes intrapleural pressure more negative, lowering alveolar pressure below atmospheric pressure so air enters. Quiet expiration is predominantly passive because of elastic recoil. Forced expiration recruits abdominal and internal intercostal muscles.','Bodyx')]
story.append(tbl([['Term','Meaning / formula','Key clinical point'],['Compliance (ΔV/ΔP)','Distensibility of lung or chest wall.','High in emphysema; low in fibrosis, edema and ARDS.'],['Elastic recoil','Tendency of lung to return to smaller volume.','Reduced in emphysema; increased in fibrosis.'],['Airway resistance','Mostly determined by medium-sized bronchi; rises as radius falls.','Bronchospasm, edema and secretions increase resistance.'],['Dynamic airway compression','During forced expiration, positive pleural pressure can narrow intrathoracic airways.','Exaggerated in COPD due to loss of elastic support.']],[3.5*cm,6*cm,7.7*cm]))
story += [P('Lung volumes and capacities','H2x'),tbl([['Term','Definition'],['VT (tidal volume)','Air inspired/expired in a normal quiet breath, approximately 500 mL in a typical adult.'],['IRV / ERV','Extra volume that can be inspired / expired after a normal breath.'],['RV','Gas remaining after maximal expiration. Cannot be measured by simple spirometry.'],['FRC','Volume at end of normal expiration = ERV + RV. Oxygen reservoir between breaths.'],['VC','Maximum exhaled after maximum inspiration = IRV + VT + ERV.'],['TLC','Volume after maximal inspiration = VC + RV.']],[4*cm,13.2*cm]))
story += [box('Pattern recognition','<b>Obstruction</b>: difficulty getting air out, reduced FEV<sub>1</sub>/FVC, often increased RV and TLC from air trapping/hyperinflation. <b>Restriction</b>: reduced expandable lung volume, reduced TLC, FEV<sub>1</sub> and FVC fall proportionately, so ratio is normal or high.','HexColor('#FFF7E0'))]
# 4
story += [P('4. Gas exchange, V/Q and oxygen carriage','H1x'),P('Gas exchange occurs by diffusion down partial-pressure gradients. A normal lung matches ventilation (V) to perfusion (Q). The overall V/Q ratio is about 0.8, but regional variation is normal: both V and Q are greater at the bases, with Q increasing more.','Bodyx')]
story.append(tbl([['Mechanism of hypoxemia','Clue','Typical examples','Response to supplemental O2'],['Low inspired O2','Low PAO2 with normal A-a gradient.','Altitude.','Usually improves.'],['Hypoventilation','High PaCO2, normal A-a gradient if isolated.','CNS depression, neuromuscular weakness.','Improves, but ventilatory support may be needed.'],['V/Q mismatch','Raised A-a gradient.','Asthma/COPD, pneumonia, pulmonary edema, PE.','Usually improves.'],['Right-to-left shunt','Perfusion without ventilation.','Consolidation, atelectasis, intracardiac shunt.','May respond poorly if large.'],['Diffusion limitation','Exercise-related desaturation possible.','Interstitial lung disease.','Usually improves.']],[3.2*cm,3.5*cm,5.9*cm,4.6*cm]))
story += [P('Oxygen content: why saturation is not the whole story','H2x'),P('Most O<sub>2</sub> is bound to hemoglobin. Approximate arterial oxygen content: <b>CaO<sub>2</sub> = (1.34 × Hb × SaO<sub>2</sub>) + (0.003 × PaO<sub>2</sub>)</b>. Thus a patient with severe anemia can have normal SpO<sub>2</sub> but low oxygen content. Pulse oximetry estimates saturation, not PaO<sub>2</sub>, hemoglobin concentration, ventilation or adequacy of tissue perfusion.','Bodyx'),box('Oxyhemoglobin curve','A <b>right shift</b> promotes tissue unloading: increased CO<sub>2</sub>, acidosis, temperature and 2,3-BPG. A <b>left shift</b> increases affinity: decreased CO<sub>2</sub>, alkalosis, hypothermia, fetal Hb and carbon monoxide.','HexColor('#FFF7E0'))]
#5
story += [PageBreak(),P('5. Control of breathing and acid-base basics','H1x'),P('Breathing is generated in the brainstem and modified by chemoreceptors, pulmonary receptors and voluntary cortical control. Central chemoreceptors respond mainly to CSF pH changes induced by CO<sub>2</sub>. Peripheral carotid and aortic bodies respond to hypoxemia, hypercapnia and acidosis. In chronic hypercapnia, oxygen should be prescribed to a target and monitored, not withheld.','Bodyx')]
story.append(tbl([['Primary process','pH','PaCO2','HCO3−','Simple interpretation'],['Respiratory acidosis','↓','↑','Normal initially, then ↑','Alveolar hypoventilation.'],['Respiratory alkalosis','↑','↓','Normal initially, then ↓','Alveolar hyperventilation.'],['Metabolic acidosis','↓','Compensatory ↓','↓','Acid gain / bicarbonate loss.'],['Metabolic alkalosis','↑','Compensatory ↑','↑','Acid loss / bicarbonate gain.']],[3.9*cm,2.1*cm,2.6*cm,2.8*cm,5.8*cm]))
story += [P('Compensation quick reference','H2x'),bullets(['Acute respiratory acidosis: HCO<sub>3</sub><sup>−</sup> rises approximately 1 mmol/L per 10 mmHg rise in PaCO<sub>2</sub>; pH falls around 0.08 per 10 mmHg.', 'Chronic respiratory acidosis: renal compensation takes days; HCO<sub>3</sub><sup>−</sup> rises approximately 3.5-5 mmol/L per 10 mmHg PaCO<sub>2</sub> rise.', 'Always consider a mixed disorder if compensation is not in the expected direction or magnitude.'])
story.append(box('Clinical link','Type 1 respiratory failure: low PaO<sub>2</sub> with normal or low PaCO<sub>2</sub>, commonly from V/Q mismatch, diffusion impairment or shunt. Type 2 respiratory failure: low PaO<sub>2</sub> with raised PaCO<sub>2</sub>, signifying alveolar hypoventilation.','HexColor('#FDECEC')))
#6
story += [P('6. Respiratory history and examination','H1x'),P('Start with stability. A patient who cannot speak full sentences, is exhausted, cyanosed, confused, hypotensive or has a silent chest needs urgent assessment and escalation before a detailed history.','Bodyx')]
story += [P('Focused history','H2x'),tbl([['Feature','Ask specifically','Useful associations'],['Dyspnea','Onset, rest/exertion, progression, orthopnea, triggers.','Asthma/COPD, pneumonia, PE, heart failure, anemia.'],['Cough','Duration, dry/productive, timing, sputum amount/colour.','Acute infection, chronic bronchitis, ILD, postnasal drip.'],['Hemoptysis','Streaks or volume? recurrent? anticoagulants?','Infection, cancer, PE, bronchiectasis. Treat massive bleeding as emergency.'],['Chest pain','Pleuritic, central, exertional, sudden?','PE/pneumothorax/pneumonia; also consider ACS/aortic disease.'],['Wheeze/stridor','Episodic expiratory wheeze? inspiratory noise?','Asthma/COPD; stridor suggests upper airway obstruction.'],['Risk profile','Smoking/vaping, TB contacts, travel, occupation, drugs, immobility, malignancy.','Guides differential and tests.']],[3.2*cm,7*cm,5.7*cm]))
story += [P('Examination sequence: inspect, palpate, percuss, auscultate','H2x'),tbl([['Step','Do','Interpretation'],['General inspection','RR, work of breathing, ability to talk, cyanosis, cachexia, clubbing, oxygen devices.','Tachypnea and accessory-muscle use are severity markers.'],['Hands and face','Clubbing, nicotine stain, flap/tremor, central cyanosis, Horner syndrome.','CO2 retention may cause flap; clubbing occurs in selected chronic lung diseases.'],['Chest inspection','Symmetry, scars, deformity, tracheal position, expansion.','Reduced unilateral movement: effusion, collapse, pneumothorax, consolidation.'],['Palpation','Chest expansion; tactile vocal fremitus.','Fremitus ↑ with consolidation; ↓ with effusion/pneumothorax.'],['Percussion','Compare side to side.','Dull: consolidation/effusion/collapse. Stony dull: effusion. Hyperresonant: pneumothorax/emphysema.'],['Auscultation','Breath sounds, vocal resonance, crackles, wheeze, pleural rub.','Bronchial breathing + increased vocal resonance suggests consolidation.']],[3.2*cm,6.2*cm,6.5*cm]))
#7
story += [PageBreak(),P('7. Core investigations','H1x'),P('Choose tests to answer a clinical question. Interpret investigations alongside history, examination and acuity.','Bodyx')]
story += [P('Chest X-ray: systematic approach','H2x'),bullets(['Confirm patient, date, projection, rotation and inspiratory effort. PA erect films are preferred when feasible; AP portable films magnify the heart.', '<b>A</b>irway: trachea central? carina? <b>B</b>ones/soft tissues: fractures, lesions, subcutaneous emphysema? <b>C</b>ardiomediastinum: heart size, contours, hila? <b>D</b>iaphragms: costophrenic angles, free subdiaphragmatic gas? <b>E</b>verything else: lung fields, pleura, devices.', 'For a subtle opacity, ask: which lobe? Is there volume loss? Are borders silhouetted? Is there air bronchogram? Compare prior imaging.'])
story += [P('Common CXR patterns','H2x'),tbl([['Finding','Likely pattern'],['Consolidation','Air-space opacity, often air bronchograms; may obscure an adjacent heart/diaphragm border (silhouette sign).'],['Pleural effusion','Blunted costophrenic angle and meniscus; large effusion may shift mediastinum away.'],['Pneumothorax','Visceral pleural line with no peripheral lung markings. Tension physiology is a clinical emergency: do not delay treatment for imaging.'],['Atelectasis','Opacity with volume loss and shift of fissures/hila/mediastinum toward the affected side.'],['Pulmonary edema','Often bilateral perihilar/interstitial opacities with possible cardiomegaly and effusions, but patterns vary.']],[4.3*cm,12.9*cm]))
story += [P('Pulse oximetry and spirometry','H2x'),P('<b>Pulse oximetry:</b> interpret waveform and clinical context. Readings can be unreliable with poor perfusion, movement, nail products, some dyes, dyshemoglobinemia and severe anemia. Obtain an ABG when ventilation, pH, PaCO<sub>2</sub> or precise PaO<sub>2</sub> matters.','Bodyx'),tbl([['Spirometry pattern','FEV1','FVC','FEV1/FVC','Next step'],['Obstructive','↓','Normal or ↓','↓','Assess bronchodilator response; lung volumes and DLCO as indicated.'],['Restrictive suggestion','↓','↓','Normal or ↑','Confirm restriction with TLC.'],['Mixed possibility','↓','↓','↓','Measure TLC and assess clinical context.']],[3.2*cm,2.4*cm,2.4*cm,3.1*cm,6.1*cm]))
story += [box('Spirometry quality','Acceptable efforts need a rapid forced start, no cough or early termination, and reproducibility. A low FVC alone does <b>not</b> prove restriction: total lung capacity is required for confirmation.','HexColor('#FFF7E0'))]
#8
story += [P('8. ABG: a practical method','H1x'),P('ABG directly measures pH, PaCO<sub>2</sub> and PaO<sub>2</sub>; bicarbonate is calculated. Record oxygen delivery and FiO<sub>2</sub> at sampling. Typical reference values: pH 7.35-7.45, PaCO<sub>2</sub> 35-45 mmHg, HCO<sub>3</sub><sup>−</sup> 22-26 mmol/L.','Bodyx')]
story += [P('Five-step method','H2x'),bullets(['1. <b>pH:</b> acidemia or alkalemia?', '2. <b>Primary process:</b> does PaCO<sub>2</sub> or HCO<sub>3</sub><sup>−</sup> explain the pH?', '3. <b>Compensation:</b> appropriate? If not, suspect a mixed process.', '4. <b>Oxygenation:</b> is PaO<sub>2</sub> low for the patient’s oxygen delivery? Calculate/consider A-a gradient where appropriate.', '5. <b>Context:</b> acute or chronic? What is the cause and what immediate action is needed?'])
story.append(tbl([['Example','Interpretation'],['pH 7.28 | PaCO2 60 | HCO3 26','Primary acute respiratory acidosis: hypoventilation.'],['pH 7.38 | PaCO2 60 | HCO3 35','Compensated chronic respiratory acidosis is likely, if clinical history supports chronicity.'],['pH 7.50 | PaCO2 28 | HCO3 22','Acute respiratory alkalosis: hyperventilation. Think pain, anxiety, hypoxemia, PE, sepsis, CNS cause or salicylate toxicity.'],['pH 7.25 | PaCO2 30 | HCO3 13','Primary metabolic acidosis with respiratory compensation; assess anion gap and cause.']],[7*cm,10.2*cm]))
story += [box('Safety','A normal or high PaCO<sub>2</sub> in a severely breathless patient may indicate fatigue and impending ventilatory failure. Do not interpret a blood gas in isolation.','HexColor('#FDECEC'))]
#9
story += [PageBreak(),P('9. Symptom patterns and red flags','H1x'),tbl([['Presentation','Think of','Immediate concern'],['Acute severe dyspnea','Asthma/COPD exacerbation, pneumonia, PE, edema, pneumothorax, acidosis.','Airway, severe hypoxemia/hypercapnia, shock, fatigue.'],['Unilateral pleuritic pain + sudden dyspnea','PE, pneumothorax, pneumonia.','Tension pneumothorax or high-risk PE.'],['Fever + focal crackles/bronchial breathing','Pneumonia or aspiration.','Sepsis, hypoxemia, parapneumonic effusion.'],['Chronic progressive dyspnea + dry crackles','Interstitial disease, heart failure, anemia, deconditioning.','Rapid progression, resting hypoxemia.'],['Hemoptysis','Infection, bronchiectasis, cancer, PE, TB.','Large-volume bleeding, airway compromise, instability.'],['Stridor','Upper airway obstruction.','Airway emergency.']],[4.1*cm,7.4*cm,5.7*cm]))
story += [box('Red flags requiring urgent senior/emergency assessment','Severe work of breathing or exhaustion; altered mental status; silent chest; stridor; cyanosis; inability to speak full sentences; hypotension; new arrhythmia/chest pain; rapidly rising oxygen requirement; suspected tension pneumothorax; significant hemoptysis; or a worsening ABG.','HexColor('#FDECEC'))]
#10
story += [P('10. OSCE checklist, viva and self-test','H1x'),P('Respiratory examination OSCE','H2x'),bullets(['Wash hands, introduce yourself, confirm identity, explain and obtain consent. Position patient at 45 degrees and expose chest appropriately.', 'General inspection and observations. Inspect hands, face and neck. Examine anterior and posterior chest systematically: inspection, palpation, percussion and auscultation.', 'Check legs for edema/DVT features where appropriate. Complete with peak flow, spirometry, CXR, ABG or sputum testing as clinically indicated. Thank patient, ensure comfort and summarize findings.', 'State clearly: “I would assess observations and oxygen saturation immediately, and escalate if the patient is unstable.”'])
story += [P('Common viva questions','H2x'),tbl([['Question','Short answer'],['Why does COPD cause a low FEV1/FVC ratio?','Expiratory flow limitation from airway narrowing and loss of elastic recoil causes a disproportionate fall in FEV1.'],['Why may a large pleural effusion cause reduced fremitus?','Fluid in the pleural space separates lung from chest wall and dampens transmission of vocal vibrations.'],['What proves restriction?','A reduced total lung capacity, not simply a low FVC.'],['Why is PaCO2 high in hypoventilation?','CO2 elimination falls when alveolar ventilation is insufficient.'],['What is the difference between dead space and shunt?','Dead space is ventilation without perfusion; shunt is perfusion without ventilation.']],[6.2*cm,11*cm]))
story += [P('Self-test','H2x'),bullets(['1. Give the formula for alveolar ventilation and explain why tachypnea can be inefficient.', '2. Name five mechanisms of hypoxemia and identify the one that may respond poorly to oxygen.', '3. Contrast examination findings in consolidation, pleural effusion and pneumothorax.', '4. Interpret: pH 7.30, PaCO<sub>2</sub> 55 mmHg, HCO<sub>3</sub><sup>−</sup> 26 mmol/L.', '5. Which lung volume must be measured to confirm restrictive disease?'])
story.append(box('Answers','1. V̇A = RR × (VT − VD). Small VT means a greater dead-space fraction. 2. Low inspired O2, hypoventilation, V/Q mismatch, shunt, diffusion limitation; shunt. 3. Consolidation: dull, bronchial breathing, fremitus/resonance increased; effusion: stony dull, reduced breath sounds/fremitus; pneumothorax: hyperresonant, reduced breath sounds/fremitus. 4. Acute respiratory acidosis. 5. TLC.','HexColor('#EAF4F5')))
# references
story += [PageBreak(),P('References and source note','H1x'),P('Core content was synthesized for undergraduate revision from authoritative medical textbooks and current professional clinical resources. Values are approximate adult references and must be interpreted in clinical context.','Bodyx')]
story += bullets(['Ganong’s Review of Medical Physiology, 26th ed., Respiratory Physiology section.', 'Murray & Nadel’s Textbook of Respiratory Medicine, arterial blood gas and respiratory physiology sections.', 'Tintinalli’s Emergency Medicine, respiratory physiology and blood-gas assessment sections.', 'Merck Manual Professional Edition, <i>Overview of Tests of Pulmonary Function</i> and <i>Airflow, Lung Volumes, and Flow-Volume Loop</i>, reviewed April 2026.', 'European Respiratory Society/American Thoracic Society technical standards for lung-volume measurement and pulmonary function reporting.'])
story += [Spacer(1,.6*cm),box('Scope note','This guide teaches foundations and clinical interpretation. It does not replace local protocols, supervisor teaching, imaging reports or emergency pathways. Drug selection and treatment dosing are intentionally outside its scope.','HexColor('#FFF7E0'))]
doc.build(story,onFirstPage=header_footer,onLaterPages=header_footer)
print(OUT)

Successfully replaced 1 instance(s) of the string in '/tmp/workspace/respiratory-basics-guide/src/create_pdf.py'

Successfully replaced 1 instance(s) of the string in '/tmp/workspace/respiratory-basics-guide/src/create_pdf.py'

from reportlab.lib.pagesizes import A4
from reportlab.lib import colors
from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
from reportlab.lib.units import cm
from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak, Table, TableStyle, KeepTogether
from reportlab.pdfbase.ttfonts import TTFont
from reportlab.pdfbase import pdfmetrics
from pathlib import Path

out=Path('/tmp/workspace/respiratory-basics-guide/output/Respiratory_Basics_3rd_Year_Study_Guide.pdf')
out.parent.mkdir(parents=True,exist_ok=True)
styles=getSampleStyleSheet()
styles.add(ParagraphStyle(name='TitleX',parent=styles['Title'],fontName='Helvetica-Bold',fontSize=28,leading=33,textColor=colors.HexColor('#12304A'),spaceAfter=16))
styles.add(ParagraphStyle(name='H1X',parent=styles['Heading1'],fontName='Helvetica-Bold',fontSize=17,leading=21,textColor=colors.HexColor('#0C6471'),spaceBefore=8,spaceAfter=8))
styles.add(ParagraphStyle(name='H2X',parent=styles['Heading2'],fontName='Helvetica-Bold',fontSize=12,leading=15,textColor=colors.HexColor('#12304A'),spaceBefore=8,spaceAfter=5))
styles.add(ParagraphStyle(name='BodyX',parent=styles['BodyText'],fontName='Helvetica',fontSize=9.2,leading=12.4,spaceAfter=5))
styles.add(ParagraphStyle(name='SmallX',parent=styles['BodyText'],fontName='Helvetica',fontSize=8,leading=10))
P=lambda text,style='BodyX': Paragraph(text,styles[style])
def table(rows,widths):
    data=[[P(str(v),'SmallX') for v in r] for r in rows]
    t=Table(data,colWidths=widths,repeatRows=1,hAlign='LEFT')
    t.setStyle(TableStyle([('BACKGROUND',(0,0),(-1,0),colors.HexColor('#0C6471')),('TEXTCOLOR',(0,0),(-1,0),colors.white),('FONTNAME',(0,0),(-1,0),'Helvetica-Bold'),('VALIGN',(0,0),(-1,-1),'TOP'),('GRID',(0,0),(-1,-1),.25,colors.HexColor('#B5CBD0')),('ROWBACKGROUNDS',(0,1),(-1,-1),[colors.white,colors.HexColor('#EFF7F7')]),('LEFTPADDING',(0,0),(-1,-1),5),('RIGHTPADDING',(0,0),(-1,-1),5),('TOPPADDING',(0,0),(-1,-1),4),('BOTTOMPADDING',(0,0),(-1,-1),4)]))
    return t
def box(title,text):
    t=Table([[P('<b>'+title+'</b><br/>'+text,'BodyX')]],colWidths=[17*cm])
    t.setStyle(TableStyle([('BACKGROUND',(0,0),(-1,-1),colors.HexColor('#FFF8DD')),('BOX',(0,0),(-1,-1),.6,colors.HexColor('#D7A71D')),('LEFTPADDING',(0,0),(-1,-1),9),('RIGHTPADDING',(0,0),(-1,-1),9),('TOPPADDING',(0,0),(-1,-1),6),('BOTTOMPADDING',(0,0),(-1,-1),6)]))
    return t
def footer(c,doc):
    c.saveState(); c.setStrokeColor(colors.HexColor('#0C6471')); c.line(1.7*cm,1.1*cm,19.3*cm,1.1*cm)
    c.setFont('Helvetica',8); c.setFillColor(colors.HexColor('#52636B')); c.drawString(1.7*cm,.65*cm,'RESPIRATORY BASICS | 3RD-YEAR STUDY GUIDE'); c.drawRightString(19.3*cm,.65*cm,'Page %d'%doc.page); c.restoreState()
doc=SimpleDocTemplate(str(out),pagesize=A4,rightMargin=1.7*cm,leftMargin=1.7*cm,topMargin=1.55*cm,bottomMargin=1.45*cm)
s=[]
s += [Spacer(1,3*cm),P('RESPIRATORY BASICS','TitleX'),P('Focused clinical study guide for 3rd-year students','H2X'),Spacer(1,.5*cm),box('What this guide covers','Applied anatomy, breathing mechanics, gas exchange, lung volumes, respiratory examination, chest X-ray, spirometry, pulse oximetry, ABG interpretation, red flags, and OSCE revision.'),Spacer(1,1*cm),P('Use it actively: explain each table aloud, then practise the examination sequence at the bedside. Reference values are adult approximations and local ranges take precedence.','BodyX'),PageBreak()]
s += [P('Contents','H1X')]
for x in ['1. System overview and applied anatomy','2. Mechanics, volumes and ventilation','3. Gas exchange, V/Q and oxygen transport','4. Control of breathing and acid-base','5. Respiratory history and examination','6. Investigations: CXR, oximetry and spirometry','7. ABG interpretation','8. Symptom patterns, red flags and OSCE review','References'] : s.append(P(x))
s += [box('Clinical framework','For every patient decide: <b>site</b> (airway, alveoli, pleura, vessels, chest wall, neuromuscular); <b>physiology</b> (obstruction, restriction, V/Q mismatch, shunt or hypoventilation); <b>severity</b>; and <b>time-critical threats</b>.')]
s += [PageBreak(),P('1. System overview and applied anatomy','H1X'),P('The lungs deliver O<sub>2</sub> to pulmonary capillary blood and eliminate CO<sub>2</sub>. Effective gas exchange needs a patent airway, ventilated alveoli, perfusion, an intact alveolar-capillary interface, adequate hemoglobin and cardiac output. The conducting zone ends at terminal bronchioles; gas exchange occurs in respiratory bronchioles and alveoli.'),table([['Structure','Clinical relevance'],['Right main bronchus','Shorter, wider and more vertical. Aspirated material more commonly enters the right lung.'],['Pleura','Visceral pleura covers lung and parietal pleura lines chest wall. Air in the space is pneumothorax; fluid is pleural effusion.'],['Alveoli','Type I cells enable gas exchange. Type II cells secrete surfactant, lowering surface tension and limiting collapse.'],['Mucociliary clearance','Cilia move mucus upward. Smoking impairs this airway defence.'],['Lobar examination','Lower lobes are mainly posterior. Right middle lobe and lingula are better assessed anteriorly/laterally.']],[4.2*cm,12.8*cm]),box('Surface anatomy','Lung apices rise about 2-3 cm above medial clavicles. Inferior border during quiet breathing is roughly rib 6 midclavicular, rib 8 midaxillary and rib 10 posteriorly.')]
s += [PageBreak(),P('2. Mechanics, volumes and ventilation','H1X'),P('Quiet inspiration is active: diaphragm contraction expands the thorax, making pleural pressure more negative and alveolar pressure subatmospheric. Quiet expiration is mainly passive elastic recoil. Forced expiration recruits abdominal and internal intercostal muscles.'),table([['Term','Meaning','Clinical point'],['Compliance','Change in volume/change in pressure.','High in emphysema; low in fibrosis, pulmonary edema and ARDS.'],['Elastic recoil','Tendency of lung to return to smaller volume.','Reduced in emphysema; increased in fibrosis.'],['Airway resistance','Rises as airway radius falls.','Bronchospasm, edema and secretions increase resistance.'],['Dynamic compression','Forced expiration narrows intrathoracic airways.','Worse in COPD because elastic support is lost.']],[3.3*cm,6*cm,7.7*cm]),P('Lung volumes and capacities','H2X'),table([['Term','Definition'],['VT','Tidal volume: air inspired or expired in quiet breathing, about 500 mL in a typical adult.'],['IRV / ERV','Extra volume inspired or expired beyond a normal breath.'],['RV','Gas after maximal expiration. Not measured by simple spirometry.'],['FRC','ERV + RV: volume at end-normal expiration; acts as an O2 reservoir.'],['VC','IRV + VT + ERV: maximum exhaled after maximum inspiration.'],['TLC','VC + RV: volume after maximum inspiration.']],[4*cm,13*cm]),box('Equations','Minute ventilation = respiratory rate × VT. Alveolar ventilation = respiratory rate × (VT - dead-space volume). PaCO<sub>2</sub> varies inversely with alveolar ventilation. Rapid shallow breaths can preserve minute ventilation but reduce alveolar ventilation because proportionally more air enters dead space.')]
s += [PageBreak(),P('3. Gas exchange, V/Q and oxygen transport','H1X'),P('O<sub>2</sub> diffuses from alveoli to blood and CO<sub>2</sub> in the reverse direction. Diffusion depends on surface area, membrane thickness and pressure gradients. Most O<sub>2</sub> is carried bound to hemoglobin; PaO<sub>2</sub> reflects dissolved O<sub>2</sub>, not total O<sub>2</sub> content.'),table([['Mechanism of hypoxemia','Key clue / example','Response to supplemental O2'],['Low inspired O2','Altitude.','Improves.'],['Hypoventilation','High PaCO2, often normal A-a gradient.','Improves.'],['V/Q mismatch','Most common: COPD, asthma, pneumonia, PE.','Usually improves.'],['Diffusion limitation','Fibrosis; worse on exercise.','Improves.'],['Right-to-left shunt','Consolidation, edema, intracardiac shunt.','Less responsive.']],[4*cm,7.1*cm,5.9*cm]),P('Ventilation-perfusion ratio','H2X'),P('Ideal matching is about 0.8 overall. Low V/Q units receive perfusion but insufficient ventilation, causing hypoxemia. High V/Q units are ventilated but underperfused, contributing to physiological dead space. Pulmonary embolism creates high V/Q areas; asthma/COPD and pneumonia cause low V/Q regions. A true shunt means blood bypasses ventilated alveoli.'),box('A-a gradient','Alveolar gas equation: PAO<sub>2</sub> ≈ FiO<sub>2</sub> × (P<sub>B</sub> - P<sub>H2O</sub>) - PaCO<sub>2</sub>/R. A widened A-a gradient supports V/Q mismatch, diffusion impairment or shunt. A normal gradient with hypoxemia suggests hypoventilation or low inspired O2.')]
s += [PageBreak(),P('4. Control of breathing and acid-base','H1X'),P('Medullary and pontine networks generate breathing rhythm. Central chemoreceptors respond mainly to CSF pH changes induced by CO<sub>2</sub>. Peripheral carotid and aortic body chemoreceptors respond to hypoxemia, hypercapnia and acidosis. Work of breathing rises with increased resistance, reduced compliance or respiratory muscle weakness.'),table([['Primary disorder','pH','PaCO2','Expected direction of HCO3-'],['Respiratory acidosis','Low','High','Rises: small acute change; larger renal compensation after days.'],['Respiratory alkalosis','High','Low','Falls: renal compensation takes time.'],['Metabolic acidosis','Low','Low if respiratory compensation appropriate','Low.'],['Metabolic alkalosis','High','High if respiratory compensation appropriate','High.']],[3.7*cm,3.2*cm,4*cm,6.1*cm]),box('ABG normal reference range','pH 7.35-7.45; PaCO<sub>2</sub> 35-45 mmHg; HCO<sub>3</sub><sup>-</sup> roughly 21-27 mmol/L. PaO<sub>2</sub> varies by age and FiO<sub>2</sub>. Interpret in context.')]
s += [PageBreak(),P('5. Respiratory history and examination','H1X'),P('History must establish onset, tempo, severity, triggers and systemic features. Ask about smoking/vaping, TB exposure, travel, allergens, occupation, drugs, thromboembolism risk, cancer, immunosuppression and cardiorespiratory history.'),table([['Symptom','Ask','Important associations'],['Dyspnea','Rest/exertion, onset, progression, orthopnea, triggers.','Asthma/COPD, pneumonia, PE, heart failure, anemia.'],['Cough','Duration, dry/productive, sputum, timing.','Infection, chronic bronchitis, ILD.'],['Hemoptysis','Volume, recurrence, anticoagulants, weight loss.','Cancer, TB, bronchiectasis, PE.'],['Chest pain','Pleuritic, exertional, sudden, central?','PE, pneumothorax, pneumonia; also ACS/aortic disease.'],['Wheeze or stridor','Episodic expiratory wheeze? inspiratory noise?','Asthma/COPD; stridor may indicate upper-airway obstruction.']],[3.1*cm,6.3*cm,7.6*cm]),P('Examination sequence','H2X'),table([['Step','What to look for','Interpretation'],['General inspection','Speech, posture, RR, cyanosis, cachexia, accessory muscles, oxygen.','Inability to speak, exhaustion or altered consciousness is serious.'],['Hands and face','Clubbing, nicotine staining, flap, central cyanosis, nasal disease.','Flap may reflect hypercapnia; clubbing suggests chronic suppurative/ILD/malignancy.'],['Chest inspection','Symmetry, scars, deformity, expansion.','Unilateral reduced movement: effusion, collapse, pneumothorax.'],['Palpation','Trachea, chest expansion, tactile fremitus.','Fremitus increased in consolidation, reduced in effusion/pneumothorax.'],['Percussion','Compare symmetric zones.','Dull: consolidation/effusion/collapse. Hyperresonant: pneumothorax/emphysema.'],['Auscultation','Breath sounds, added sounds, vocal resonance.','Bronchial breathing/crackles: consolidation. Wheeze: narrowed airways. Silent chest: severe obstruction.']],[3.1*cm,6.5*cm,7.4*cm])]
s += [PageBreak(),P('6. Investigations: CXR, oximetry and spirometry','H1X'),P('Choose investigations from the clinical question. A normal test does not override a dangerous clinical presentation.'),P('Chest X-ray: use ABCDE','H2X'),table([['A','Airway: tracheal position, carina, hilar structures.'],['B','Breathing: lung fields, pleura, vascularity, apices and costophrenic angles.'],['C','Cardiac silhouette and mediastinum.'],['D','Diaphragms: shape, position, free subdiaphragmatic air.'],['E','Everything else: bones, soft tissue, lines/devices; compare with old films.']],[3*cm,14*cm]),P('Spirometry','H2X'),table([['Pattern','FEV1','FVC','FEV1/FVC','TLC'],['Obstructive','Reduced','Normal or reduced','Reduced','Normal or increased (air trapping may raise RV).'],['Restrictive','Reduced or normal','Reduced','Normal or increased','Reduced confirms restriction.'],['Mixed','Reduced','Reduced','Reduced','Usually reduced.']],[3*cm,3.2*cm,3.2*cm,4*cm,3.6*cm]),P('FEV1 is forced expiratory volume in 1 second; FVC is forced vital capacity. A reduced ratio suggests airflow obstruction. Spirometry requires acceptable and reproducible effort. Bronchodilator testing can demonstrate reversible airflow limitation, but interpretation should use local standards and clinical context.'),box('Pulse oximetry limitations','SpO2 estimates hemoglobin saturation, not ventilation or PaCO2. It can be unreliable with poor perfusion, movement, nail products, dyshemoglobins and some pigments. A normal SpO2 does not exclude hypercapnia.')]
s += [PageBreak(),P('7. ABG interpretation: a practical method','H1X'),table([['Step','Question','Example'],['1. pH','Acidemia (<7.35) or alkalemia (>7.45)?','pH 7.28 = acidemia.'],['2. Primary process','Does PaCO2 or HCO3- explain pH direction?','High PaCO2 with acidemia = primary respiratory acidosis.'],['3. Compensation','Is compensation plausible for acute/chronic state?','Chronic hypercapnia has greater HCO3- rise than acute.'],['4. Oxygenation','PaO2/SpO2 and FiO2? Calculate A-a gradient if needed.','Hypoxemia plus high PaCO2 suggests hypoventilation.'],['5. Clinical cause','Integrate history, examination and imaging.','COPD exacerbation, CNS depression, neuromuscular weakness.']],[3*cm,6.6*cm,7.4*cm]),P('Worked examples','H2X'),table([['ABG','Interpretation'],['pH 7.29, PaCO2 65, HCO3- 30','Respiratory acidosis with partial compensation. Decide acute versus chronic using history and expected compensation.'],['pH 7.51, PaCO2 28, HCO3- 23','Primary respiratory alkalosis, often acute. Consider pain, anxiety, sepsis, pregnancy, hypoxemia or PE.'],['pH 7.22, PaCO2 25, HCO3- 10','Metabolic acidosis with respiratory compensation. Assess anion gap and cause.']],[6*cm,11*cm]),box('Safety point','ABGs are interpreted with FiO2, timing, perfusion and clinical status. Treat the patient first. Escalate immediately for severe distress, exhaustion, deteriorating consciousness, shock, suspected tension pneumothorax or refractory hypoxemia.')]
s += [PageBreak(),P('8. Symptom patterns, red flags and OSCE review','H1X'),table([['Pattern','Likely physiological clue','Immediate concern'],['Wheeze with prolonged expiration','Airflow obstruction.','Severe asthma: silent chest, fatigue, hypoxemia.'],['Crackles + bronchial breathing + dullness','Alveolar consolidation.','Sepsis or severe pneumonia.'],['Stony dullness + reduced breath sounds/fremitus','Pleural effusion.','Large effusion causing respiratory compromise.'],['Hyperresonance + absent breath sounds','Pneumothorax.','Tension physiology: hypotension, severe distress, tracheal shift late.'],['Sudden dyspnea with pleuritic pain','PE or pneumothorax.','PE with shock; tension pneumothorax.'],['High RR, drowsiness, flap','Possible hypercapnic respiratory failure.','Urgent ABG and senior review.']],[4.6*cm,6.3*cm,6.1*cm]),P('OSCE closing script','H2X'),P('“I would complete vital signs including respiratory rate and SpO2, examine cardiovascular system and legs for DVT signs, review medication and inhaler technique, and obtain appropriate tests such as CXR, ECG, ABG and spirometry when stable. I would assess urgently for respiratory failure, sepsis, PE and pneumothorax.”'),P('Rapid viva questions','H2X')]
for q in ['Why does a high respiratory rate not necessarily mean adequate CO2 clearance?','Why is the FEV1/FVC ratio reduced in obstruction?','What physical signs distinguish pleural effusion from consolidation?','Why can oxygen saturation be normal in hypercapnia?','Give five causes of hypoxemia and identify which usually has a normal A-a gradient.'] : s.append(P('• '+q))
s += [P('References','H1X'),P('Ganong’s Review of Medical Physiology, 26th ed., Respiratory Physiology, pp. 618 onward. Murray & Nadel’s Textbook of Respiratory Medicine, arterial blood gas section. Tintinalli’s Emergency Medicine, respiratory physiology and blood gas assessment. For current PFT interpretation, see the <link href="https://www.merckmanuals.com/professional/pulmonary-disorders/tests-of-pulmonary-function-pft/airflow-lung-volumes-and-flow-volume-loop">Merck PFT overview</link>.')]
doc.build(s,onFirstPage=footer,onLaterPages=footer)
print(out)