Teaching Lab

Documentation: datadocs.teachinglab.org · Infrastructure: ARCHITECTURE.md (auto-updated from the Posit Connect API) · Open work: OPEN_WORK.md · Why things are this way: DECISIONS.md

R package and scripts for Teaching Lab data operations, dashboards, and automations.

Getting Started

Prerequisites

• R (4.0+)
• RStudio or VSCode
• Access to Teaching Lab’s Qualtrics, Monday.com, and Google accounts

Installation

# Install the package
devtools::install_github("TeachingLabHQ/TeachingLab")

# Load the package
library(TeachingLab)

Environment Setup

The package requires several API credentials. Set these in your .Renviron:

QUALTRICS_API_KEY=your_key
MONDAY_API_KEY_V2=your_key
CONNECT_API_KEY=your_key
CONNECT_SERVER=your_server_url

Organization

Folder	Description
R/	Internal package functions for data fetching, processing, and utilities
posit_automations/	Scheduled automation scripts deployed to Posit Connect (see below)
api/	REST APIs including Monday.com webhook handlers
analysis/	Ad-hoc analyses, reports, and visualizations organized by year
dashboards/	Interactive dashboards for data visualization (some deprecated)
data/	Stored data files and cached datasets
data_scripts/	Legacy data scripts (most moved to posit_automations)
tests/	Package tests
man/	Package documentation
inst/	Rmd templates
html/	HTML template files
images/	Logos, graphics, and visual assets

posit_automations/

Scheduled scripts that run on Posit Connect. Auto-generated index available at posit_automations/INDEX.md.

posit_automations/
├── emails/                  # Automated email scripts
├── reports/                 # Report generation
├── data_updates/            # Monday, Qualtrics, and data sync scripts
├── validation/              # Data validation and quality checks
├── coaching_action_plans/   # CAP-specific scripts
├── misc/                    # One-off and infrastructure scripts
├── cap_targets/             # Targets pipeline for CAP data
├── project_log_targets/     # Targets pipeline for project log
└── deprecated/              # Old scripts kept for reference

The index is automatically regenerated via GitHub Actions when scripts change.

Data Architecture

Teaching Lab’s data platform integrates multiple data sources to track teacher professional learning outcomes. The system connects coaching activities, survey responses, classroom observations, and student work assessments.

Entity Relationships

┌─────────────────────────────────────────────────────────────────────────────────┐
│                           TEACHING LAB DATA MODEL                               │
└─────────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│    SITE      │       │    COACH     │       │   TEACHER    │
│  (District)  │       │  (Employee)  │       │  (Coachee)   │
├──────────────┤       ├──────────────┤       ├──────────────┤
│ site_name    │       │ employee     │       │ teacher_name │
│ content_area │◄──────│ district     │───────►│ school       │
│ subsite      │       │ project      │       │ district     │
│ type         │       │ project_role │       │ content_area │
└──────┬───────┘       └──────┬───────┘       └──────┬───────┘
       │                      │                      │
       │                      │                      │
       │    ┌─────────────────┴─────────────────┐    │
       │    │                                   │    │
       │    ▼                                   ▼    │
       │  ┌──────────────────────────────────────┐   │
       │  │           COACHING LOG               │   │
       │  │         (Session Record)             │   │
       │  ├──────────────────────────────────────┤   │
       │  │ id, Date, employee, District         │   │
       │  │ Subsite, Coachee, hours              │   │
       │  │ session_type, activities             │   │
       └──►│ [Links coach to teacher by session] │◄──┘
          └──────────────────┬───────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          │                  │                  │
          ▼                  ▼                  ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│  IPG OBSERVATION │ │   STUDENT WORK   │ │  EDUCATOR SURVEY │
