feat: ✨ add filtering by GE and additional aggregation operations

apps/api/v1/graphql/src/graphql/grades.graphql

@@ -91,6 +91,33 @@ type GradesOptions {
   "The list of instructors that matched the given filters."
   instructors: [String!]!
 }
+"An object that represents aggregate grades statistics for a course taught by an instructor."
+type AggregateGroupedGrade {
+  "The department code."
+  department: String!
+  "The course number the section belongs to."
+  courseNumber: String!
+  "The shortened name of the instructor who taught the section."
+  instructor: String!
+  "How many students attained an A+/A/A-."
+  gradeACount: Int!
+  "How many students attained a B+/B/B-."
+  gradeBCount: Int!
+  "How many students attained a C+/C/C-."
+  gradeCCount: Int!
+  "How many students attained a D+/D/D-."
+  gradeDCount: Int!
+  "How many students attained an F."
+  gradeFCount: Int!
+  "How many students attained a P."
+  gradePCount: Int!
+  "How many students attained an NP."
+  gradeNPCount: Int!
+  "How many students attained a W."
+  gradeWCount: Int!
+  "The average GPA of all assigned grades in the course."
+  averageGPA: Float!
+}
 
 extend type Query {
   "Get the raw grade info for the given parameters."
@@ -126,4 +153,15 @@ extend type Query {
     division: Division
     excludePNP: Boolean
   ): GradesOptions!
+  "Get the aggregate grade info, grouped by course and instructor, for the given parameters."
+  aggregateGroupedGrades(
+    year: String
+    quarter: Quarter
+    instructor: String
+    department: String
+    courseNumber: String
+    sectionCode: String
+    division: Division
+    excludePNP: Boolean
+  ): [AggregateGroupedGrade!]!
 }

apps/api/v1/graphql/src/resolvers.ts

@@ -15,6 +15,7 @@ export const resolvers: ApolloServerOptions<BaseContext>["resolvers"] = {
     rawGrades: proxyRestApi("v1/rest/grades/raw"),
     aggregateGrades: proxyRestApi("v1/rest/grades/aggregate"),
     gradesOptions: proxyRestApi("v1/rest/grades/options"),
+    aggregateGroupedGrades: proxyRestApi("v1/rest/grades/aggregateGrouped"),
     instructor: proxyRestApi("v1/rest/instructors", { pathArg: "courseId" }),
     instructors: proxyRestApi("v1/rest/instructors"),
     allInstructors: proxyRestApi("v1/rest/instructors/all"),

apps/api/v1/rest/grades/src/index.ts

@@ -1,10 +1,10 @@
 import { PrismaClient } from "@libs/db";
 import { createErrorResult, createOKResult, logger } from "ant-stack";
 import type { InternalHandler } from "ant-stack";
-import type { GradesOptions, GradesRaw } from "peterportal-api-next-types";
+import type { AggregateGroupedGrades, GradesOptions, RawGrades } from "peterportal-api-next-types";
 import { ZodError } from "zod";
 
-import { aggregateGrades, constructPrismaQuery, lexOrd } from "./lib";
+import { aggregateGrades, aggregateGroupedGrades, constructPrismaQuery, lexOrd } from "./lib";
 import { QuerySchema } from "./schema";
 
 let prisma: PrismaClient;
@@ -39,7 +39,7 @@ export const GET: InternalHandler = async (request) => {
           }));
           switch (params.id) {
             case "raw":
-              return createOKResult<GradesRaw>(res, headers, requestId);
+              return createOKResult<RawGrades>(res, headers, requestId);
             case "aggregate":
               return createOKResult(aggregateGrades(res), headers, requestId);
           }
@@ -97,6 +97,23 @@ export const GET: InternalHandler = async (request) => {
           requestId,
         );
       }
