Introduction

Analytics Middle Tier 2.0 is becoming a full citizen in the Ed-Fi platform in 2020, rather than just a proof-of-concept on the Ed-Fi Exchange. As it grows up, it needs to correct some architectural concerns that came up as feedback from the field. It also needs to be up to par with the latest release of the ODS/API, version 3.3. This document aims to inform about the challenges and elicit feedback on the real-world usefulness of the proposed solutions.

Naming Convention

Requirement

Hold names to under 63 characters for PostgreSQL compatibility.

Design

Currently, none of the objects have a name that violates this constraint. To help avoid problems with future views, it is proposed to either truncate "Dimension" to "Dim" or drop the word altogether. Generally, clarity should be preferred over length when naming objects, hence the question is: how much clarity is lost if we move away from the "Dimension" suffix?

Multi Data Standard Support

Requirement

Support installing the views on ODS databases supporting multiple data standards (2.2, 3.1, 3.2).

Design

Version 1.3.0 added support for Data Standard 3.1, which was used by ODS/API 3.1.1 and 3.2, through the use of the –dataStandard <Ds2 | Ds31>  argument. 

Forcing the user to remember which data standard is installed is sub-optimal. We should be able to detect this implicitly and install the correct version without user input.

1. If table AddressType exists, then install Data Standard 2.  if needed
2. Else if table VersionLevel exists, then install Data Standard 3.1.
3. Else if table DeployJournal exists, then install Data Standard 3.2.
4. Else throw an error: "Unable to determine the ODS database version".

Student, Parent, and Staff Keys

Requirement

The views should expose "Key" fields based on the natural key of the underlying table. 

Design

In the case of StudentDimension , ContactPersonDimension , and UserDimension , the original release used StudentUSI , ParentUSI , and StaffUSI  respectively. The "USI" columns are primary keys and were used by mistake. The "UniqueId" columns are the correct natural keys.

Change all instances of StudentKey , ContactPersonKey , and UserKey  to use the corresponding "UniqueId" column from the source table.

Descriptor and Type Mapping

Requirement

Decouple the views from hard-coded Descriptor and Type values. 

Context

many of the views need to lookup records by Descriptor value - for instance, looking up the Attendance records where a student has an "Excused Absence" or "Unexcused Absence." Because the original developer had access to only a limited dataset, it was not realized that the Descriptor values will vary widely from one implementation to the next. Thus the hard-coding needs to be decoupled, allowing the implementation to provide a mapping from their Descriptor value to the concept used by the Analytics Middle Tier.

In theory, the various "Types" values in Data Standard 2 should provide a more universal constant than the Descriptors. However, some community members report that these too are mutable. Therefore, (a) using Types is not a solution for Data Standard 2, and (b) even those views with hard-coding to Types instead of Descriptors must be modified for greater independence. Note: Type tables were removed in Data Standard 3 precisely because they were not being used in the originally-designed manner. 

Design

Summary

1. Move hard-coded values to a "Constants" table.
2. Create mapping tables that link Descriptors or Types to Constants.
3. Modify all views as needed to join to the Constants and new mapping tables.

Example

In Version 1.x, the StudentEarlyWarningFact view reports on excused and unexcused absences, looking for StudentSchoolAttendanceEvent  records with attendance descriptor values of either "Excused Absence" or "Unexcused Absence".

In version 2, the view would now search for all StudentSchoolAttendanceEvent records whose descriptor maps to the relevant constant. Thus there would be two DescriptorMap  values, one each for "Excused Absence" and "Unexcused Absence." Any school who uses a different term than these two would create a DescriptorMap  record mapping that term to the DescriptorConstant  value of "Absent".

Implications

Those who install the Analytics Middle Tier will need to carefully assess their Descriptors and Types, and then manage the DescriptorMap table (and TypeMap , for Data Standard 2) accordingly. 

Default Mappings

A new command-line Option will be provided to run a script that loads the default Descriptor mapping for the default Ed-Fi descriptors (minimal/populated template descriptors).

.\EdFi.AnalyticsMiddleTier.exe --connectionString "..." --options DefaultMap

