Add HOCOMOCO v14 as a motif database

Shaun Mahony · claude · Shaun Mahony · commit 03230aa59efa · 2026-03-01T01:26:55.000-05:00
Stream-parse the HOCOMOCO annotation JSONL to extract PCM matrices,
TF names, species, and TF classification. Supports both H14CORE (full)
and H14CORE-CLUSTERED (non-redundant) collections. Motifs are grouped
by species (Human/Mouse) and link to hocomoco14.autosome.org.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/web/src/app/admin/page.tsx b/web/src/app/admin/page.tsx
@@ -37,6 +37,11 @@ export default function AdminPage() {
   const [cisbpSyncing, setCisbpSyncing] = useState(false);
   const [cisbpResult, setCisbpResult] = useState<string | null>(null);
 
+  // HOCOMOCO state
+  const [hocomocoSyncing, setHocomocoSyncing] = useState(false);
+  const [hocomocoResult, setHocomocoResult] = useState<string | null>(null);
+  const [hocomocoCollection, setHocomocoCollection] = useState<string>("H14CORE");
+
   const fetchData = useCallback(async () => {
     const [jobsRes, dbsRes] = await Promise.all([
       fetch("/api/admin/jobs"),
@@ -86,6 +91,31 @@ export default function AdminPage() {
     }
   };
 
+  const handleHocomocoSync = async () => {
+    setHocomocoSyncing(true);
+    setHocomocoResult(null);
+    try {
+      const res = await fetch("/api/admin/sync-hocomoco", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ collection: hocomocoCollection }),
+      });
+      const data = await res.json();
+      if (res.ok) {
+        setHocomocoResult(
+          `Sync complete: ${data.result.totalStored} motifs stored from ${data.result.groups.length} groups, ${data.result.errors.length} errors`
+        );
+        fetchData();
+      } else {
+        setHocomocoResult(`Sync failed: ${data.error}`);
+      }
+    } catch (err) {
+      setHocomocoResult(`Sync failed: ${err instanceof Error ? err.message : String(err)}`);
+    } finally {
+      setHocomocoSyncing(false);
+    }
+  };
+
   const handleCisbpSync = async () => {
     setCisbpSyncing(true);
     setCisbpResult(null);
@@ -291,6 +321,48 @@ export default function AdminPage() {
             <p className="text-sm text-gray-600 mt-2">{cisbpResult}</p>
           )}
         </div>
+
+        {/* HOCOMOCO Sync Controls */}
+        <div className="border-t border-gray-200 pt-4 mt-4">
+          <h4 className="text-sm font-medium text-gray-900 mb-3">
+            Sync HOCOMOCO Database
+          </h4>
+          <p className="text-xs text-gray-500 mb-3">
+            Downloads motif data from{" "}
+            <a
+              href="https://hocomoco14.autosome.org/"
+              target="_blank"
+              rel="noopener noreferrer"
+              className="underline hover:text-gray-600"
+            >
+              HOCOMOCO v14
+            </a>
+            . Select a collection to sync:
+          </p>
+          <div className="flex flex-wrap gap-2 mb-4">
+            {(["H14CORE", "H14CORE-CLUSTERED"] as const).map((col) => (
+              <button
+                key={col}
+                className={`px-3 py-1 rounded-full text-xs font-medium transition-colors ${
+                  hocomocoCollection === col
+                    ? "bg-brand-100 text-brand-700 border border-brand-300"
+                    : "bg-gray-100 text-gray-600 border border-gray-200 hover:bg-gray-200"
+                }`}
+                onClick={() => setHocomocoCollection(col)}
+              >
+                {col === "H14CORE" ? "CORE (full, ~1595 motifs)" : "CLUSTERED (non-redundant, ~523 motifs)"}
+              </button>
+            ))}
+          </div>
+          <div className="flex items-center gap-3">
+            <Button onClick={handleHocomocoSync} disabled={hocomocoSyncing}>
+              {hocomocoSyncing ? "Syncing..." : "Sync HOCOMOCO"}
+            </Button>
+          </div>
+          {hocomocoResult && (
+            <p className="text-sm text-gray-600 mt-2">{hocomocoResult}</p>
+          )}
+        </div>
       </Card>
     </div>
   );
