scitex 2.5.0__py3-none-any.whl → 2.7.3__py3-none-any.whl

scitex/plt/utils/_scientific_captions.py

@@ -31,12 +31,25 @@ class ScientificCaption:
     - Cross-references
     - Multiple formatting styles
     """
-    
+
     def __init__(self):
         self.figure_counter = 0
         self.caption_registry = {}
-        self.panel_letters = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L']
-    
+        self.panel_letters = [
+            "A",
+            "B",
+            "C",
+            "D",
+            "E",
+            "F",
+            "G",
+            "H",
+            "I",
+            "J",
+            "K",
+            "L",
+        ]
+
     def add_figure_caption(
         self,
         fig,
@@ -48,11 +61,11 @@ class ScientificCaption:
         font_size: Union[str, int] = "small",
         wrap_width: int = 80,
         save_to_file: bool = False,
-        file_path: str = None
+        file_path: str = None,
     ) -> str:
         """
         Add a scientific caption to a figure.
-        
+
         Parameters
         ----------
         fig : matplotlib.figure.Figure
@@ -75,7 +88,7 @@ class ScientificCaption:
             Whether to save caption to separate file, by default False
         file_path : str, optional
             Path for caption file, by default None
-            
+
         Returns
         -------
         str
@@ -85,27 +98,31 @@ class ScientificCaption:
         if figure_label is None:
             self.figure_counter += 1
             figure_label = f"Figure {self.figure_counter}"
-        
+
         # Format caption according to style
-        formatted_caption = self._format_caption(caption, figure_label, style, wrap_width)
-        
+        formatted_caption = self._format_caption(
+            caption, figure_label, style, wrap_width
+        )
+
         # Add caption to figure
-        self._add_caption_to_figure(fig, formatted_caption, position, width_ratio, font_size)
-        
+        self._add_caption_to_figure(
+            fig, formatted_caption, position, width_ratio, font_size
+        )
+
         # Register caption
         self.caption_registry[figure_label] = {
-            'text': caption,
-            'formatted': formatted_caption,
-            'style': style,
-            'figure': fig
+            "text": caption,
+            "formatted": formatted_caption,
+            "style": style,
+            "figure": fig,
         }
-        
+
         # Save to file if requested
         if save_to_file:
             self._save_caption_to_file(formatted_caption, figure_label, file_path)
-        
+
         return formatted_caption
-    
+
     def add_panel_captions(
         self,
         fig,
@@ -116,11 +133,11 @@ class ScientificCaption:
         panel_style: str = "letter_bold",
         position: str = "top_left",
         font_size: Union[str, int] = "medium",
-        offset: Tuple[float, float] = (0.02, 0.98)
+        offset: Tuple[float, float] = (0.02, 0.98),
     ) -> Dict[str, str]:
         """
         Add panel captions (A, B, C, etc.) to subplot panels.
-        
+
         Parameters
         ----------
         fig : matplotlib.figure.Figure
@@ -141,7 +158,7 @@ class ScientificCaption:
             Font size for panel labels, by default "medium"
         offset : Tuple[float, float], optional
             Position offset for panel labels, by default (0.02, 0.98)
-            
+
         Returns
         -------
         Dict[str, str]
@@ -149,41 +166,53 @@ class ScientificCaption:
         """
         # Ensure axes is a list
         if not isinstance(axes, (list, tuple)):
-            axes = [axes] if hasattr(axes, 'plot') else axes.flatten()
-        
+            axes = [axes] if hasattr(axes, "plot") else axes.flatten()
+
         # Handle different input formats for panel_captions
         if isinstance(panel_captions, list):
-            panel_dict = {self.panel_letters[i]: panel_captions[i] 
-                         for i in range(min(len(panel_captions), len(axes)))}
+            panel_dict = {
+                self.panel_letters[i]: panel_captions[i]
+                for i in range(min(len(panel_captions), len(axes)))
+            }
         else:
             panel_dict = panel_captions
-        
+
         # Add panel labels to axes
         formatted_panels = {}
         for i, ax in enumerate(axes):
             if i < len(self.panel_letters):
                 panel_letter = self.panel_letters[i]
                 if panel_letter in panel_dict:
-                    formatted_label = self._format_panel_label(panel_letter, panel_style)
+                    formatted_label = self._format_panel_label(
+                        panel_letter, panel_style
+                    )
                     panel_caption = panel_dict[panel_letter]
