Fit lifecycle charts to content and support transparent exports

Author: ahmedfgad

docs/source/releases.md

@@ -27,7 +27,7 @@ These changes are prepared on the `github-actions` branch. PyGAD 3.8.0 has not b
 11. [Scramble mutation](utils.md#scramble_mutation) shuffles the selected segment's values directly, removing the separate index shuffle and reversal. Every permutation of that segment is possible; its values, array dtype, and unselected genes are preserved. Seeded results can differ from earlier versions. See issue [#76](https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/76).
 12. New examples explain [replacing a loaded fitness function](pygad.md#updating-the-fitness-function-after-loading), starting fresh when the objective changes, and [handling short final fitness batches](fitness_calculation.md#why-a-fitness-batch-can-be-smaller). The lifecycle guide also explains [progress reporting](lifecycle.md#reporting-progress) and the order of fitness evaluation and callbacks. See issues [#263](https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/263), [#217](https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/217), and [#154](https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/154).
 13. [Rank selection](utils.md#rank_selection) assigns descending selection weights to the best-to-worst sorted solutions, correcting a bias that gave worse solutions higher selection probabilities. Regression tests verify exact probabilities, original population indices, negative fitness, objective vectors, crowding distance, ties, and parent copies. See issue [#120](https://github.com/ahmedfgad/GeneticAlgorithmPython/issues/120). Seeded rank-selection results can differ from earlier versions.
-14. A new [plot_lifecycle()](visualize.md#plot_lifecycle) method draws the lifecycle configured for a GA instance, including operators, callbacks, population replacement, generation loops, and stopping decisions. Stage annotations and a configuration panel show relevant settings, including gene types, batching, and offspring shapes. Use `show_parameters=False` for a compact view, `save_dir` to export SVG, PNG, or PDF, and `show=False` to create a chart without displaying it. The method works before or after `run()` without executing user functions or changing GA state. A new example is available at `examples/plots/example_plot_lifecycle.py`. The `pygad.visualize` submodule version is `1.2.1`.
+14. A new [plot_lifecycle()](visualize.md#plot_lifecycle) method draws the lifecycle configured for a GA instance, including operators, callbacks, population replacement, generation loops, and stopping decisions. Stage annotations and a configuration panel show relevant settings, including gene types, batching, and offspring shapes. Use `show_parameters=False` for a compact view, `save_dir` to export SVG, PNG, or PDF, and `show=False` to create a chart without displaying it. Use `transparent=True` for a transparent background. Charts fit their labels and connectors with small outer margins. The method works before or after `run()` without executing user functions or changing GA state. A new example is available at `examples/plots/example_plot_lifecycle.py`. The `pygad.visualize` submodule version is `1.2.1`.
 
 15. [Duplicate-gene repair](gene_values.md#prevent-duplicates-in-gene-values) now uses one shared implementation for generated and manual initial populations, crossover, mutation, and NSGA-III population growth. Custom crossover and mutation outputs and their callbacks are also repaired when `allow_duplicate_genes=False`. Finite domains are searched completely through replacement chains, including changes to earlier duplicate occurrences. Continuous candidates and additional searches for dependent constraints use `sample_size`.
 16. Repair uses each destination gene's type, precision, and [range](gene_values.md#more-about-the-gene_space-parameter), and validates [constraints](gene_values.md#gene-constraint) against complete candidate solutions. Mixed types are compared by their exact stored numeric values. Mixed types, `sample_size=1`, stepped spaces, per-gene ranges, and `None` entries are handled consistently. Impossible initialization spaces warn instead of accessing uninitialized attributes. Equal and reversed integer bounds are handled consistently. Swap fallback uses original continuous and `None` bounds instead of membership in cached samples. SBX and polynomial mutation convert and round generated values before repair and use their own bounds. The `pygad.helper` and `pygad.utils` submodule versions are `1.4.2` and `1.5.4`.

docs/source/visualize.md

@@ -44,10 +44,12 @@ Callbacks appear only when supplied. If `crossover_type=None` or `mutation_type=
 
 In the detailed view, the `Stop Early?` block lists the configured `stop_criteria` and, when an `on_generation` callback is supplied, the possible condition `on_generation() returns "stop"`. Any one of these conditions ends the run. The chart does not analyze the callback's code or assume that it will return `"stop"`. The block is omitted when neither early stopping mechanism is configured. Built-in block and configuration titles capitalize the first letter of each word; method and handler names retain their original spelling.
 
-Parameters: `title` (default `"PyGAD - Lifecycle"`), `font_size` (default `11`, finite and positive), `show_parameters` (default `True`), `save_dir` (default `None`), `show` (default `True`).
+Parameters: `title` (default `"PyGAD - Lifecycle"`), `font_size` (default `11`, finite and positive), `show_parameters` (default `True`), `save_dir` (default `None`), `show` (default `True`), `transparent` (default `False`).
 
 Use `show_parameters=False` for a compact chart that keeps handler names and control flow. Set `show=False` to create or save a chart without displaying it. The method always returns the figure, so it can be customized further.
 
+Charts fit their labels, cards, and connectors with small outer margins. Set `transparent=True` to remove the background for embedding in slides, videos, or web pages; the stage cards keep their fill colors.
+
 ```python
 # Save a detailed chart. The filename extension selects SVG, PNG, or PDF.
 fig = ga_instance.plot_lifecycle(title="PyGAD - Scheduling Optimization",

pygad/visualize/lifecycle.py

@@ -400,4 +400,19 @@ def wrap_text(text, width_inches, text_font_size, weight="normal"):
                       linespacing=1.2, parse_math=False)
             configuration_top += 0.20 * len(label_lines) + 0.17 * len(value_lines) + 0.17
 
+    # Axes with axis("off") still occupy their full canvas in a tight export.
+    # Fit the canvas to the actual labels, cards, and connectors instead.
+    from matplotlib.transforms import Bbox
+    fig.canvas.draw()
+    renderer = fig.canvas.get_renderer()
+    bounds = Bbox.union([artist.get_window_extent(renderer)
+                         for artist in list(axes.texts) + list(axes.patches)])
+    data_bounds = bounds.transformed(axes.transData.inverted())
+    margin = 0.08
+    left, right = data_bounds.xmin - margin, data_bounds.xmax + margin
+    top, bottom = data_bounds.ymin - margin, data_bounds.ymax + margin
+    axes.set_xlim(left, right)
+    axes.set_ylim(bottom, top)
+    fig.set_size_inches((right - left) * figure_scale,
+                        (bottom - top) * figure_scale)
     return fig

pygad/visualize/plot.py

@@ -31,7 +31,8 @@ def plot_lifecycle(self,
                        font_size=11,
                        show_parameters=True,
                        save_dir=None,
-                       show=True):
+                       show=True,
+                       transparent=False):
         """
         Draw the configured lifecycle, including active operators,
         callbacks, the generation loop, and stopping conditions.
@@ -58,6 +59,9 @@ def plot_lifecycle(self,
             If True, display the figure. Set to False when saving
             charts in scripts, notebooks, or reports without showing
             a window. The figure is returned in either case.
+        transparent : bool
+            If True, use a transparent figure background when displaying
+            or exporting the chart. Stage cards retain their fill colors.
 
         Returns
         -------
@@ -79,8 +83,8 @@ def plot_lifecycle(self,
             raise TypeError("The font_size parameter must be a positive number.")
         if not numpy.isfinite(font_size) or font_size <= 0:
             raise ValueError("The font_size parameter must be finite and greater than 0.")
-        if not isinstance(show_parameters, bool) or not isinstance(show, bool):
-            raise TypeError("The show_parameters and show parameters must be bool values.")
+        if not all(isinstance(value, bool) for value in (show_parameters, show, transparent)):
+            raise TypeError("The show_parameters, show, and transparent parameters must be bool values.")
 
         # Keep chart construction separate from rendering so its flow
         # can be checked without importing matplotlib or running a GA.
@@ -93,8 +97,13 @@ def plot_lifecycle(self,
                               "pip install pygad[visualize] (or pip install matplotlib).") from exc
 
         fig = _draw_lifecycle(lifecycle, matplt, title, font_size)
+        if transparent:
+            fig.patch.set_alpha(0)
+            for axes in fig.axes:
+                axes.patch.set_alpha(0)
         if save_dir is not None:
-            fig.savefig(fname=save_dir, bbox_inches="tight")
+            fig.savefig(fname=save_dir, bbox_inches="tight", pad_inches=0.02,
+                        transparent=transparent)
         if show:
             matplt.show()
         return fig

tests/test_plot_lifecycle.py

@@ -397,6 +397,44 @@ def test_lifecycle_export_and_display_control(tmp_path, monkeypatch, extension):
     matplt.close(fig)
 
 
+@pytest.mark.parametrize("show_parameters", [True, False])
+def test_lifecycle_transparent_export_has_small_outer_margins(tmp_path, show_parameters):
+    from PIL import Image
+
+    path = tmp_path / "transparent.png"
+    fig = create_ga_instance().plot_lifecycle(show_parameters=show_parameters,
+                                             transparent=True, save_dir=path, show=False)
+    try:
+        assert fig.patch.get_alpha() == 0
+        with Image.open(path) as image:
+            alpha = image.convert("RGBA").getchannel("A")
+            left, top, right, bottom = alpha.getbbox()
+            assert alpha.getextrema() == (0, 255)
+            # Default exports use 100 dpi; a content crop leaves about ten
+            # pixels of safety padding, rather than an unused axes canvas.
+            assert max(left, top, image.width-right, image.height-bottom) <= 15
+        fig.canvas.draw()
+        renderer = fig.canvas.get_renderer()
+        for text in fig.axes[0].texts:
+            bounds = text.get_window_extent(renderer)
+            assert fig.bbox.contains(*bounds.get_points()[0]), text.get_text()
+            assert fig.bbox.contains(*bounds.get_points()[1]), text.get_text()
+    finally:
+        matplt.close(fig)
+
+
+def test_lifecycle_default_export_keeps_opaque_background(tmp_path):
+    from PIL import Image
+
+    path = tmp_path / "opaque.png"
+    fig = create_ga_instance().plot_lifecycle(save_dir=path, show=False)
+    try:
+        with Image.open(path) as image:
+            assert image.convert("RGBA").getchannel("A").getextrema() == (255, 255)
+    finally:
+        matplt.close(fig)
+
+
 @pytest.mark.parametrize("parameters,error", [
     ({"title": None}, TypeError),
     ({"font_size": "large"}, TypeError),
@@ -407,6 +445,7 @@ def test_lifecycle_export_and_display_control(tmp_path, monkeypatch, extension):
     ({"font_size": numpy.inf}, ValueError),
     ({"show_parameters": "yes"}, TypeError),
     ({"show": None}, TypeError),
+    ({"transparent": "yes"}, TypeError),
 ])
 def test_lifecycle_parameter_validation(parameters, error):
     with pytest.raises(error):