lower level test class, improve doc, increase timeout

Author: Clare72

src/test/test_query_performance.py

@@ -352,14 +352,18 @@ def test_07_connectivity_queries(self):
         print(f"NeuronRegionConnectivityQuery: {duration:.4f}s {'✅' if success else '❌'}")
         self.assertLess(duration, self.THRESHOLD_SLOW, "NeuronRegionConnectivityQuery exceeded threshold")
 
-    # FBbt_00001482 = lineage NB3-2 primary interneuron — known to have
-    # downstream/upstream connectivity data in the vfb_json Solr core.
-    CLASS_CONNECTIVITY_TEST_CLASS = "FBbt_00001482"
+    # FBbt_00100234 = MBON01 — a specific mushroom body output neuron type
+    # with a small instance count (preferred over broad lineage classes for
+    # bounded test runtime). The class-level connectivity queries are a
+    # multi-step aggregation (Neo4j + batched Solr + ancestor walk), not a
+    # single Solr lookup, so cold-cache calls can take tens of seconds even
+    # on a small class.
+    CLASS_CONNECTIVITY_TEST_CLASS = "FBbt_00100234"
 
     def test_07b_downstream_class_connectivity(self):
-        """Test DownstreamClassConnectivity query (pre-indexed Solr)"""
+        """Test DownstreamClassConnectivity query (multi-step aggregation)"""
         print("\n" + "="*80)
-        print("DOWNSTREAM CLASS CONNECTIVITY (Solr pre-indexed)")
+        print("DOWNSTREAM CLASS CONNECTIVITY (multi-step aggregation)")
         print("="*80)
 
         result, duration, success = self._time_query(
@@ -369,12 +373,12 @@ def test_07b_downstream_class_connectivity(self):
             return_dataframe=False,
         )
         print(f"DownstreamClassConnectivity: {duration:.4f}s {'✅' if success else '❌'}")
-        self.assertLess(duration, self.THRESHOLD_MEDIUM, "DownstreamClassConnectivity exceeded threshold")
+        self.assertLess(duration, self.THRESHOLD_VERY_SLOW, "DownstreamClassConnectivity exceeded threshold")
 
     def test_07b_upstream_class_connectivity(self):
-        """Test UpstreamClassConnectivity query (pre-indexed Solr)"""
+        """Test UpstreamClassConnectivity query (multi-step aggregation)"""
         print("\n" + "="*80)
-        print("UPSTREAM CLASS CONNECTIVITY (Solr pre-indexed)")
+        print("UPSTREAM CLASS CONNECTIVITY (multi-step aggregation)")
         print("="*80)
 
         result, duration, success = self._time_query(
@@ -384,7 +388,7 @@ def test_07b_upstream_class_connectivity(self):
             return_dataframe=False,
         )
         print(f"UpstreamClassConnectivity: {duration:.4f}s {'✅' if success else '❌'}")
-        self.assertLess(duration, self.THRESHOLD_MEDIUM, "UpstreamClassConnectivity exceeded threshold")
+        self.assertLess(duration, self.THRESHOLD_VERY_SLOW, "UpstreamClassConnectivity exceeded threshold")
 
     def test_07c_cross_dataset_connectivity(self):
         """Test cross-dataset query_connectivity (live, both-end filtered)"""

src/vfbquery/vfb_queries.py

@@ -1521,7 +1521,20 @@ def DownstreamClassConnectivity_to_schema(name, take_default):
     Schema for downstream class connectivity query.
     Shows which neuron classes receive synapses from this neuron class.
     Matching criteria: Class + Neuron
-    Query chain: Solr downstream_connectivity_query field
+
+    Implementation: multi-step aggregation, not a single Solr lookup.
+      1. Neo4j: instances in the SUBCLASSOF closure of the queried class.
+      2. Solr cache (batched): per-instance synaptic partners.
+      3. Solr: direct partner classes from the downstream_connectivity_query
+         field (seed set for the partner-side ancestor walk).
+      4. Neo4j: walk SUBCLASSOF up from each direct partner to the neuron root.
+      5. Neo4j (batched): partner_instance -> {class_ids} membership map.
+      6. In-memory aggregation with set-union semantics to handle FBbt
+         multi-inheritance without double-counting.
+
+    Results are cached server-side (@with_solr_cache) per queried class, so
+    repeat calls return in milliseconds, but cold calls on broad classes can
+    take tens of seconds.
     """
     query = "DownstreamClassConnectivity"
     label = f"Downstream connectivity classes for {name}"
@@ -1540,7 +1553,11 @@ def UpstreamClassConnectivity_to_schema(name, take_default):
     Schema for upstream class connectivity query.
     Shows which neuron classes send synapses to this neuron class.
     Matching criteria: Class + Neuron
-    Query chain: Solr upstream_connectivity_query field
+
+    Implementation: same multi-step aggregation as
+    DownstreamClassConnectivity but with the upstream_connectivity_query
+    Solr field as the seed for the partner-side ancestor walk. See
+    DownstreamClassConnectivity_to_schema for the full pipeline.
     """
     query = "UpstreamClassConnectivity"
     label = f"Upstream connectivity classes for {name}"
@@ -3404,13 +3421,19 @@ def get_downstream_class_connectivity(short_form: str, return_dataframe=True, li
     """
     Retrieves downstream connectivity classes for the specified neuron class.
 
-    Uses OWLERY to expand subclasses of the queried class, fetches per-instance
+    Uses a Neo4j SUBCLASSOF traversal to enumerate instances of the queried
+    class (Owlery's get_instances was observed to hang for some classes;
+    Cypher is equivalent and fast here), bulk-fetches per-instance
     connectivity from the Solr cache, and aggregates by partner class with
     set-union semantics on partner instance memberships. The partner-side
-    hierarchy is walked up to ``NEURON_ROOT_SHORT_FORM`` so that connections to
-    a child class also count toward each ancestor class's row, without
+    hierarchy is walked up to ``NEURON_ROOT_SHORT_FORM`` so that connections
+    to a child class also count toward each ancestor class's row, without
     double-counting under FBbt multi-inheritance.
 
+    Server-side cached via ``@with_solr_cache``; cold calls on broad classes
+    can take tens of seconds because of the aggregation work (already batched
+    across Solr/Neo4j round-trips).
+
     Matching criteria: Class + Neuron
 
     :param short_form: short form of the neuron class
@@ -3454,12 +3477,15 @@ def get_upstream_class_connectivity(short_form: str, return_dataframe=True, limi
     """
     Retrieves upstream connectivity classes for the specified neuron class.
 
-    Uses OWLERY to expand subclasses of the queried class, fetches per-instance
-    connectivity from the Solr cache, and aggregates by partner class with
-    set-union semantics on partner instance memberships. The partner-side
-    hierarchy is walked up to ``NEURON_ROOT_SHORT_FORM`` so that connections
-    from a child class also count toward each ancestor class's row, without
-    double-counting under FBbt multi-inheritance.
+    Same multi-step aggregation as ``get_downstream_class_connectivity`` but
+    walking the upstream side: Neo4j SUBCLASSOF enumerates queried-class
+    instances, batched Solr cache fetches their synaptic partners, and the
+    partner-side hierarchy is walked up to ``NEURON_ROOT_SHORT_FORM`` with
+    set-union semantics to avoid double-counting under FBbt multi-inheritance.
+
+    Server-side cached via ``@with_solr_cache``; cold calls on broad classes
+    can take tens of seconds because of the aggregation work (already batched
+    across Solr/Neo4j round-trips).
 
     Matching criteria: Class + Neuron