diff --git a/web/src/app/api/admin/sync-hocomoco/route.ts b/web/src/app/api/admin/sync-hocomoco/route.ts
@@ -0,0 +1,34 @@
+import { NextRequest, NextResponse } from "next/server";
+import { connectDB } from "@/lib/db/mongoose";
+import { syncHocomoco } from "@/lib/hocomoco/sync";
+
+function isAdmin(request: NextRequest): boolean {
+  return request.cookies.get("stamp-admin")?.value === "authenticated";
+}
+
+export async function POST(request: NextRequest) {
+  if (!isAdmin(request)) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  try {
+    await connectDB();
+
+    const body = await request.json().catch(() => ({}));
+    const collection = body.collection === "H14CORE-CLUSTERED"
+      ? "H14CORE-CLUSTERED" as const
+      : "H14CORE" as const;
+
+    const result = await syncHocomoco(collection);
+    return NextResponse.json({ success: true, result });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        error: `HOCOMOCO sync failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      },
+      { status: 500 }
+    );
+  }
+}
diff --git a/web/src/components/job/DatabaseSelector.tsx b/web/src/components/job/DatabaseSelector.tsx
@@ -55,9 +55,10 @@ export function DatabaseSelector({ value, onChange }: DatabaseSelectorProps) {
   );
 
   // Source display names and order
-  const sourceOrder = ["jaspar", "cisbp", "custom"];
+  const sourceOrder = ["jaspar", "hocomoco", "cisbp", "custom"];
   const sourceLabels: Record<string, string> = {
     jaspar: "JASPAR",
+    hocomoco: "HOCOMOCO",
     cisbp: "CIS-BP",
     custom: "Custom",
   };
diff --git a/web/src/lib/db/models/ReferenceDatabase.ts b/web/src/lib/db/models/ReferenceDatabase.ts
@@ -3,7 +3,7 @@ import mongoose, { Schema, Document } from "mongoose";
 export interface IReferenceDatabase extends Document {
   name: string;
   slug: string;
-  source: "jaspar" | "cisbp" | "custom";
+  source: "jaspar" | "cisbp" | "hocomoco" | "custom";
   description: string;
   jasparCollection: string | null;
   version: string | null;
@@ -21,7 +21,7 @@ const ReferenceDatabaseSchema = new Schema<IReferenceDatabase>(
   {
     name: { type: String, required: true },
     slug: { type: String, required: true, unique: true, index: true },
-    source: { type: String, required: true, enum: ["jaspar", "cisbp", "custom"] },
+    source: { type: String, required: true, enum: ["jaspar", "cisbp", "hocomoco", "custom"] },
     description: { type: String, default: "" },
     jasparCollection: { type: String, default: null },
     version: { type: String, default: null },
diff --git a/web/src/lib/hocomoco/parser.ts b/web/src/lib/hocomoco/parser.ts
@@ -0,0 +1,105 @@
+/**
+ * Parser for HOCOMOCO v14 annotation JSONL files.
+ *
+ * Each line in the annotation JSONL is a self-contained JSON object with all
+ * motif data: matrix values (PCM/PFM), TF name, species, TF classification,
+ * and quality rating.
+ */
+
+export interface HocomocoMotifRecord {
+  motifId: string;
+  tfName: string;
+  quality: string;
+  species: string; // "Human" or "Mouse"
+  tfClass: string | null;
+  family: string | null;
+  pfm: { A: number[]; C: number[]; G: number[]; T: number[] };
+}
+
+/**
+ * Parse a single line from an H14CORE or H14CORE-CLUSTERED annotation JSONL.
+ *
+ * Expected JSON fields per line:
+ *   name            – motif ID (e.g. "AHR.H14CORE.0.P.B")
+ *   tf              – TF gene symbol (e.g. "AHR")
+ *   quality         – "A" | "B" | "C" | "D"
+ *   pcm             – position count matrix  [[A,C,G,T], ...] (row-major)
+ *   pfm             – position frequency matrix [[A,C,G,T], ...] (row-major)
+ *   original_motif.species – "HUMAN" | "MOUSE"
+ *   masterlist_info.tfclass_class  – TF class description
+ *   masterlist_info.tfclass_family – TF family name
+ *
+ * Returns null if the line cannot be parsed or has no matrix data.
+ */
+export function parseAnnotationLine(line: string): HocomocoMotifRecord | null {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+
+  let obj: Record<string, unknown>;
+  try {
+    obj = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+
+  const motifId = obj.name as string | undefined;
+  const tfName = obj.tf as string | undefined;
+  if (!motifId || !tfName) return null;
+
+  // Get matrix data – prefer PCM (counts) over PFM (frequencies)
+  const pcm = obj.pcm as number[][] | undefined;
+  const pfmRaw = obj.pfm as number[][] | undefined;
+  const matrix = pcm || pfmRaw;
+  if (!matrix || matrix.length === 0) return null;
+
+  // Transpose from row-major [[A,C,G,T], ...] to column-major {A:[], C:[], G:[], T:[]}
+  const pfm = transposePcm(matrix);
+  if (!pfm) return null;
+
+  // Species: from original_motif.species
+  const originalMotif = obj.original_motif as Record<string, unknown> | undefined;
+  const rawSpecies = (originalMotif?.species as string) || "";
+  const species = normalizeSpecies(rawSpecies);
+
+  // TF classification
+  const masterlistInfo = obj.masterlist_info as Record<string, unknown> | undefined;
+  const tfClass = (masterlistInfo?.tfclass_class as string) || null;
+  const family = (masterlistInfo?.tfclass_family as string) || null;
+
+  const quality = (obj.quality as string) || "";
+
+  return { motifId, tfName, quality, species, tfClass, family, pfm };
+}
+
+/**
+ * Transpose a row-major matrix [[A,C,G,T], ...] (one row per position)
+ * to column-major { A: [...], C: [...], G: [...], T: [...] }.
+ */
+function transposePcm(
+  rows: number[][]
+): { A: number[]; C: number[]; G: number[]; T: number[] } | null {
+  if (rows.length === 0) return null;
+
+  const A: number[] = [];
+  const C: number[] = [];
+  const G: number[] = [];
+  const T: number[] = [];
+
+  for (const row of rows) {
+    if (row.length < 4) return null;
+    A.push(row[0]);
+    C.push(row[1]);
+    G.push(row[2]);
+    T.push(row[3]);
+  }
+
+  return { A, C, G, T };
+}
+
+function normalizeSpecies(raw: string): string {
+  const upper = raw.toUpperCase().trim();
+  if (upper === "HUMAN") return "Human";
+  if (upper === "MOUSE") return "Mouse";
+  if (upper) return raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+  return "Unknown";
+}
diff --git a/web/src/lib/hocomoco/sync.ts b/web/src/lib/hocomoco/sync.ts
