scitex 2.1.3__py3-none-any.whl → 2.4.0__py3-none-any.whl

scitex/dsp/_ensure_3d.py

@@ -3,7 +3,7 @@
 # Time-stamp: "2024-11-05 01:03:47 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/dsp/_ensure_3d.py
 
-from ..decorators import signal_fn
+from scitex.decorators import signal_fn
 
 
 @signal_fn

scitex/dsp/_hilbert.py

@@ -10,9 +10,9 @@ This script does XYZ.
 import sys
 
 import matplotlib.pyplot as plt
-from ..nn._Hilbert import Hilbert
+from scitex.nn._Hilbert import Hilbert
 
-from ..decorators import signal_fn
+from scitex.decorators import signal_fn
 
 
 # Functions

scitex/dsp/_misc.py

@@ -7,7 +7,7 @@
 # -*- coding: utf-8 -*-
 # Time-stamp: "2024-04-05 12:14:08 (ywatanabe)"
 
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 @torch_fn

scitex/dsp/_modulation_index.py

@@ -5,8 +5,8 @@
 
 import torch
 
-from ..decorators import signal_fn
-from ..nn._ModulationIndex import ModulationIndex
+from scitex.decorators import signal_fn
+from scitex.nn._ModulationIndex import ModulationIndex
 
 
 @signal_fn

scitex/dsp/_pac.py

@@ -10,10 +10,10 @@ import sys
 import matplotlib.pyplot as plt
 import numpy as np
 import torch
-from ..str import printc
+from scitex.str import printc
 
