[Feat] Explode dataframe columns with list values

- Add _explode_dataframe() to flatten metric columns into rows
- Fix metric error message formatting

Signed-off-by: ConvolutedDog <yangjianchao16@nudt.edu.cn>

Author: ConvolutedDog

examples/08_multiple_metrics.py

@@ -51,7 +51,7 @@ def main() -> None:
     df = results.to_dataframe()
     print(df)
 
-    unique_metrics = df["Metric"].unique()[0]
+    unique_metrics = df["Metric"].unique()
     print(f"\n✓ Collected {len(unique_metrics)} metrics:")
     for metric in unique_metrics:
         print(f"  - {metric}")

nsight/collection/core.py

@@ -13,6 +13,7 @@
 from collections.abc import Callable, Collection, Iterable, Sequence
 from typing import Any
 
+import numpy as np
 import pandas as pd
 
 from nsight import annotation, exceptions, thermovision, transformation, utils
@@ -435,6 +436,10 @@ def wrapper(
                     self.settings.output_progress,
                 )
 
+                # Explode the dataframe.
+                raw_df = self._explode_dataframe(raw_df)
+                processed = self._explode_dataframe(processed)
+
                 # Save to CSV if enabled
                 if self.settings.output_csv:
                     raw_csv_path = (
@@ -468,3 +473,42 @@ def wrapper(
             return None
 
         return wrapper
+
+    def _explode_dataframe(self, df: pd.DataFrame) -> pd.DataFrame:
+        """
+        Explode columns with list/tuple/np.ndarray values into multiple rows.
+
+        Two scenarios:
+            1. No derived metrics (all "Transformed" = False):
+                - All columns maybe contain multiple values (lists/arrays).
+                - Use `explode()` to flatten each list element into separate rows.
+            2. With derived metrics:
+                - Metric columns contain either:
+                    a) Single-element lists (from derived metrics) - extract the scalar
+                    b) Scalars (from original metrics) - keep as-is
+                - Only flatten single-element lists to scalars, don't create new rows.
+
+        Args:
+            df: Dataframe to be exploded.
+
+        Returns:
+            Exploded dataframe.
+        """
+        df_explode = None
+        if df["Transformed"].eq(False).all():
+            # 1: No derived metrics - explode all columns with sequences into rows.
+            df_explode = df.apply(pd.Series.explode).reset_index(drop=True)
+        else:
+            # 2: With derived metrics - only explode columns with single-value sequences.
+            df_explode = df.apply(
+                lambda col: (
+                    col.apply(
+                        lambda x: (
+                            x[0]
+                            if isinstance(x, (list, tuple, np.ndarray)) and len(x) == 1
+                            else x
+                        )
+                    )
+                )
+            )
+        return df_explode

nsight/collection/ncu.py

@@ -245,10 +245,6 @@ def collect(
             # If NSPY_NCU_PROFILE is set, just run the function normally
             name = os.environ["NSPY_NCU_PROFILE"]
 
-            # TODO: If we have two functions to profile in one script, we cannot access
-            # the result of the first function. Because when we profile the second function,
-            # the first function will return None.
-
             # If this is not the function we are profiling, stop
             if func.__name__ != name:
                 return None

nsight/exceptions.py

@@ -46,7 +46,7 @@ class NCUNotAvailableError(Exception):
 CUDA_CORE_UNAVAILABLE_MSG = "cuda-core is required for ignore_failures functionality.\n Install it with:\n  - pip install nsight-python[cu12]  (if you have CUDA 12.x)\n  - pip install nsight-python[cu13]  (if you have CUDA 13.x)"
 
 
-def get_metric_error_message(
+def get_metrics_error_message(
     metrics: Sequence[str], error_type: MetricErrorType
 ) -> str:
     """
@@ -60,7 +60,7 @@ def get_metric_error_message(
         str: User-friendly error message with guidance.
     """
     return (
-        f"{error_type.value} value '{metrics}' for 'metrics' parameter for nsight.analyze.kernel(). "
+        f"{error_type.value} value {metrics} for 'metrics' parameter for nsight.analyze.kernel()."
         f"\nPlease refer ncu --query-metrics for list of supported metrics."
     )
 

nsight/extraction.py

@@ -43,7 +43,7 @@ def extract_ncu_action_data(action: Any, metrics: Sequence[str]) -> utils.NCUAct
     """
     for metric in metrics:
         if metric not in action.metric_names():
-            error_message = exceptions.get_metric_error_message(
+            error_message = exceptions.get_metrics_error_message(
                 metric, error_type=exceptions.MetricErrorType.INVALID
             )
             raise exceptions.ProfilerException(error_message)
@@ -206,7 +206,6 @@ def extract_df_from_report(
             # evaluate the measured metrics
             values = data.values
             if derive_metrics is not None:
-                # TODO: Add support for multiple derived metrics.
                 derived_metrics: float | int | None = (
                     None if values is None else derive_metrics(*values, *conf)
                 )

nsight/transformation.py

@@ -224,17 +224,4 @@ def compute_group_geomean(valid_values: pd.Series) -> Any:
     # Add geomean values to the DataFrame
     agg_df["Geomean"] = agg_df["Annotation"].map(geomean_values)
 
-    # If the column has only one value, and it's a list/tuple/np.ndarray, flatten it.
-    agg_df = agg_df.apply(
-        lambda col: (
-            col.apply(
-                lambda x: (
-                    x[0]
-                    if isinstance(x, (list, tuple, np.ndarray)) and len(x) == 1
-                    else x
-                )
-            )
-        )
-    )
-
     return agg_df

nsight/utils.py

@@ -19,7 +19,7 @@
     CUDA_CORE_UNAVAILABLE_MSG,
     MetricErrorType,
     NCUErrorContext,
-    get_metric_error_message,
+    get_metrics_error_message,
 )
 
 # Try to import cuda-core (optional dependency)
@@ -321,7 +321,7 @@ def format_ncu_error_message(context: NCUErrorContext) -> str:
 
     if context.errors and INVALID_METRIC_ERROR_HINT in context.errors[0]:
         message_parts.append(
-            get_metric_error_message(
+            get_metrics_error_message(
                 context.metrics, error_type=MetricErrorType.INVALID
             )
         )

tests/test_profiler.py

@@ -6,9 +6,7 @@
 """
 
 import os
-import re
 import shutil
-import tempfile
 from collections.abc import Generator
 from typing import Any, Literal
 
@@ -953,8 +951,8 @@ def profiled_func(x: int, y: int) -> None:
     if metric == "invalid_value":
         with pytest.raises(
             exceptions.ProfilerException,
-            match=re.escape(
-                f"Invalid value '['{metric}']' for 'metric' parameter for nsight.analyze.kernel()"
+            match=(
+                rf"Invalid value \['{metric}'\] for 'metrics' parameter for nsight.analyze.kernel()"
             ),
         ):
             profiled_func()