Changes to the Student Dimension

Requirements

1. Create a "Student" dimension with a single unique key.
2. Provide intuitive access to student demographics.

Context

Student Dimension Uniqueness

The Early Warning System fact views both assumed that the StudentDimension  would only have a single record for a student, as shown in these diagrams:

However, a student could be enrolled in multiple schools at the same time, resulting in two records in the StudentDimension for the same StudentKey. This is problematic for the PowerBI Starter Kit, which has a hard requirement for unique StudentKeys.

Demographics in Ed-Fi UDM v3.x

Data Standard 3 moved the student demographics into the StudentEducationOrganizationAssociation  table, away from the Student table. Demographic information is thus closely aligned with school enrollment. Alternately, because this table is linked to Education Organizations instead of Schools, the demographics could be defined for the Local Education Agency instead of or in addition to being defined on the school enrollment.

The current StudentDimension  view provides student name, primary contact, and demographics, which looks intuitive but is misleading: if the student has multiple sets of records, then which do you choose? The Analytics Middle Tier will not be able to solve this problem. However, it should attempt to be clear about the problem so that the data analyst is not led down a false path.

Dimension or Fact?

While gender, race, and ethnicity all have strings associated with them, some elements of the demographic and enrollment data are more fact-oriented than dimension-oriented:

• IsHispanic
• IsEconomicallyDisadvantaged
• LimitedEnglishProficiency
• IsEligibleForSchoolFoodService
• SchoolEnrollmentDate

The ODS does not support slowly-changing dimensions, so there is only ever one current snapshot of these data - one cannot tie them to a date unless referring to the enrollment date.