-from ..decorators import signal_fn, batch_fn
-from ..nn._PAC import PAC
+from scitex.decorators import signal_fn, batch_fn
+from scitex.nn._PAC import PAC
 
 """
 scitex.dsp.pac function

scitex/dsp/_psd.py

@@ -7,8 +7,8 @@
 
 import torch
 
-from ..decorators import signal_fn
-from ..nn._PSD import PSD
+from scitex.decorators import signal_fn
+from scitex.nn._PSD import PSD
 
 
 @signal_fn

scitex/dsp/_resample.py

@@ -5,7 +5,7 @@
 
 import torch
 import torchaudio.transforms as T
-from ..decorators import signal_fn
+from scitex.decorators import signal_fn
 import scitex
 
 

scitex/dsp/_transform.py

@@ -8,7 +8,7 @@ import warnings
 import numpy as np
 import pandas as pd
 import torch
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 def to_sktime_df(arr):

scitex/dsp/_wavelet.py

@@ -6,8 +6,8 @@
 """scitex.dsp.wavelet function"""
 
 
-from ..decorators import batch_fn, signal_fn
-from ..nn._Wavelet import Wavelet
+from scitex.decorators import batch_fn, signal_fn
+from scitex.nn._Wavelet import Wavelet
 import scitex
 
 

scitex/dsp/add_noise.py

@@ -4,7 +4,7 @@
 # File: ./scitex_repo/src/scitex/dsp/add_noise.py
 
 import torch
-from ..decorators import signal_fn
+from scitex.decorators import signal_fn
 
 
 def _uniform(shape, amp=1.0):

scitex/dsp/filt.py

@@ -6,7 +6,7 @@
 import scitex
 import numpy as np
 
-from ..decorators import signal_fn
+from scitex.decorators import signal_fn
 
 # No top-level imports from nn module to avoid circular dependency
 # Filters will be imported inside functions when needed
@@ -14,14 +14,14 @@ from ..decorators import signal_fn
 
 @signal_fn
 def gauss(x, sigma, t=None):
-    from ..nn._Filters import GaussianFilter
+    from scitex.nn._Filters import GaussianFilter
     return GaussianFilter(sigma)(x, t=t)
 
 
 @signal_fn
 def bandpass(x, fs, bands, t=None):
     import torch
-    from ..nn._Filters import BandPassFilter
+    from scitex.nn._Filters import BandPassFilter
 
     # Convert bands to tensor if it's not already
     if not isinstance(bands, torch.Tensor):
@@ -31,19 +31,19 @@ def bandpass(x, fs, bands, t=None):
 
 @signal_fn
 def bandstop(x, fs, bands, t=None):
-    from ..nn._Filters import BandStopFilter
+    from scitex.nn._Filters import BandStopFilter
     return BandStopFilter(bands, fs, x.shape[-1])(x, t=t)
 
 
 @signal_fn
 def lowpass(x, fs, cutoffs_hz, t=None):
-    from ..nn._Filters import LowPassFilter
+    from scitex.nn._Filters import LowPassFilter
     return LowPassFilter(cutoffs_hz, fs, x.shape[-1])(x, t=t)
 
 
 @signal_fn
 def highpass(x, fs, cutoffs_hz, t=None):
-    from ..nn._Filters import HighPassFilter
+    from scitex.nn._Filters import HighPassFilter
     return HighPassFilter(cutoffs_hz, fs, x.shape[-1])(x, t=t)
 
 

scitex/dsp/norm.py

@@ -3,7 +3,7 @@
 # Time-stamp: "2024-04-05 12:15:42 (ywatanabe)"
 
 import torch as _torch
-from ..decorators import signal_fn as _signal_fn
+from scitex.decorators import signal_fn as _signal_fn
 
 
 @_signal_fn

scitex/dsp/reference.py

@@ -4,7 +4,7 @@
 # File: ./scitex_repo/src/scitex/dsp/reference.py
 
 import torch as _torch
-from ..decorators import torch_fn as _torch_fn
+from scitex.decorators import torch_fn as _torch_fn
 
 
 @_torch_fn

scitex/dsp/utils/_differential_bandpass_filters.py

@@ -12,9 +12,9 @@ import numpy as np
 import torch
 import torch.nn as nn
 
-from ...decorators import torch_fn
-from ...gen._to_even import to_even
-from ...gen._to_odd import to_odd
+from scitex.decorators import torch_fn
+from scitex.gen._to_even import to_even
+from scitex.gen._to_odd import to_odd
 
 try:
     from torchaudio.prototype.functional import sinc_impulse_response

scitex/dsp/utils/_ensure_3d.py

@@ -3,7 +3,7 @@
 # Time-stamp: "2024-11-05 01:04:03 (ywatanabe)"
 # File: ./scitex_repo/src/scitex/dsp/utils/_ensure_3d.py
 
-from ...decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 @torch_fn

scitex/dsp/utils/_zero_pad.py

@@ -8,7 +8,7 @@ THIS_FILE = "/home/ywatanabe/proj/scitex_repo/src/scitex/dsp/utils/_zero_pad.py"
 import numpy as np
 import torch
 import torch.nn.functional as F
-from ...decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 def _zero_pad_1d(x, target_length):

scitex/dsp/utils/filter.py

@@ -7,8 +7,8 @@ import matplotlib.pyplot as plt
 import numpy as np
 from scipy.signal import firwin, freqz
 
-from ...decorators import numpy_fn
-from ...gen._to_even import to_even
+from scitex.decorators import numpy_fn
+from scitex.gen._to_even import to_even
 
 
 @numpy_fn

scitex/dt/_normalize_timestamp.py

@@ -405,7 +405,7 @@ def run_main() -> None:
 
     args = parse_args()
 
-    CONFIG, sys.stdout, sys.stderr, plt, CC, rng = stx.session.start(
+    CONFIG, sys.stdout, sys.stderr, plt, CC, rng_manager = stx.session.start(
         sys,
         plt,
         args=args,

scitex/gen/_check_host.py

@@ -4,7 +4,7 @@
 # File: ./scitex_repo/src/scitex/gen/_check_host.py
 
 
-from .._sh import sh
+from scitex.sh import sh
 import sys
 
 

scitex/gen/_deprecated_close.py

@@ -16,7 +16,7 @@ This module provides backward compatibility by forwarding calls to the new
 scitex.session.close function while showing deprecation warnings.
 """
 