-                    
+
                     # Add label to axes
-                    self._add_panel_label_to_axes(ax, formatted_label, position, font_size, offset)
-                    
-                    formatted_panels[panel_letter] = f"{formatted_label} {panel_caption}"
-        
+                    self._add_panel_label_to_axes(
+                        ax, formatted_label, position, font_size, offset
+                    )
+
+                    formatted_panels[panel_letter] = (
+                        f"{formatted_label} {panel_caption}"
+                    )
+
         # Add main caption if provided
         if main_caption:
-            full_caption = self._combine_panel_and_main_captions(formatted_panels, main_caption)
+            full_caption = self._combine_panel_and_main_captions(
+                formatted_panels, main_caption
+            )
             self.add_figure_caption(fig, full_caption, figure_label)
-        
+
         return formatted_panels
-    
-    def _format_caption(self, caption: str, figure_label: str, style: str, wrap_width: int) -> str:
+
+    def _format_caption(
+        self, caption: str, figure_label: str, style: str, wrap_width: int
+    ) -> str:
         """Format caption according to specified style."""
         # Wrap text
         wrapped_text = textwrap.fill(caption, width=wrap_width)
-        
+
         if style == "scientific":
             return f"**{figure_label}.** {wrapped_text}"
         elif style == "nature":
@@ -194,7 +223,7 @@ class ScientificCaption:
             return f"*{figure_label}*\n{wrapped_text}"
         else:
             return f"{figure_label}. {wrapped_text}"
-    
+
     def _format_panel_label(self, letter: str, style: str) -> str:
         """Format panel label according to style."""
         if style == "letter_bold":
@@ -205,87 +234,115 @@ class ScientificCaption:
             return f"**{ord(letter) - ord('A') + 1}**"
         else:
             return f"**{letter}**"
-    
-    def _add_caption_to_figure(self, fig, caption: str, position: str, width_ratio: float, font_size: Union[str, int]):
+
+    def _add_caption_to_figure(
+        self,
+        fig,
+        caption: str,
+        position: str,
+        width_ratio: float,
+        font_size: Union[str, int],
+    ):
         """Add caption text to figure."""
         # Calculate position
         if position == "bottom":
             y_pos = 0.02
-            va = 'bottom'
+            va = "bottom"
         else:  # top
             y_pos = 0.98
-            va = 'top'
-        
+            va = "top"
+
         # Add caption text
         fig.text(
-            0.5, y_pos, caption,
-            ha='center', va=va,
+            0.5,
+            y_pos,
+            caption,
+            ha="center",
+            va=va,
             fontsize=font_size,
             wrap=True,
-            bbox=dict(boxstyle="round,pad=0.5", facecolor='white', alpha=0.8)
+            bbox=dict(boxstyle="round,pad=0.5", facecolor="white", alpha=0.8),
         )
-        
+
         # Adjust layout to accommodate caption
         if position == "bottom":
             fig.subplots_adjust(bottom=0.15)
         else:
             fig.subplots_adjust(top=0.85)
-    
-    def _add_panel_label_to_axes(self, ax, label: str, position: str, font_size: Union[str, int], offset: Tuple[float, float]):
+
+    def _add_panel_label_to_axes(
+        self,
+        ax,
+        label: str,
+        position: str,
+        font_size: Union[str, int],
+        offset: Tuple[float, float],
+    ):
         """Add panel label to individual axes."""
         # Position mapping
         positions = {
-            'top_left': (offset[0], offset[1]),
-            'top_right': (1 - offset[0], offset[1]),
-            'bottom_left': (offset[0], 1 - offset[1]),
-            'bottom_right': (1 - offset[0], 1 - offset[1])
+            "top_left": (offset[0], offset[1]),
+            "top_right": (1 - offset[0], offset[1]),
+            "bottom_left": (offset[0], 1 - offset[1]),
+            "bottom_right": (1 - offset[0], 1 - offset[1]),
         }
-        
+
         x_pos, y_pos = positions.get(position, (offset[0], offset[1]))
-        
+
         # Determine alignment
-        ha = 'left' if 'left' in position else 'right'
-        va = 'top' if 'top' in position else 'bottom'
-        
+        ha = "left" if "left" in position else "right"
+        va = "top" if "top" in position else "bottom"
+
         # Add label
         ax.text(
-            x_pos, y_pos, label,
+            x_pos,
+            y_pos,
+            label,
             transform=ax.transAxes,
             fontsize=font_size,
-            fontweight='bold',
-            ha=ha, va=va,
-            bbox=dict(boxstyle="round,pad=0.3", facecolor='white', alpha=0.9)
+            fontweight="bold",
+            ha=ha,
+            va=va,
+            bbox=dict(boxstyle="round,pad=0.3", facecolor="white", alpha=0.9),
         )