│ (Classroom Obs)  │ │    (Artifacts)   │ │   (Diagnostic)   │
├──────────────────┤ ├──────────────────┤ ├──────────────────┤
│ date             │ │ Teacher Name     │ │ ResponseId       │
│ site, subsite    │ │ Subject Area     │ │ site             │
│ teacher_select   │ │ Site, Subsite    │ │ prepost          │
│ coach            │ │ Grade Band       │ │ role             │
│ ipg_rubric       │ │ Prepost          │ │ mindsets_ts_*    │
│ content_area     │ │ Submitted Grades │ │ years_teaching   │
│ direct_to_ts_obs │ │ Date Submitted   │ │ grade_level      │
│ k12_m_ca1a..     │ └──────────────────┘ └──────────────────┘
│ k12_ela_ca1a..   │
│ (CA1, CA2, CA3)  │
└──────────────────┘
          │
          │ Timing: BOY/MOY/EOY
          ▼
┌──────────────────────────────────────────────────────────────┐
│                    TRACKER (L&R Board)                       │
│              Aggregated completion status per teacher        │
├──────────────────────────────────────────────────────────────┤
│ participant_name, site_district, school                      │
│ Diagnostic Educator Survey    [TRUE/FALSE/In Progress]       │
│ Followup Educator Survey      [TRUE/FALSE/In Progress]       │
│ Baseline observation          [TRUE/FALSE/In Progress]       │
│ Middle of year observation    [TRUE/FALSE/In Progress]       │
│ End of year observation       [TRUE/FALSE/In Progress]       │
│ Baseline Student Work         [TRUE/FALSE/In Progress]       │
│ Middle of Year Student Work   [TRUE/FALSE/In Progress]       │
│ Followup Student Work         [TRUE/FALSE/In Progress]       │
│ Participant Feedback          [TRUE/FALSE]                   │
└──────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────┐
│              ADDITIONAL SURVEY INSTRUMENTS                   │
├──────────────────────────────────────────────────────────────┤
│ PARTICIPANT FEEDBACK    │ STUDENT SURVEY     │ KNOWLEDGE     │
│ (Session-level)         │ (Classroom-level)  │ ASSESSMENTS   │
├─────────────────────────┼────────────────────┼───────────────┤
│ ResponseId              │ ResponseId         │ id            │
│ RecordedDate            │ RecordedDate       │ prepost       │
│ site                    │ site               │ site, subsite │
│ facilitator             │ grade_level        │ course_name   │
│ course                  │ growth_mindset_*   │ total_score   │
│ satisfaction ratings    │ self_efficacy_*    │ max_possible  │
│ relevance ratings       │ math_enjoyment_*   │               │
│ facilitator ratings     │ achievement_id_*   │               │
└─────────────────────────┴────────────────────┴───────────────┘

Key Relationships

Relationship	Join Keys	Description
Coach → Site	District, site	Coach assigned to partner site/district
Coach → Teacher	employee ↔︎ coach, Coachee ↔︎ teacher_name	Coaching roster assignment
Teacher → IPG	teacher_select, site, subsite	Classroom observations of teacher
Teacher → Student Work	Teacher Name, Site, Subsite	Student work artifacts submitted
Teacher → Educator Survey	site + email/name matching	Pre/post diagnostic surveys
Session → Tracker	Coachee ↔︎ participant_name	Links coaching sessions to completion status
Site → Logistics Board	L&R name, content_area	Routes webhook data to correct Monday board

Data Schemas

Coaching Log (get_coaching_log())

Primary record of coaching sessions from Monday.com.

Column	Type	Description
id	character	Monday.com item ID
employee	character	Coach name
District	character	Partner site (e.g., “NY_D11”, “DC_DCPS”)
Subsite	character	School name
Date	Date	Session date
Coachee	character	Teacher being coached
hours	numeric	Session duration in hours
hours_total	numeric	Total hours submitted
project	character	Project assignment (e.g., “NYC Reads”)
project_role	character	Role in project

Coach Roster (get_coach_roster())

Current coaching assignments linking coaches to teachers.

