Add Datacard.segment_duration_distribution

audbcards/core/datacard.py

@@ -339,6 +339,82 @@ def save(self, file: str = None):
             with open(file, mode="w", encoding="utf-8") as fp:
                 fp.write(self.content)
 
+    @property
+    def segment_duration_distribution(self) -> str:
+        r"""Minimum and maximum of segment durations, and plotted distribution.
+
+        This generates a single line
+        containing the mininimum and maximum values
+        of segment durations.
+
+        If :attr:`audbcards.Datacard.sphinx_src_dir` is not ``None``
+        (e.g. when used in the sphinx extension),
+        an image is stored in the file
+        ``<dataset-name>-<dataset-version>-segment-duration-distribution.png``,
+        which is cached in
+        ``<cache-root>/<dataset-name>/<dataset-version>/``
+        and copied to the sphinx source folder
+        into
+        ``<sphinx-src-dir>/<path><dataset-name>/``.
+        The image is displayed inline
+        between the minimum and maximum values.
+        If all duration values are the same,
+        no distribution plot is created.
+
+        """
+        file_name = (
+            f"{self.dataset.name}-{self.dataset.version}"
+            "-segment-duration-distribution.png"
+        )
+        # Cache is organized as `<cache_root>/<name>/<version>/`
+        cache_file = audeer.path(
+            self.cache_root,
+            self.dataset.name,
+            self.dataset.version,
+            file_name,
+        )
+
+        min_ = 0
+        max_ = 0
+        unit = "s"
+        durations = self.dataset.segment_durations
+        if len(durations) > 0:
+            min_ = np.min(durations)
+            max_ = np.max(durations)
+
+        # Skip creating a distribution plot,
+        # if all durations are the same
+        if min_ == max_:
+            return f"each file is {max_:.1f} {unit}"
+
+        distribution_str = f"{min_:.1f} {unit} .. {max_:.1f} {unit}"
+
+        # Save distribution plot
+        if self.sphinx_src_dir is not None:
+            # Plot distribution to cache,
+            # if not found there already.
+            if not os.path.exists(cache_file):
+                audeer.mkdir(os.path.dirname(cache_file))
+                self._plot_distribution(durations)
+                plt.savefig(cache_file, transparent=True)
+                plt.close()
+
+            image_file = audeer.path(
+                self.sphinx_src_dir,
+                self.path,
+                self.dataset.name,
+                file_name,
+            )
+            audeer.mkdir(os.path.dirname(image_file))
+            shutil.copyfile(cache_file, image_file)
+            distribution_str = self._inline_image(
+                f"{min_:.1f} {unit}",
+                f"./{self.dataset.name}/{file_name}",
+                f"{max_:.1f} {unit}",
+            )
+
+        return distribution_str
+
     def _inline_image(
         self,
         text1: str,
@@ -442,6 +518,7 @@ def _expand_dataset(
                 player = self.player()
                 dataset["player"] = player
         dataset["file_duration_distribution"] = self.file_duration_distribution
+        dataset["segment_duration_distribution"] = self.segment_duration_distribution
         return dataset
 
     def _render_template(self) -> str:

audbcards/core/templates/datacard_header.j2

@@ -26,6 +26,9 @@ sampling rate {{ sampling_rates|join(', ') }}
 bit depth     {{ bit_depths|join(', ') }}
 duration      {{ duration }}
 files         {{ files }}, duration distribution: {{ file_duration_distribution }}
+{% if segments != "0" %}
+segments      {{ segments }}, duration distribution: {{ segment_duration_distribution }}
+{% endif %}
 repository    `{{ repository }} <{{ repository_link }}>`__
 published     {{ publication_date }} by {{ publication_owner }}
 ============= ======================

tests/test_data/rendered_templates/medium_db.rst

@@ -1,4 +1,5 @@
 .. |medium_db-1.0.0-file-duration-distribution| image:: ./medium_db/medium_db-1.0.0-file-duration-distribution.png
+.. |medium_db-1.0.0-segment-duration-distribution| image:: ./medium_db/medium_db-1.0.0-segment-duration-distribution.png
 
 .. _datasets-medium_db:
 
@@ -19,6 +20,7 @@ sampling rate 8000
 bit depth     16
 duration      0 days 00:05:02
 files         2, duration distribution: 1.0 s |medium_db-1.0.0-file-duration-distribution| 301.0 s
+segments      4, duration distribution: 0.5 s |medium_db-1.0.0-segment-duration-distribution| 151.0 s
 repository    `data-local <.../data-local/medium_db>`__
 published     2023-04-05 by author
 ============= ======================