-from ..decorators._deprecated import deprecated
+from scitex.decorators._deprecated import deprecated
 
 
 @deprecated(
@@ -42,7 +42,7 @@ def close(*args, **kwargs):
         Same return value as scitex.session.close()
     """
     # Import here to avoid circular dependencies
-    from ..session import close as session_close
+    from scitex.session import close as session_close
 
     return session_close(*args, **kwargs)
 
@@ -70,7 +70,7 @@ def running2finished(*args, **kwargs):
         Same return value as scitex.session.running2finished()
     """
     # Import here to avoid circular dependencies
-    from ..session import running2finished as session_running2finished
+    from scitex.session import running2finished as session_running2finished
 
     return session_running2finished(*args, **kwargs)
 

scitex/gen/_deprecated_start.py

@@ -9,7 +9,7 @@ This module provides backward compatibility by forwarding calls to the new
 scitex.session.start function while showing deprecation warnings.
 """
 
-from ..decorators._deprecated import deprecated
+from scitex.decorators._deprecated import deprecated
 
 
 @deprecated(

scitex/gen/_norm.py

@@ -7,8 +7,8 @@ THIS_FILE = "/home/ywatanabe/proj/scitex_repo/src/scitex/gen/_norm.py"
 
 import torch
 
-from ..decorators import torch_fn
-from ..torch import nanstd
+from scitex.decorators import torch_fn
+from scitex.torch import nanstd
 
 
 @torch_fn

scitex/gen/_norm_cache.py

@@ -14,7 +14,7 @@ from functools import lru_cache
 from typing import Union, Tuple, Optional
 import hashlib
 
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 # Cache for normalized data

scitex/gen/_symlink.py

@@ -4,7 +4,7 @@
 # File: ./scitex_repo/src/scitex/gen/_symlink.py
 
 import os
-from ..str._color_text import color_text
+from scitex.str._color_text import color_text
 
 
 def symlink(tgt, src, force=False):

scitex/gen/_to_rank.py

@@ -10,7 +10,7 @@
 import torch
 
 # from .._converters import
-from ..decorators import torch_fn
+from scitex.decorators import torch_fn
 
 
 @torch_fn

scitex/gen/_transpose.py

@@ -3,7 +3,7 @@
 # Time-stamp: "2024-08-24 09:47:16 (ywatanabe)"
 # ./src/scitex/gen/_transpose.py
 
-from ..decorators import numpy_fn
+from scitex.decorators import numpy_fn
 import numpy as np
 
 

scitex/git/_branch.py

@@ -16,7 +16,7 @@ Examples
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 from ._validation import validate_branch_name, validate_path
@@ -76,7 +76,8 @@ def git_branch_rename(repo_path: Path, new_name: str, verbose: bool = True) -> b
             logger.error(f"Failed to rename branch in {repo_path}: {error_msg}")
             return False
 
-        logger.info(f"Branch renamed to {new_name}")
+        if verbose:
+            logger.info(f"Branch renamed to {new_name}")
         return True
 
 
@@ -132,7 +133,8 @@ def git_checkout_new_branch(repo_path: Path, branch_name: str, verbose: bool = T
             logger.error(f"Failed to create branch {branch_name} in {repo_path}: {error_msg}")
             return False
 
-        logger.info(f"Switched to new branch: {branch_name}")
+        if verbose:
+            logger.info(f"Switched to new branch: {branch_name}")
         return True
 
 

scitex/git/_clone.py

@@ -8,13 +8,13 @@ Git clone operations.
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 
 logger = getLogger(__name__)
 
 
-def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
+def clone_repo(url: str, target_path: Path, branch: str = None, tag: str = None, verbose: bool = True) -> bool:
     """
     Safely clone a git repository.
 
@@ -24,6 +24,12 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
         Git repository URL
     target_path : Path
         Destination path for cloning
+    branch : str, optional
+        Specific branch to clone. If None, clones the default branch.
+        Mutually exclusive with tag parameter.
+    tag : str, optional
+        Specific tag/release to clone. If None, clones the default branch.
+        Mutually exclusive with branch parameter.
     verbose : bool
         Enable verbose output
 
@@ -31,15 +37,34 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
     -------
     bool
         True if successful, False otherwise
+
+    Raises
+    ------
+    ValueError
+        If both branch and tag are specified
     """
     from ._remote import _validate_git_url
 
+    # Validate mutual exclusivity
+    if branch and tag:
+        raise ValueError("Cannot specify both 'branch' and 'tag' parameters. They are mutually exclusive.")
+
     if not _validate_git_url(url):
         logger.error(f"Invalid git URL: {url}")
         return False
 
+    cmd = ["git", "clone"]
+    ref_info = ""
+    if branch:
+        cmd.extend(["--branch", branch])
+        ref_info = f" (branch: {branch})"
+    elif tag:
+        cmd.extend(["--branch", tag])
+        ref_info = f" (tag: {tag})"
+    cmd.extend([url, str(target_path)])
+
     result = sh(
-        ["git", "clone", url, str(target_path)],
+        cmd,
         verbose=verbose,
         return_as="dict"
     )
@@ -48,7 +73,8 @@ def clone_repo(url: str, target_path: Path, verbose: bool = True) -> bool:
         logger.error(f"Failed to clone repository: {result['stderr']}")
         return False
 
-    logger.info("Repository cloned successfully")
+    if verbose:
+        logger.info(f"Repository cloned successfully{ref_info}")
     return True
 
 
@@ -85,7 +111,8 @@ def git_init(repo_path: Path, verbose: bool = True) -> bool:
             logger.warning(f"Failed to initialize git repository: {result['stderr']}")
             return False
 
-        logger.info("Git repository initialized")
+        if verbose:
+            logger.info("Git repository initialized")
         return True
 
 
@@ -94,7 +121,7 @@ def main(args):
         if not args.url:
             logger.error("URL required for clone action")
             return EXIT_FAILURE
-        success = clone_repo(args.url, args.path, args.verbose)
+        success = clone_repo(args.url, args.path, branch=args.branch, tag=args.tag, verbose=args.verbose)
         return EXIT_SUCCESS if success else EXIT_FAILURE
     elif args.action == "init":
         success = git_init(args.path, args.verbose)
@@ -108,6 +135,8 @@ def parse_args():
     parser.add_argument("--action", choices=["clone", "init"], required=True)
     parser.add_argument("--url", help="Repository URL for cloning")
     parser.add_argument("--path", type=Path, required=True)
+    parser.add_argument("--branch", help="Branch to clone (mutually exclusive with --tag)")
+    parser.add_argument("--tag", help="Tag/release to clone (mutually exclusive with --branch)")
     parser.add_argument("--verbose", action="store_true")
     return parser.parse_args()
 

scitex/git/_commit.py

@@ -17,7 +17,7 @@ Examples
 
 from pathlib import Path
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 from ._validation import validate_commit_message, validate_path
@@ -126,7 +126,8 @@ def git_commit(repo_path: Path, message: str, verbose: bool = True) -> bool:
             logger.error(f"Failed to commit in {repo_path}: {error_msg}")
             return False
 
-        logger.info("Commit created successfully")
+        if verbose:
+            logger.info("Commit created successfully")
         return True
 
 

scitex/git/_remote.py

@@ -9,7 +9,7 @@ Git remote operations.
 from pathlib import Path
 from typing import Optional
 from scitex.logging import getLogger
-from scitex._sh import sh
+from scitex.sh import sh
 from ._utils import _in_directory
 from ._constants import EXIT_SUCCESS, EXIT_FAILURE
 

scitex/git/_session.py

@@ -32,7 +32,7 @@ def run_with_session(parse_args_func, main_func):
 
     args = parse_args_func()
 
-    CONFIG, sys.stdout, sys.stderr, plt_obj, CC, rng = stx.session.start(
+    CONFIG, sys.stdout, sys.stderr, plt_obj, CC, rng_manager = stx.session.start(
         sys,
         plt,
         args=args,

scitex/git/_workflow.py

@@ -62,7 +62,7 @@ def _rollback_commit(repo_path: Path, verbose: bool = True) -> None:
     verbose : bool
         Enable verbose output
     """
-    from scitex._sh import sh
+    from scitex.sh import sh
     from ._utils import _in_directory
     from scitex.logging import getLogger
 

scitex/io/README.md

@@ -79,7 +79,7 @@ scitex.io.save(model.state_dict(), 'model.pth')
 
 # Save an image using PIL
 image = Image.new('RGB', (100, 100), color='red')
-scitex.io.save(image, 'image.jpg')
+scitex.io.save(image, 'image.png')  # Use PNG for lossless quality
 
 # Save a dictionary as a JSON file
 data = {'name': 'Alice', 'age': 30}
@@ -90,7 +90,71 @@ text = "Hello, World!"
 scitex.io.save(text, 'hello.txt')
 ```
 
+## ⚠️ File Format Best Practices for Scientific Figures
 
+### **NEVER use JPEG for scientific figures!**
+
+JPEG uses lossy compression that creates artifacts around text, lines, and sharp edges, making it unsuitable for scientific figures.
+
+#### Recommended Formats:
+
+1. **PNG (Portable Network Graphics)** ✅ BEST for raster figures
+   - **Lossless compression** - no quality loss
+   - Perfect for figures with text, lines, and solid colors
+   - Supports transparency
+   - Metadata preserved (scitex stores full metadata in PNG tEXt chunks)
+   - Auto-cropping preserves quality and DPI
+   ```python
+   scitex.io.save(fig, 'figure.png', dpi=300, auto_crop=True)
+   ```
+
+2. **PDF (Portable Document Format)** ✅ BEST for vector graphics
+   - **Vector format** - infinite zoom without quality loss
+   - Required by most scientific journals
+   - Smaller file size for line art
+   - Metadata preserved (scitex stores metadata in PDF Subject field)
+   ```python
+   scitex.io.save(fig, 'figure.pdf')
+   ```
+
+3. **JPEG (Joint Photographic Experts Group)** ❌ NEVER for scientific figures
+   - **Lossy compression** - creates visible artifacts
+   - Degrades quality around text and lines
+   - Not suitable for graphs, plots, or diagrams
+   - Only use for photographs
+
+#### Example - Publication-Ready Figure Saving:
+
+```python
+import scitex as stx
+
+# Create publication figure
+fig, ax = stx.plt.subplots(**stx.plt.presets.SCITEX_STYLE)
+ax.plot(x, y, label='Data')
+ax.set_xlabel('Time [s]')
+ax.set_ylabel('Amplitude [a.u.]')
+ax.legend()
+
+# Save in publication formats (PNG + PDF)
+stx.io.save(fig, 'figure1.png', dpi=300, auto_crop=True)  # Lossless raster
+stx.io.save(fig, 'figure1.pdf')                           # Vector format
+
+# DO NOT save as JPEG - it creates artifacts!
+# stx.io.save(fig, 'figure1.jpg')  # ❌ WRONG - lossy compression!
+```
+
+#### Auto-Cropping Feature:
+
+By default (`auto_crop=True`), figures are automatically cropped to content with 1mm margin:
+- Removes excess whitespace
+- Preserves image quality (PNG: lossless, PDF: vector)
+- Preserves DPI metadata (300 DPI for publication)
+- Preserves scitex metadata (version, style, dimensions, etc.)
+
+```python
+# Auto-crop is enabled by default
+stx.io.save(fig, 'figure.png')  # Automatically cropped, metadata preserved
+```
 
 <summary>Advanced Usage</summary>
 

scitex/io/__init__.py

@@ -69,6 +69,14 @@ except ImportError:
     migrate_h5_to_zarr = None
     migrate_h5_to_zarr_batch = None
 
+# Import metadata functions
+try:
+    from ._metadata import read_metadata, embed_metadata, has_metadata
+except ImportError:
+    read_metadata = None
+    embed_metadata = None
+    has_metadata = None
+
 __all__ = [
     "save",
     "load",
@@ -99,6 +107,10 @@ __all__ = [
     "get_cache_info",
     "configure_cache",
     "clear_load_cache",
+    # Metadata functions
+    "read_metadata",
+    "embed_metadata",
+    "has_metadata",
 ]
 
 # EOF

scitex/io/_glob.py

@@ -9,7 +9,7 @@ import re as _re
 from glob import glob as _glob
 from pathlib import Path
 from typing import Union
-from ..str._parse import parse as _parse
+from scitex.str._parse import parse as _parse
 from natsort import natsorted as _natsorted