Race is not included the the current views because it is not relevant in the Balfanz early warning system. It may be included in future use cases. Sex was provided out of convenience but could be removed (starter kits don't use it), or treated as a Key in a snowflake. In both cases, there is no universal binary definition that would become a Fact, without hard-coding "business logic" that should be decided by the use case or by the school/district.

Design Proposals

1. Shrink the Student Dimension 

Only the following columns truly belong on a StudentDimension  that has unique primary keys:

2a. Kick the Can Down the Road

The Early Warning System use case needs to know about a student's school enrollment - which is already provided via the StudentEarlyWarningFact  view. It does not need any demographic information. That information was included in version 1.0 to support ad hoc analytics without having a specific use case to anchor the structure of the data. Therefore we could simply remove all demographic data from 2.0. Re-introduce in 2.1 (or beyond) when there is a specific use case.

2b. Demographics Dimension for Ad Hoc Exploration

To support ad-hoc analytics exploration, continue supporting dimensional demographics data. Why dimension over fact?

• Fact views should generally be use case driven, and we don't have a clearly defined use case for demographics right now.
• A data analyst using a BI tool probably wants to slice data by demographics, which favors dimensional perspective over date-in-time fact or event perspective.
• When slicing or filtering by some bit of demographic data, a BI tool should automatically re-calculate aggregations / metrics. This is different than creating a report - this is about real-time exploration. For example, "how many fifth graders are at risk for dropout based on attendance, behavior, and course performance?" The analyst simply wants to filter on GradeLevel=Fifth. Then drill down to "ask" about limited English proficiency. In Power BI, this looks the image to the right. In this case, none of the fifth graders are recorded as having limited English proficiency, so the filter only shows "not applicable." Thus the ad hoc exploration just uncovered something interesting.
• That filter would not be so easy to achieve with a fact that is tied to a date, unless the data were provided for every single available date. Doing that would greatly increase the size of the analytics database without providing any additional value: since the ODS doesn't store past data, only current records, the demographic data would never change from one day to the next.

New View for Old Columns

Create a new StudentDemographics dimension that includes the following columns. 

Other Demographics

There are several other group categorizations that might be of interest:

• CohortYear
• Disability
• DisabilityDesignation
• Language / LanguageUse
• StudentCharacteristic
• Race
• TribalAffiliation

These are all represented with many-to-many relationships, making them difficult to model on the StudentDemographics  view. We have already used one: Student Characteristic of "Economic Disadvantaged" - so there is one model: add columns for a bunch of characteristics of interest, e.g. an IsHomeless  column or HasTribalAffiliation  column. Alternately, could combine values by concept, e.g. single "StudentCharacteristic" field that might have value of "Homeless, Refugee" to represent two records in the Edfi.StudentEducationOrganizationAssociationStudentCharacteristic . The latter would be more flexible from a modeling standpoint, but less useful from an analytics standpoint (i.e. you don't want to force users to query with language such as studentcharacteristic like "%homeless%" because that will lead to terrible performance.

Program Views

Requirement

Support analytics on Program Participation at the school level.

Context

A small set of Program-related views was added to Analytics Middle Tier as an experiment in supporting a second use-case: analyzing student program participation. Programs in the default Ed-Fi ODS template include "Bilingual", "Career and Technical Education", "Special Education", and a few others. These data are represented in two different fact views: analytics.StudentProgramEvent  and analytics.StudentProgramFact 

The "Event" view represents the date on which a student entered or exited a program. The "Fact" view represents every day on which the student was in a program. Each perspective has its own utility in analytics / reporting.

Note, however, that they both join to analytics.LocalEducationAgencyDimension . There is no linkage to schools. This is because the data modeler originally heard (or thought he heard) that program enrollment is "always" at the district level. Since then, he has received feedback that many implementations do link students to programs at the school level.

Design

a Remove the Views

Eliminate the problem by eliminating the views, unless and until we get a detailed real-world use case definition that would solve these problems.

b Add a SchoolKey to Both Views

This implies that SchoolKey  or LocalEducationAgencyKey  could be null, generally an undesirable situation in dimensional modeling. A few options:

1. Ignore the problem: downstream data analyst have to join the program views to SchoolDimension  or LocalEducationAgencyDimension  with an outer join.
   1.  Good for data architect.
   2.  Dangerous for data analyst.
      
      
2. Nulls can be eliminated - or at least nearly eliminated - for LocalEducationAgencyKey by loading a School's LocalEducationAgencyKey  value. 
   1.  Moderate additional complexity for data architecture.
   2.  Resolves one outer join problem but leaves the other in place.
      
      
3. Create a "fake school" for each LEA in the SchoolDimension , with SchoolName = 'n/a' . Use this as the SchoolKey  when program participation is only at the LEA level.
   1.  Ugly for the data architect, although not impossible.
   2.  Resolves the other outer join problem, at the expense of having a strange "District" entry show up in School filters. Dubious value.
      
      
4. Separate the views into copies for School and LocalEducationAgency.
   1.  Just forces the problem onto the data analyst.

The Data Standard  shows that a School can belong to 0 or 1 Local Education Agency. Side note: that Agency might be a Charter Management Organization. Thus option 2 can still lead to lost records when using an INNER JOIN. As with Option 3, null/missing records can be eliminated by creating a "n/a" LocalEducationAgency for these schools.

If these program views are to be kept, then a combination of options 2 and 3 seems like the only option that presents a useful interface to the data analyst.

School Year

Requirement

Add SchoolYear to help support longitudinal data.

Design

Data Standard 2's support for School Year is limited compared to Data Standard 3. The following dimension views could have a SchoolYear  column in them:

The DateDimension  view does not include a SchoolKey as it was intended as a generic date table. Although it strikes the writer as a nonsensical, there could be two different school years for the same date at different schools. Therefore it does not seem appropriate to add this column to the DateDimension. 

There might be value in having the SchoolYear  in the GradingPeriod  and making the decision that Data Standard 2 would always return null for this column (so that the interfaces stay consistent): one could use this to create a filter hierarchy School Year > Grading Period. However, other than interpolating the begin and end dates on the Grading Period, there is currently no way to build out the hierarchy beyond this. The PeriodSequence is insufficient for determining a parent-child relationship between grading periods.

When trying to filter the StudentEarlyWarningFact  or StudentSectionGradeFact views, the available school years could be extracted from either the Student or Student Section dimensions to create a slicer. However, this would be much simpler if the SchoolYear  were simply included in those fact views.

Separation Between Core and Use-Case Views

Requirement

Manage a collection of "core" views and separate collections of use-case specific views.

Design

The application already has a concept for installing optional components, which was first created for optional install of additional indexes in the ODS. Proposal:

1. Always install a core set of views
   1. ContactPersonDimension
   2. DateDimension
   3. GradingPeriodDimension
   4. LocalEducationAgencyDimension
   5. MostRecentGradingPeriod
   6. SchoolDimension
   7. SchoolNetworkAssociationDimension
   8. StudentDimension
   9. StudentEnrollmentDimension (if created, see above)
   10. StudentSectionDimension
       
       
2. Move some of the existing views into new optional collections:
   1. Row-level Security (RLS)
      1. StudentDataAuthorization
      2. UserAuthorization
      3. UserDimension
         
         
   2. Early Warning System (EWS)
      1. StudentEarlyWarningFact
      2. StudentSectionGradeFact
         
         
   3. QuickSight-Early Warning System (QEWS)
      1. Ews_SchoolRiskTrend
      2. Ews_StudentAttendanceTrend
      3. Ews_StudentEnrolledSectionGrade
      4. Ews_StudentEnrolledSectionGradeTrend
      5. Ews_StudentIndicators
      6. Ews_StudentIndicatorsByGradingPeriod
      7. Ews_UserSchoolAuthorization
         
         
   4. Program Analysis (PROGRAM)
      1. ProgramTypeDimension
      2. StudentProgramEvent

      3. StudentProgramFact
         
         

         Thus to install the Early Warning System and Row-level security collections used by the Power BI Starter Kit v2, the admin user would run this command:

         .\EdFi.AnalyticsMiddleTier.exe --connectionString "..." --options EWS RLS

3. Avoid name overlaps

   1. Option 1: separate by "namespace" (schema).  Instead of having a single analytics  schema, we could create an analytics_core  schema and other schemas to match use cases:
      

      v1 Name	v2 Name
      analytics.​ContactPersonDimension	analytics_core.​ContactPersonDimension
      analytics.DateDimension	analytics_core.DateDimension
      analytics.Ews_SchoolRiskTrend	analytics_qews.SchoolRiskTrend
      analytics.Ews_StudentAttendanceTrend	analytics_qews.StudentAttendanceTrend
      analytics.Ews_StudentEnrolledSectionGrade	analytics_qews.StudentEnrolledSectionGrade
      analytics.Ews_StudentEnrolledSectionGradeTrend	analytics_qews.StudentEnrolledSectionGradeTrend
      analytics.Ews_StudentIndicators	analytics_qews.StudentIndicators
      analytics.Ews_StudentIndicatorsByGradingPeriod	analytics_qews.StudentIndicatorsByGradingPeriod
      analytics.Ews_UserSchoolAuthorization	analytics_qews.UserSchoolAuthorization
      analytics.GradingPeriodDimension	analytics_core.GradingPeriodDimension
      analytics.LocalEducationAgencyDimension	analytics_core.LocalEducationAgencyDimension
      analytics.MostRecentGradingPeriod	analytics_core.MostRecentGradingPeriod
      analytics.ProgramTypeDimension	analytics_program.ProgramTypeDimension
      analytics.SchoolDimension	analytics_core.SchoolDimension
      analytics.SchoolNetworkAssociationDimension	analytics_core.SchoolNetworkAssociationDimension
      analytics.StudentDataAuthorization	analytics_rls.StudentDataAuthorization
      analytics.StudentDimension	analytics_core.StudentDimension
      analytics.StudentEarlyWarningFact	analytics_ews.StudentEarlyWarningFact
      analytics.StudentProgramEvent	analytics_program.StudentProgramEvent
      analytics.StudentProgramFact	analytics_program.StudentProgramFact
      analytics.StudentSectionDimension	analytics_core.StudentSectionDimension
      analytics.StudentSectionGradeFact	analytics_ews.StudentSectionGradeFact
      analytics.UserAuthorization	analytics_rls.UserAuthorization
      analytics.UserDimension	analytics_rls.UserDimension
      analytics.UserStudentDataAuthorization	analytics_rls.UserStudentDataAuthorization

   2. Option 2: keep everything in a single schema, ensuring unique names, so that downstream data models (without namespaces/schemas) do not need to name their models differently than the views. Put use case name as object name prefix.

      v1 Name	v2 Name
      analytics.​ContactPersonDimension	analytics.​ContactPersonDimension
      analytics.DateDimension	analytics.DateDimension
      analytics.Ews_SchoolRiskTrend	analytics.qews_SchoolRiskTrend
      analytics.Ews_StudentAttendanceTrend	analytics.qews_StudentAttendanceTrend
      analytics.Ews_StudentEnrolledSectionGrade	analytics.qews_StudentEnrolledSectionGrade
      analytics.Ews_StudentEnrolledSectionGradeTrend	analytics.qews_StudentEnrolledSectionGradeTrend
      analytics.Ews_StudentIndicators	analytics.qews_StudentIndicators
      analytics.Ews_StudentIndicatorsByGradingPeriod	analytics.qews_StudentIndicatorsByGradingPeriod
      analytics.Ews_UserSchoolAuthorization	analytics.qews_UserSchoolAuthorization
      analytics.GradingPeriodDimension	analytics.GradingPeriodDimension
      analytics.LocalEducationAgencyDimension	analytics.LocalEducationAgencyDimension
      analytics.MostRecentGradingPeriod	analytics.MostRecentGradingPeriod
      analytics.ProgramTypeDimension	analytics.program_ProgramTypeDimension
      analytics.SchoolDimension	analytics.SchoolDimension
      analytics.SchoolNetworkAssociationDimension	analytics.SchoolNetworkAssociationDimension
      analytics.StudentDataAuthorization	analytics.rls_StudentDataAuthorization
      analytics.StudentDimension	analytics.StudentDimension
      analytics.StudentEarlyWarningFact	analytics.ews_StudentEarlyWarningFact
      analytics.StudentProgramEvent	analytics.program_StudentProgramEvent
      analytics.StudentProgramFact	analytics.program_StudentProgramFact
      analytics.StudentSectionDimension	analytics.StudentSectionDimension
      analytics.StudentSectionGradeFact	analytics.ews_StudentSectionGradeFact
      analytics.UserAuthorization	analytics.ews_UserAuthorization
      analytics.UserDimension	analytics.ews_UserDimension
      analytics.UserStudentDataAuthorization	analytics.ews_.UserStudentDataAuthorization

   3. Option 3: keep everything in single schema and don't force prefixing for use cases. Just have clear and unique names for views. Prefix on case-by-case basis.
      
      

      Leaning toward option (b). Additional benefit: helps the reader know where to look up additional information about use-case specific views, such as important usage notes.

Additional Views

Will not add any new views in the 2.0 release. New views can be added with 2.1, 2.2 etc. This 2.0 release is all about fixing architectural problems and setting the stage for broader adoption.

End-User Documentation

Decisions made in defining the Ed-Fi data model are allowing a great deal of flexibility in storing data, at the expense of un-intuitive complexity. Users of the Analytics Middle Tier need to know about the complexities in order to use this tool effectively. For example, if adopting option (b) to solve the Program view problem, there needs to be clear guidance to help the end-user.

Users also need to be made aware of potential data quality issues, for example with the Student Demographics. If a student is enrolled in two schools at a time, and they don't both enter the same demographic information (e.g. one accidentally clicks on the wrong gender, or one does not mark student as Hispanic/Latino), then how will the data analyst know and reconcile this? The Ed-Fi Alliance cannot prescribe an answer: it depends on the implementation.

For the (rare?) case that the console deployment tool does not work, provide guidance on directly accessing the views from the source code repository. Warn that scripts, when manually executed, need to be run in numeric order of file name, starting with the Core collection first and then installing other collections as needed.

Other issues will likely arise, so that end-user documentation will be an ongoing exercise.

Contributors

Documentation for contributors to the project will need to spell out how to contribute; how to create use-cases; naming conventions; when and how to place a new view into the Core collection.