-    
-    def _combine_panel_and_main_captions(self, panel_dict: Dict[str, str], main_caption: str) -> str:
+
+    def _combine_panel_and_main_captions(
+        self, panel_dict: Dict[str, str], main_caption: str
+    ) -> str:
         """Combine panel captions with main caption."""
         panel_descriptions = []
         for letter in sorted(panel_dict.keys()):
-            panel_descriptions.append(f"({letter}) {panel_dict[letter].split(' ', 1)[1]}")  # Remove the bold letter
-        
+            panel_descriptions.append(
+                f"({letter}) {panel_dict[letter].split(' ', 1)[1]}"
+            )  # Remove the bold letter
+
         combined = main_caption
         if panel_descriptions:
             combined += " " + " ".join(panel_descriptions)
-        
+
         return combined
-    
-    def _save_caption_to_file(self, caption: str, figure_label: str, file_path: str = None):
+
+    def _save_caption_to_file(
+        self, caption: str, figure_label: str, file_path: str = None
+    ):
         """Save caption to a text file."""
         if file_path is None:
             file_path = f"{figure_label.lower().replace(' ', '_')}_caption.txt"
-        
-        with open(file_path, 'w', encoding='utf-8') as f:
+
+        with open(file_path, "w", encoding="utf-8") as f:
             f.write(caption)
-    
-    def export_all_captions(self, file_path: str = "figure_captions.txt", style: str = "scientific"):
+
+    def export_all_captions(
+        self, file_path: str = "figure_captions.txt", style: str = "scientific"
+    ):
         """Export all registered captions to a file."""
-        with open(file_path, 'w', encoding='utf-8') as f:
+        with open(file_path, "w", encoding="utf-8") as f:
             f.write("Figure Captions\n")
             f.write("=" * 50 + "\n\n")
-            
+
             for label, info in self.caption_registry.items():
                 f.write(f"{info['formatted']}\n\n")
-    
+
     def get_cross_reference(self, figure_label: str) -> str:
         """Get a cross-reference string for a figure."""
         if figure_label in self.caption_registry:
@@ -323,44 +380,44 @@ def cross_ref(figure_label: str) -> str:
 def save_with_caption(fig, filename: str, caption: str = None, **caption_kwargs):
     """
     Save figure with caption integration.
-    
+
     This function saves the figure and optionally creates caption files
     that can be used for manuscript preparation.
     """
     import scitex
-    
+
     # Save the figure normally
     scitex.io.save(fig, filename)
-    
+
     # Add caption if provided
     if caption:
         # Extract base filename
-        base_name = filename.split('.')[0]
-        
+        base_name = filename.split(".")[0]
+
         # Save in multiple formats (like CSV system)
         _save_caption_multiple_formats(caption, base_name, **caption_kwargs)
-        
+
         # Add caption to figure
         formatted_caption = add_figure_caption(fig, caption, **caption_kwargs)
-        
+
         return formatted_caption