+      case "aggregateGrouped": {
+        return createOKResult<AggregateGroupedGrades>(
+          aggregateGroupedGrades(
+            (
+              await prisma.gradesSection.findMany({
+                where: constructPrismaQuery(parsedQuery),
+                include: { instructors: true },
+              })
+            ).map((section) => ({
+              ...section,
+              instructors: section.instructors.map((instructor) => instructor.name),
+            })),
+          ),
+          headers,
+          requestId,
+        );
+      }
     }
     return createErrorResult(
       400,

apps/api/v1/rest/grades/src/lib.ts

@@ -1,5 +1,11 @@
 import { Prisma } from "@libs/db";
-import type { GradeDistribution, GradesAggregate, GradesRaw } from "peterportal-api-next-types";
+import type {
+  AggregateGrades,
+  AggregateGroupedGradeHeader,
+  AggregateGroupedGrades,
+  GradeDistribution,
+  RawGrades,
+} from "peterportal-api-next-types";
 
 import { Query } from "./schema";
 
@@ -10,6 +16,8 @@ import { Query } from "./schema";
  */
 export const lexOrd = (a: string, b: string): number => (a === b ? 0 : a > b ? 1 : -1);
 
+const headerKeys = ["department", "courseNumber", "instructor"];
+
 const isNotPNPOnly = ({
   gradeACount,
   gradeBCount,
@@ -63,7 +71,7 @@ export function constructPrismaQuery(parsedQuery: Query): Prisma.GradesSectionWh
  * mean of each section's average GPA in the given dataset.
  * @param grades The array of grades to aggregate.
  */
-export function aggregateGrades(grades: GradesRaw): GradesAggregate {
+export function aggregateGrades(grades: RawGrades): AggregateGrades {
   return {
     sectionList: grades.map(
       ({ year, quarter, sectionCode, department, courseNumber, courseNumeric, instructors }) => ({
@@ -96,3 +104,38 @@ export function aggregateGrades(grades: GradesRaw): GradesAggregate {
     },
   };
 }
+
+/**
+ * Given an array of sections and their grades distributions, aggregate them into
+ * an array of objects, such that if two sections have the same department, course number,
+ * and instructor, they would be grouped together and aggregated into the same object by
+ * {@link `aggregateGrades`}.
+ * @param grades The array of grades to aggregate.
+ */
+export function aggregateGroupedGrades(grades: RawGrades): AggregateGroupedGrades {
+  const courses = new Map<string, RawGrades>();
+  for (const grade of grades) {
+    for (const instructor of grade.instructors) {
+      const { department, courseNumber } = grade;
+      const key = JSON.stringify([department, courseNumber, instructor]);
+      if (courses.has(key)) {
+        courses.get(key)?.push(grade);
+      } else {
+        courses.set(key, [grade]);
+      }
+    }
+  }
+  return Array.from(courses)
+    .map(([k, v]) => ({
+      ...(Object.fromEntries(
+        (JSON.parse(k) as string[]).map((x, i) => [headerKeys[i], x]),
+      ) as AggregateGroupedGradeHeader),
+      ...aggregateGrades(v).gradeDistribution,
+    }))
+    .sort(
+      (a, b) =>
+        lexOrd(a.department, b.department) ||
+        lexOrd(a.courseNumber, b.courseNumber) ||
+        lexOrd(a.instructor, b.instructor),
+    );
+}

apps/docs/docs/developers-guide/rest-api/reference/grades.md

@@ -269,3 +269,111 @@ type GradesOptions = {
 
 </TabItem>
 </Tabs>
+
+## Get grade statistics aggregated by course/instructor for certain sections
+
+Formally, if two sections have the same department code, course number, and instructor name, then they will be aggregated together for the purposes of this endpoint. For queries that involve an entire department, this is equivalent to running an aggregate query for each course number-instructor pair, but much faster.
+
+Note that graduate students who are listed as instructors on WebSoc may also be included.
+
+### Code sample
+
+<Tabs>
+<TabItem value="bash" label="cURL">
+
+```bash
+curl "https://api-next.peterportal.org/v1/rest/grades/aggregateGrouped?year=2023&department=COMPSCI&courseNumber=161"
+```
+
+</TabItem>
+</Tabs>
+
+### Response
+
+<Tabs>
+<TabItem value="json" label="Example response">
+
+```json
+[
+  {
+    "department": "COMPSCI",
+    "courseNumber": "161",
+    "instructor": "FRISHBERG, D.",
+    "gradeACount": 165,
+    "gradeBCount": 42,
+    "gradeCCount": 59,
+    "gradeDCount": 0,
+    "gradeFCount": 14,
+    "gradePCount": 0,
+    "gradeNPCount": 0,
+    "gradeWCount": 2,
+    "averageGPA": 3.23
+  },
+  {
+    "department": "COMPSCI",
+    "courseNumber": "161",
+    "instructor": "KALOGIANNIS, F.",
+    "gradeACount": 165,
+    "gradeBCount": 42,
+    "gradeCCount": 59,
+    "gradeDCount": 0,
+    "gradeFCount": 14,
+    "gradePCount": 0,
+    "gradeNPCount": 0,
+    "gradeWCount": 2,
+    "averageGPA": 3.23
+  },
+  {
+    "department": "COMPSCI",
+    "courseNumber": "161",
+    "instructor": "PANAGEAS, I.",
+    "gradeACount": 101,
+    "gradeBCount": 115,
+    "gradeCCount": 48,
+    "gradeDCount": 15,
+    "gradeFCount": 12,
+    "gradePCount": 0,
+    "gradeNPCount": 0,
+    "gradeWCount": 2,
+    "averageGPA": 2.935
+  },
+  {
+    "department": "COMPSCI",
+    "courseNumber": "161",
+    "instructor": "SHINDLER, M.",
+    "gradeACount": 165,
+    "gradeBCount": 42,
+    "gradeCCount": 59,
+    "gradeDCount": 0,
+    "gradeFCount": 14,
+    "gradePCount": 0,
+    "gradeNPCount": 0,
+    "gradeWCount": 2,
+    "averageGPA": 3.23
+  }
+]
+```
+
+</TabItem>
+<TabItem value="ts" label="Payload schema">
+
+```typescript
+// https://github.com/icssc/peterportal-api-next/blob/main/packages/peterportal-api-next-types/types/grades.ts
+type AggregateGroupedGrades = {
+  department: string;
+  courseNumber: string;
+  instructor: string;
+  gradeACount: number;
+  gradeBCount: number;
+  gradeCCount: number;
+  gradeDCount: number;
+  gradeFCount: number;
+  gradePCount: number;
+  gradeNPCount: number;
+  gradeWCount: number;
+  averageGPA: number;
+}[];
+```
+
+</TabItem>
+</Tabs>

packages/peterportal-api-next-types/types/grades.ts

@@ -3,7 +3,7 @@ import { Quarter } from "./constants";
 /**
  * A section which has grades data associated with it.
  */
-export type GradeSection = {
+export type GradesSection = {
   /**
    * The year the section was offered.
    */
@@ -76,22 +76,24 @@ export type GradeDistribution = {
   averageGPA: number;
 };
 
+export type RawGrade = GradesSection & GradeDistribution;
+
 /**
  * The type of the payload returned on a successful response from querying
  * ``/v1/rest/grades/raw``.
  */
-export type GradesRaw = (GradeSection & GradeDistribution)[];
+export type RawGrades = RawGrade[];
 
 /**
  * An object that represents aggregate grades statistics for a given query.
  * The type of the payload returned on a successful response from querying
  * ``/v1/rest/grades/aggregate``.
  */
-export type GradesAggregate = {
+export type AggregateGrades = {
   /**
    * The list of sections in the query.
    */
-  sectionList: GradeSection[];
+  sectionList: GradesSection[];
   /**
    * The combined grades distribution of all sections in the query.
    */
@@ -124,3 +126,13 @@ export type GradesOptions = {
    */
   instructors: string[];
 };
+
+export type AggregateGroupedGradeHeader = {
+  department: string;
+  courseNumber: string;
+  instructor: string;
+};
+
+export type AggregateGroupedGrade = AggregateGroupedGradeHeader & GradeDistribution;
+
+export type AggregateGroupedGrades = AggregateGroupedGrade[];

packages/websoc-fuzzy-search/src/helpers.ts

@@ -1,3 +1,5 @@
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore
 import { index } from "../output";
 
 import { types, fieldNames, courseFieldNames, instructorFieldNames } from "./constants";