ENH: Add optional rank parameter to Report.add_covariance

doc/changes/dev/13761.newfeature.rst

@@ -0,0 +1 @@
+Add optional ``rank`` parameter to ``Report.add_covariance`` to display covariance rank in reports by `Aasma Gupta`.

mne/report/report.py

@@ -1721,7 +1721,16 @@ def add_trans(
         )
 
     @fill_doc
-    def add_covariance(self, cov, *, info, title, tags=("covariance",), replace=False):
+    def add_covariance(
+        self,
+        cov,
+        *,
+        info,
+        title,
+        rank=None,
+        tags=("covariance",),
+        replace=False,
+    ):
         """Add covariance to the report.
 
         Parameters
@@ -1732,6 +1741,11 @@ def add_covariance(self, cov, *, info, title, tags=("covariance",), replace=Fals
             The `~mne.Info` corresponding to ``cov``.
         title : str
             The title corresponding to the `~mne.Covariance` object.
+        rank : int | None
+            The rank of the covariance matrix. If provided, it will be displayed
+            in the report above the covariance plots.
+
+            .. versionadded:: 1.12
         %(tags_report)s
         %(replace_report)s
 
@@ -1740,6 +1754,19 @@ def add_covariance(self, cov, *, info, title, tags=("covariance",), replace=Fals
         .. versionadded:: 0.24.0
         """
         tags = _check_tags(tags)
+
+        # Display rank if provided
+        if rank is not None:
+            html = f"<p><strong>Rank:</strong> {rank}</p>"
+            self._add_html_element(
+                html=html,
+                title="Covariance rank",
+                tags=tags,
+                section=title,
+                replace=replace,
+                div_klass="covariance",
+            )
+
         self._add_cov(
             cov=cov,
             info=info,

mne/report/tests/test_report.py

@@ -1360,3 +1360,21 @@ def test_gif(tmp_path):
     bad_name.write_bytes(b"")
     with pytest.raises(ValueError, match="Allowed values"):
         r.add_image(bad_name, "fname")
+
+
+def test_add_covariance_rank(tmp_path):
+    from mne import create_info
+    from mne.cov import make_ad_hoc_cov
+    from mne.report import Report
+
+    info = create_info(ch_names=["EEG 001"], sfreq=1000, ch_types=["eeg"])
+    cov = make_ad_hoc_cov(info)
+
+    report = Report()
+    report.add_covariance(cov, info=info, title="Test Cov", rank=1)
+
+    fname = tmp_path / "report.html"
+    report.save(fname, open_browser=False)
+
+    html = fname.read_text(encoding="utf-8")
+    assert "Rank" in html

tutorials/intro/70_report.py

@@ -164,7 +164,16 @@
 cov_path = sample_dir / "sample_audvis-cov.fif"
 
 report = mne.Report(title="Covariance example")
-report.add_covariance(cov=cov_path, info=raw_path, title="Covariance")
+
+# Optionally display the covariance rank in the report
+rank = 60
+
+report.add_covariance(
+    cov=cov_path,
+    info=raw_path,
+    title="Covariance",
+    rank=rank,
+)
 report.save("report_cov.html", overwrite=True)
 
 # %%