-    
+
     return None
 
 
 def _save_caption_multiple_formats(
-    caption: str, 
-    base_filename: str, 
+    caption: str,
+    base_filename: str,
     figure_label: str = None,
     style: str = "scientific",
     save_txt: bool = True,
     save_tex: bool = True,
     save_md: bool = True,
-    wrap_width: int = 80
+    wrap_width: int = 80,
 ):
     """
     Save caption in multiple formats (like how scitex saves CSV data).
-    
+
     Parameters
     ----------
     caption : str
@@ -384,36 +441,38 @@ def _save_caption_multiple_formats(
     if figure_label is None:
         caption_manager.figure_counter += 1
         figure_label = f"Figure {caption_manager.figure_counter}"
-    
+
     # Create formatted versions
     txt_caption = _format_caption_for_txt(caption, figure_label, style, wrap_width)
     tex_caption = _format_caption_for_tex(caption, figure_label, style, wrap_width)
     md_caption = _format_caption_for_md(caption, figure_label, style, wrap_width)
-    
+
     # Save files (following scitex naming convention)
     if save_txt:
         txt_file = f"{base_filename}_caption.txt"
-        with open(txt_file, 'w', encoding='utf-8') as f:
+        with open(txt_file, "w", encoding="utf-8") as f:
             f.write(txt_caption)
         print(f"📝 Caption saved to: {txt_file}")
-    
+
     if save_tex:
         tex_file = f"{base_filename}_caption.tex"
-        with open(tex_file, 'w', encoding='utf-8') as f:
+        with open(tex_file, "w", encoding="utf-8") as f:
             f.write(tex_caption)
         print(f"📝 LaTeX caption saved to: {tex_file}")
-    
+
     if save_md:
         md_file = f"{base_filename}_caption.md"
-        with open(md_file, 'w', encoding='utf-8') as f:
+        with open(md_file, "w", encoding="utf-8") as f:
             f.write(md_caption)
         print(f"📝 Markdown caption saved to: {md_file}")
 
 
-def _format_caption_for_txt(caption: str, figure_label: str, style: str, wrap_width: int) -> str:
+def _format_caption_for_txt(
+    caption: str, figure_label: str, style: str, wrap_width: int
+) -> str:
     """Format caption for plain text file."""
     wrapped_text = textwrap.fill(caption, width=wrap_width)
-    
+
     if style == "scientific":
         return f"{figure_label}. {wrapped_text}"
     elif style == "nature":
@@ -426,19 +485,21 @@ def _format_caption_for_txt(caption: str, figure_label: str, style: str, wrap_wi
         return f"{figure_label}. {wrapped_text}"
 
 
-def _format_caption_for_tex(caption: str, figure_label: str, style: str, wrap_width: int) -> str:
+def _format_caption_for_tex(
+    caption: str, figure_label: str, style: str, wrap_width: int
+) -> str:
     """Format caption for LaTeX file."""
     # Escape special LaTeX characters
     tex_caption = _escape_latex(caption)
     wrapped_text = textwrap.fill(tex_caption, width=wrap_width)
-    
+
     if style == "scientific":
         latex_caption = f"""% {figure_label} caption
 \\begin{{figure}}[htbp]
     \\centering
     % \\includegraphics{{figure_filename}}
     \\caption{{\\textbf{{{figure_label}.}} {wrapped_text}}}
-    \\label{{fig:{figure_label.lower().replace(' ', '_')}}}
+    \\label{{fig:{figure_label.lower().replace(" ", "_")}}}
 \\end{{figure}}
 
 % For use in manuscript:
