coolride-telegram / testing /create_protocol_doc.py
Swaminaatha krishna
chore: frontend wiring audited and secured
3f68f4c
Raw History Blame Contribute Delete
13.8 kB
"""
CoolRide — Field Test Protocol Document Generator
===================================================
Generates a formatted .docx briefing document for testers.
Usage:
python testing/create_protocol_doc.py
"""
import os
from datetime import datetime
try:
from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
HAS_DOCX = True
except ImportError:
HAS_DOCX = False
ROOT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
OUTPUT_DIR = os.path.join(ROOT_DIR, "output")
os.makedirs(OUTPUT_DIR, exist_ok=True)
# ============================================================
# DOCUMENT CONTENT
# ============================================================
def generate_docx():
doc = Document()
# --- Title ---
title = doc.add_heading("CoolRide Field Test Protocol", level=0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER
subtitle = doc.add_heading("Round 2: Kent Ridge Blind A/B Test", level=1)
subtitle.alignment = WD_ALIGN_PARAGRAPH.CENTER
doc.add_paragraph(
f"Date: Tuesday, February 10, 2026 | Time: 3:00 PM — 5:00 PM\n"
f"Location: Kent Ridge Park → Buona Vista\n"
f"Document Generated: {datetime.now().strftime('%Y-%m-%d %H:%M')}"
)
doc.add_paragraph("") # spacer
# --- Objective ---
doc.add_heading("1. Objective", level=2)
doc.add_paragraph(
'Validate the "Sweat Factor" algorithm by testing whether the '
"elevation-aware Cool route produces measurably lower thermal stress "
"and perceived exertion compared to the standard shortest-distance route. "
"This is a BLIND test — testers do NOT know which route is optimized."
)
# --- Roles ---
doc.add_heading("2. Team Assignment", level=2)
table = doc.add_table(rows=3, cols=3)
table.style = "Table Grid"
# Header
for i, text in enumerate(["", "Team Blue", "Team Red"]):
table.rows[0].cells[i].text = text
for p in table.rows[0].cells[i].paragraphs:
for r in p.runs:
r.bold = True
# Data
table.rows[1].cells[0].text = "Route Code"
table.rows[1].cells[1].text = "KR-BLIND-A"
table.rows[1].cells[2].text = "KR-BLIND-B"
table.rows[2].cells[0].text = "KML File"
table.rows[2].cells[1].text = "Route_A_Blue.kml"
table.rows[2].cells[2].text = "Route_B_Red.kml"
doc.add_paragraph("")
# --- Route Codes for Google Form ---
doc.add_heading("3. Route Codes (For Google Form)", level=2)
doc.add_paragraph(
"When filling out the data collection Google Form after each checkpoint:"
)
p = doc.add_paragraph()
p.add_run("Team Blue: ").bold = True
p.add_run('Select "KR-BLIND-A" in the Route ID field.')
p = doc.add_paragraph()
p.add_run("Team Red: ").bold = True
p.add_run('Select "KR-BLIND-B" in the Route ID field.')
# --- The Blind Rule ---
doc.add_heading("4. The Blind Rule", level=2)
p = doc.add_paragraph()
run = p.add_run(
"IMPORTANT: Testers do NOT know which route is the 'Cool' route. "
"Do NOT discuss route characteristics with the other team until "
"AFTER all data has been collected and submitted."
)
run.bold = True
doc.add_paragraph(
"Follow your assigned colored line strictly. Do not deviate or "
"take shortcuts, even if you see a 'better' path. The integrity "
"of the A/B test depends on each tester completing their assigned route."
)
# --- Navigation ---
doc.add_heading("5. Navigation Instructions", level=2)
doc.add_paragraph(
"Load your assigned KML file on Google Maps (or Google Earth). "
"Your route will appear as a colored overlay on the map."
)
p = doc.add_paragraph()
run = p.add_run('DO NOT press "Start Navigation". ')
run.bold = True
p.add_run(
'Use the "Blue Dot" method: follow your position (blue dot) along '
"the colored route line. This prevents Google Maps from rerouting "
"you onto its own path, which would invalidate the test."
)
doc.add_paragraph("Steps to load KML on phone:", style="List Bullet")
doc.add_paragraph("Open the KML file sent via Telegram/WhatsApp.", style="List Bullet 2")
doc.add_paragraph("It will open in Google Earth or Maps automatically.", style="List Bullet 2")
doc.add_paragraph("Your route appears as a colored line with numbered pins.", style="List Bullet 2")
doc.add_paragraph("Follow the line using your GPS blue dot.", style="List Bullet 2")
# --- Checkpoint Protocol ---
doc.add_heading("6. Checkpoint Protocol (Stop & Log)", level=2)
doc.add_paragraph(
"Your route has 5 pins: START, Checkpoint 1 (25%), Checkpoint 2 (50%), "
"Checkpoint 3 (75%), and FINISH. At each numbered checkpoint (1, 2, 3):"
)
doc.add_paragraph("STOP completely. Park your bike safely.", style="List Number")
doc.add_paragraph("Log WBGT reading (if sensor available) or note perceived temperature.", style="List Number")
doc.add_paragraph("Rate your RPE (Rate of Perceived Exertion) on a scale of 1-10.", style="List Number")
doc.add_paragraph("Take the mandatory photos/videos (see Section 7).", style="List Number")
doc.add_paragraph("Submit the Google Form entry for this checkpoint.", style="List Number")
doc.add_paragraph("Continue to the next checkpoint.", style="List Number")
# --- Media Requirements ---
doc.add_heading("7. Media Requirements (MANDATORY)", level=2)
p = doc.add_paragraph()
p.add_run("At EVERY checkpoint, capture ALL of the following:").bold = True
doc.add_paragraph("")
media_table = doc.add_table(rows=4, cols=3)
media_table.style = "Table Grid"
headers = ["#", "Type", "Details"]
for i, h in enumerate(headers):
media_table.rows[0].cells[i].text = h
for p in media_table.rows[0].cells[i].paragraphs:
for r in p.runs:
r.bold = True
media_data = [
("1", "Selfie", "You at the checkpoint location. Must show surroundings (shade/sun)."),
("2", "Video", "5-10 second clip of the route environment (road surface, shade, traffic)."),
("3", "Environment Photo", "Photo looking DOWN the route ahead. Focus on slope/shade/road type."),
]
for row_idx, (num, typ, detail) in enumerate(media_data, 1):
media_table.rows[row_idx].cells[0].text = num
media_table.rows[row_idx].cells[1].text = typ
media_table.rows[row_idx].cells[2].text = detail
doc.add_paragraph("")
doc.add_paragraph(
"Name files with format: [TeamColor]_CP[Number]_[type].[ext]\n"
"Example: Blue_CP2_selfie.jpg, Red_CP1_video.mp4"
)
# --- RPE Scale ---
doc.add_heading("8. RPE Scale Reference", level=2)
rpe_table = doc.add_table(rows=6, cols=2)
rpe_table.style = "Table Grid"
rpe_table.rows[0].cells[0].text = "RPE"
rpe_table.rows[0].cells[1].text = "Description"
for p in rpe_table.rows[0].cells[0].paragraphs:
for r in p.runs: r.bold = True
for p in rpe_table.rows[0].cells[1].paragraphs:
for r in p.runs: r.bold = True
rpe_data = [
("1-2", "Very easy. Barely any effort. Chatting comfortably."),
("3-4", "Easy. Breathing slightly harder. Could sustain for hours."),
("5-6", "Moderate. Noticeable effort. Breathing heavier. Some sweating."),
("7-8", "Hard. Significant effort. Heavy sweating. Difficult to talk."),
("9-10", "Maximum. Cannot sustain. Gasping. Want to stop immediately."),
]
for row_idx, (rpe, desc) in enumerate(rpe_data, 1):
rpe_table.rows[row_idx].cells[0].text = rpe
rpe_table.rows[row_idx].cells[1].text = desc
# --- Safety ---
doc.add_heading("9. Safety Briefing", level=2)
p = doc.add_paragraph()
p.add_run("Kent Ridge has winding roads with vehicle traffic. ").bold = True
p.add_run("Exercise caution at all times.")
doc.add_paragraph("Wear a helmet at all times while cycling.", style="List Bullet")
doc.add_paragraph("Carry at least 500ml of water. Hydrate at every checkpoint.", style="List Bullet")
doc.add_paragraph("Watch for cars on South Buona Vista Road and Kent Ridge Crescent.", style="List Bullet")
doc.add_paragraph("Use hand signals when turning. Make eye contact with drivers.", style="List Bullet")
doc.add_paragraph("If you feel dizzy, nauseous, or overheated — STOP immediately and message the group chat.", style="List Bullet")
doc.add_paragraph("Emergency: Call 995 (Ambulance) or 999 (Police).", style="List Bullet")
p = doc.add_paragraph()
run = p.add_run("ABORT PROTOCOL: ")
run.bold = True
p.add_run(
'If any tester reports heat distress, BOTH teams stop. '
'Send location pin to group chat. Safety > Data.'
)
# --- Timeline ---
doc.add_heading("10. Timeline", level=2)
timeline_table = doc.add_table(rows=7, cols=2)
timeline_table.style = "Table Grid"
timeline_table.rows[0].cells[0].text = "Time"
timeline_table.rows[0].cells[1].text = "Activity"
for p in timeline_table.rows[0].cells[0].paragraphs:
for r in p.runs: r.bold = True
for p in timeline_table.rows[0].cells[1].paragraphs:
for r in p.runs: r.bold = True
timeline = [
("2:45 PM", "Meet at Start Point (Kent Ridge Park). Load KMLs. Brief."),
("3:00 PM", "Both teams depart simultaneously. Start timers."),
("3:00-3:45 PM", "Ride assigned routes. Stop at each checkpoint."),
("3:45 PM", "Expected arrival at Finish (Buona Vista). Final checkpoint."),
("3:45-4:00 PM", "Submit all Google Form entries. Upload media."),
("4:00 PM", "Debrief. Reveal blind key. Discuss experience."),
]
for row_idx, (t, activity) in enumerate(timeline, 1):
timeline_table.rows[row_idx].cells[0].text = t
timeline_table.rows[row_idx].cells[1].text = activity
# --- Footer ---
doc.add_paragraph("")
p = doc.add_paragraph()
p.alignment = WD_ALIGN_PARAGRAPH.CENTER
run = p.add_run("CoolRide — YDCT Project 2026")
run.italic = True
run.font.color.rgb = RGBColor(128, 128, 128)
return doc
# ============================================================
# FALLBACK: Plain text if python-docx unavailable
# ============================================================
def generate_txt():
content = """
================================================================
COOLRIDE FIELD TEST PROTOCOL
Round 2: Kent Ridge Blind A/B Test
================================================================
Date: Tuesday, February 10, 2026 | Time: 3:00 PM - 5:00 PM
Location: Kent Ridge Park -> Buona Vista
1. OBJECTIVE
Validate "Sweat Factor" algorithm by testing elevation-aware
Cool route vs standard shortest-distance route. BLIND test.
2. TEAM ASSIGNMENT
Team Blue: Route KR-BLIND-A | File: Route_A_Blue.kml
Team Red: Route KR-BLIND-B | File: Route_B_Red.kml
3. ROUTE CODES (FOR GOOGLE FORM)
Team Blue: Select "KR-BLIND-A"
Team Red: Select "KR-BLIND-B"
4. THE BLIND RULE
Testers do NOT know which route is 'Cool'.
Follow your assigned colored line STRICTLY.
Do NOT discuss route characteristics until AFTER data submission.
5. NAVIGATION
DO NOT press "Start Navigation".
Use the "Blue Dot" method: follow your GPS position along
the colored route line on Google Maps/Earth.
6. CHECKPOINT PROTOCOL (STOP & LOG)
At each numbered checkpoint (1, 2, 3):
1) STOP completely
2) Log WBGT reading or perceived temperature
3) Rate RPE (1-10)
4) Take mandatory photos/videos
5) Submit Google Form entry
6) Continue to next checkpoint
7. MEDIA REQUIREMENTS (MANDATORY)
At EVERY checkpoint:
1) 1x Selfie at checkpoint (show surroundings)
2) 1x Video of environment (5-10 seconds)
3) 1x Photo looking down route (slope/shade/road type)
8. SAFETY
- Wear helmet at all times
- Carry 500ml+ water, hydrate at every checkpoint
- Watch for cars on South Buona Vista Rd
- If dizzy/nauseous/overheated: STOP, message group chat
- Emergency: 995 (Ambulance) / 999 (Police)
- ABORT: If heat distress, BOTH teams stop. Safety > Data.
9. TIMELINE
2:45 PM Meet at Start. Load KMLs. Brief.
3:00 PM Both teams depart simultaneously.
3:00-3:45 PM Ride routes. Stop at checkpoints.
3:45 PM Arrival at Finish. Final checkpoint.
3:45-4:00 PM Submit forms. Upload media.
4:00 PM Debrief. Reveal blind key. Discuss.
================================================================
CoolRide - YDCT Project 2026
================================================================
"""
return content.strip()
# ============================================================
# MAIN
# ============================================================
if __name__ == "__main__":
print("=" * 60)
print(" PROTOCOL DOCUMENT GENERATOR")
print("=" * 60)
if HAS_DOCX:
doc = generate_docx()
filepath = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.docx")
doc.save(filepath)
print(f"\n Generated (DOCX): {filepath}")
else:
print("\n python-docx not installed. Generating .txt fallback.")
content = generate_txt()
filepath = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.txt")
with open(filepath, "w") as f:
f.write(content)
print(f" Generated (TXT): {filepath}")
# Always generate txt as backup
txt_content = generate_txt()
txt_path = os.path.join(OUTPUT_DIR, "Field_Test_Protocol_Round2.txt")
with open(txt_path, "w") as f:
f.write(txt_content)
print(f" Generated (TXT): {txt_path}")
print("\nDone.")