Column	Type	Description
coach	character	Coach name
teacher_name	character	Coachee/participant name
school	character	School (subsite)
district	character	District/site
content_area	character	Subject area (Math, ELA, Science)
status	character	Active/Inactive

IPG Forms / Classroom Observations (get_ipg_forms())

Instructional Practice Guide classroom observation data.

Column	Type	Description
ResponseId	character	Qualtrics response ID
date	Date	Observation date
site	character	District
subsite	character	School
teacher_select	character	Teacher observed
coach	character	Observer/coach
ipg_rubric	character	Rubric type (Math IPG, ELA IPG, FSOT, TERI, etc.)
content_area	character	Subject (Math, ELA, Science, Social Studies)
direct_to_ts_obs	character	Timing (Baseline, Mid-year, End of year, Ongoing)
k12_m_ca1a..c	character	Math Core Action 1 indicators (Yes/No)
k12_m_ca2a..d	integer	Math Core Action 2 indicators (1-4 scale)
k12_m_ca3a..e	integer	Math Core Action 3 indicators (1-4 scale)
k12_ela_ca1a..c	character	ELA Core Action 1 indicators (Yes/No)
k12_ela_ca2a..d	integer	ELA Core Action 2 indicators (1-4 scale)
k12_ela_ca3a..f	integer	ELA Core Action 3 indicators (1-4 scale)
fsot_ac1..2	integer	FSOT Alphabetic Code indicators (1-4)
fsot_td1..4	integer	FSOT Text Discussion indicators (1-4)
fsot_sp1..4	integer	FSOT Spelling indicators (1-4)
fsot_ad1..2	integer	FSOT Additional indicators (1-3)

IPG Scoring Rules: - Character columns (Yes/No): Yes = TRUE, No = FALSE - Numeric 1-4 columns: 3-4 = TRUE (proficient), 1-2 = FALSE - Numeric 1-3 columns: 2-3 = TRUE, 1 = FALSE - Core Action scores = mean of indicators × 100

Participant Feedback (get_participant_feedback())

Session-level feedback from PD participants.

Column	Type	Description
ResponseId	character	Qualtrics response ID
StartDate	POSIXct	Survey start time
EndDate	POSIXct	Survey end time
RecordedDate	POSIXct	Submission timestamp
Finished	logical	Survey completion status
site	character	Partner site
facilitator	character	Session facilitator
course	character	PD course name
how_much_learned	integer	Learning rating (1-5 Likert)
relevance_to_work	integer	Relevance rating (1-5 Likert)
would_recommend	integer	Recommendation likelihood (1-5)
facilitator_knowledge	integer	Facilitator rating (1-5)
overall_satisfaction	integer	Overall rating (1-5)

Student Survey (get_student_survey())

Student perceptions of classroom instruction.

Column	Type	Description
ResponseId	character	Qualtrics response ID
RecordedDate	POSIXct	Submission timestamp
Finished	logical	Survey completion
site	character	School/district
grade_level	character	Student grade
growth_mindset_1..n	integer	Growth mindset items (1-6 Likert)
achievement_identity_1..n	integer	Achievement identity items (1-6)
self_efficacy_1..n	integer	Self-efficacy items (1-6)
math_enjoyment_1..n	integer	Math enjoyment items (1-6)

Student Survey Domains: - Growth Mindsets - Achievement Identity - Self-Efficacy - Math Enjoyment - Meta-cognition - Value/Importance - Task Persistence - Agency - CRSE Practices

Knowledge Assessments (get_knowledge_assessments())

Pre/post content knowledge assessments for educators.

Column	Type	Description
id	character	Participant identifier
ResponseId	character	Qualtrics response ID
RecordedDate	POSIXct	Submission timestamp
prepost	character	Assessment timing (“pre” or “post”)
site	character	District
subsite	character	School
course_name	character	Assessment/course name
question1	character	Usually “Score”
total_score	integer	Raw score achieved
max_possible	integer	Maximum possible score