@@ -450,7 +511,7 @@ def _format_caption_for_tex(caption: str, figure_label: str, style: str, wrap_wi
     \\centering
     % \\includegraphics{{figure_filename}}
     \\caption{{\\textbf{{{figure_label} |}} {wrapped_text}}}
-    \\label{{fig:{figure_label.lower().replace(' ', '_')}}}
+    \\label{{fig:{figure_label.lower().replace(" ", "_")}}}
 \\end{{figure}}
 """
     else:
@@ -459,17 +520,19 @@ def _format_caption_for_tex(caption: str, figure_label: str, style: str, wrap_wi
     \\centering
     % \\includegraphics{{figure_filename}}
     \\caption{{{figure_label}. {wrapped_text}}}
-    \\label{{fig:{figure_label.lower().replace(' ', '_')}}}
+    \\label{{fig:{figure_label.lower().replace(" ", "_")}}}
 \\end{{figure}}
 """
-    
+
     return latex_caption
 
 
-def _format_caption_for_md(caption: str, figure_label: str, style: str, wrap_width: int) -> str:
+def _format_caption_for_md(
+    caption: str, figure_label: str, style: str, wrap_width: int
+) -> str:
     """Format caption for Markdown file."""
     wrapped_text = textwrap.fill(caption, width=wrap_width)
-    
+
     if style == "scientific":
         return f"""# {figure_label}
 
@@ -503,22 +566,22 @@ def _escape_latex(text: str) -> str:
     """Escape special LaTeX characters."""
     # Basic LaTeX character escaping
     escapes = {
-        '&': r'\&',
-        '%': r'\%',
-        '$': r'\$',
-        '#': r'\#',
-        '^': r'\textasciicircum{}',
-        '_': r'\_',
-        '{': r'\{',
-        '}': r'\}',
-        '~': r'\textasciitilde{}',
-        '\\': r'\textbackslash{}'
+        "&": r"\&",
+        "%": r"\%",
+        "$": r"\$",
+        "#": r"\#",
+        "^": r"\textasciicircum{}",
+        "_": r"\_",
+        "{": r"\{",
+        "}": r"\}",
+        "~": r"\textasciitilde{}",
+        "\\": r"\textbackslash{}",
     }
-    
+
     result = text
     for char, escape in escapes.items():
         result = result.replace(char, escape)
-    
+
     return result
 
 
@@ -526,26 +589,26 @@ def _escape_latex(text: str) -> str:
 def enhance_scitex_save_with_captions():
     """
     Enhance the scitex.io.save system to automatically handle captions.
-    
+
     This can be called to monkey-patch scitex.io.save to include caption support.
     """
     import scitex
-    
+
     # Store original save function
     original_save = scitex.io.save
-    
+
     def enhanced_save(obj, filename, caption=None, **kwargs):
         """Enhanced save function with caption support."""
         # Call original save
         result = original_save(obj, filename, **kwargs)
-        
+
         # Handle captions if provided
-        if caption is not None and hasattr(obj, 'savefig'):  # It's a figure
-            base_name = filename.split('.')[0]
+        if caption is not None and hasattr(obj, "savefig"):  # It's a figure
+            base_name = filename.split(".")[0]
             _save_caption_multiple_formats(caption, base_name)
-        
+
         return result
-    
+
     # Replace the save function
     scitex.io.save = enhanced_save
     print("📝 scitex.io.save enhanced with caption support!")
@@ -556,7 +619,7 @@ def enhance_scitex_save_with_captions():
 def create_figure_list(output_file: str = "figure_list.txt", format: str = "txt"):
     """
     Create a comprehensive list of all figures and their captions.
-    
+
     Parameters
     ----------
     output_file : str, optional
@@ -567,44 +630,44 @@ def create_figure_list(output_file: str = "figure_list.txt", format: str = "txt"
     if not caption_manager.caption_registry:
         print("No figures with captions found.")
         return
-    
+
     if format == "tex":
         _create_latex_figure_list(output_file)
     elif format == "md":
         _create_markdown_figure_list(output_file)
     else:
         _create_text_figure_list(output_file)
-    
+
     print(f"📋 Figure list saved to: {output_file}")
 
 
 def _create_text_figure_list(output_file: str):
     """Create plain text figure list."""
-    with open(output_file, 'w', encoding='utf-8') as f:
+    with open(output_file, "w", encoding="utf-8") as f:
         f.write("Figure List\n")
         f.write("=" * 50 + "\n\n")
-        
+
         for label, info in caption_manager.caption_registry.items():
             f.write(f"{info['formatted']}\n\n")
 
 
 def _create_latex_figure_list(output_file: str):
     """Create LaTeX figure list."""
-    with open(output_file, 'w', encoding='utf-8') as f:
+    with open(output_file, "w", encoding="utf-8") as f:
         f.write("% Figure List - Generated by scitex\n")
         f.write("\\section{List of Figures}\n\n")
-        
+
         for label, info in caption_manager.caption_registry.items():
-            escaped_caption = _escape_latex(info['text'])
+            escaped_caption = _escape_latex(info["text"])
             f.write(f"\\textbf{{{label}.}} {escaped_caption}\\\\\n\n")
 
 
 def _create_markdown_figure_list(output_file: str):
     """Create Markdown figure list."""
-    with open(output_file, 'w', encoding='utf-8') as f:
+    with open(output_file, "w", encoding="utf-8") as f:
         f.write("# Figure List\n\n")
         f.write("*Generated by scitex scientific caption system*\n\n")
-        
+
         for label, info in caption_manager.caption_registry.items():
             f.write(f"**{label}.** {info['text']}\n\n")
 
@@ -613,7 +676,7 @@ def _create_markdown_figure_list(output_file: str):
 def quick_caption(fig, caption: str, save_path: str = None, **kwargs):
     """
     Quick way to add caption and save all formats.
-    
+
     Parameters
     ----------
     fig : matplotlib.figure.Figure
@@ -627,12 +690,12 @@ def quick_caption(fig, caption: str, save_path: str = None, **kwargs):
     """
     if save_path is None:
         save_path = f"figure_{caption_manager.figure_counter + 1}"
-    
+
     # Save in all formats
     _save_caption_multiple_formats(caption, save_path, **kwargs)
-    
+
     # Add visual caption to figure
     return add_figure_caption(fig, caption, **kwargs)
 
 
-# EOF
+# EOF