Diagnostic/Followup Educator Survey (get_diagnostic_survey(), get_followup_educator())

Teacher beliefs and practices assessment.

Column	Type	Description
ResponseId	character	Qualtrics response ID
RecordedDate	POSIXct	Submission timestamp
Finished	logical	Completion status
site	character	District
prepost	character	Timing (“pre” or “post”)
role	character	Teacher, Coach, Admin, etc.
years_teaching	integer	Years of experience
grade_level	character	Elementary, Middle, High School
mindsets_ts_1_1..14	integer	Teaching staff mindset items (1-6 Likert)
non_ts_mindsets_1..15	integer	Non-teaching staff mindsets (1-6)

Student Work Grades (get_student_work_grades())

Rubric scores for student work artifacts.

Column	Type	Description
Teacher Name	character	Submitting teacher
Subject Area	character	Math, ELA, Science
Site	character	District code
Subsite	character	School name
Student Work File	character	File identifier
Grade Band	character	K-2, 3-5, 6-8, 9-12, Pre-K, etc.
Prepost	character	Pre, Post, Beginning, End
Submitted Grade/s	character	Comma-separated rubric scores (e.g., “2, 1, 2”)
Date of Submission	Date	When submitted

Tracker / L&R Board

Aggregated completion status per teacher (from Monday.com).

Column	Type	Description
participant_name	character	Teacher name
site_district	character	District
school	character	School name
Diagnostic Educator Survey	character	TRUE/FALSE/In Progress
Followup Educator Survey	character	TRUE/FALSE/In Progress
Baseline observation	character	TRUE/FALSE/In Progress
Middle of year observation	character	TRUE/FALSE/In Progress
End of year observation	character	TRUE/FALSE/In Progress
Baseline Student Work	character	TRUE/FALSE/In Progress
Middle of Year Student Work	character	TRUE/FALSE/In Progress
Followup Student Work	character	TRUE/FALSE/In Progress
Participant Feedback	character	TRUE/FALSE

Storage Locations

Data Type	Source	Bucket/Location	File Format
Participant Feedback	Qualtrics	tl-surveys-26	.parquet
Student Survey	Qualtrics	tl-surveys-25	.parquet
IPG Forms	Qualtrics	tl-surveys-26	.parquet
Knowledge Assessments	Qualtrics	tl-surveys-26	.parquet
Diagnostic Survey	Qualtrics	tl-surveys-26	.parquet
Coaching Log	Monday.com	coaching-data-tl	.parquet
Coach Roster	Monday.com	coaching-data-tl	.parquet
Facilitator Board	Monday.com	tl-monday	.parquet
Staffing Match	Monday.com	tl-monday	.parquet
Project Log	Monday.com	tl-monday	.parquet
Logistics Lookup	Monday.com	tl-monday	.parquet
Tracker	Monday.com	tl-monday	.parquet
Attendance	Google Sheets	Direct API	-
Partner Sites	Google Sheets	Direct API	-
Student Work Grades	Google Sheets	tl-surveys-26	.parquet

Bucket Naming Convention: - tl-surveys-26 → FY26 (July 2025 - June 2026) survey data - tl-surveys-25 → FY25 (July 2024 - June 2025) survey data - tl-surveys → Historical data (FY24 and earlier) - coaching-data-tl → Coaching operational data - tl-monday → Monday.com board exports

Roadmap

• Improve test coverage for core data functions
• Migrate remaining legacy scripts to posit_automations/
• Add validation checks for data quality

See open issues for more.

Contributing

1. Create a feature branch (git checkout -b feature/my-feature)
2. Commit your changes
3. Push and open a Pull Request

License

MIT License. See LICENSE for details.

Contact

Teaching Lab - contact@teachinglab.org

Technologies

• Qualtrics - Survey platform
• Monday.com - Project management and data tracking
• Posit Connect - Script scheduling and deployment
• pins - Data versioning and sharing
• targets - Pipeline orchestration