plotastrodata 1.9.21__tar.gz → 1.10.0__tar.gz

{plotastrodata-1.9.21/plotastrodata.egg-info → plotastrodata-1.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotastrodata
-Version: 1.9.21
+Version: 1.10.0
 Summary: plotastrodata is a tool for astronomers to create figures from FITS files and perform fundamental data analyses with ease.
 Home-page: https://github.com/yusukeaso-astron/plotastrodata
 Download-URL: https://github.com/yusukeaso-astron/plotastrodata
@@ -14,12 +14,13 @@ License-File: LICENSE
 Requires-Dist: astropy>=7.2
 Requires-Dist: corner
 Requires-Dist: dynesty
-Requires-Dist: emcee>=3.0
+Requires-Dist: emcee>=3.1.5
 Requires-Dist: matplotlib
 Requires-Dist: numpy>=2.0
 Requires-Dist: pillow
 Requires-Dist: plotly
 Requires-Dist: ptemcee
+Requires-Dist: pydantic>=2
 Requires-Dist: scikit-image
 Requires-Dist: scipy
 Requires-Dist: tqdm
@@ -84,13 +85,14 @@ plotastrodata can do the following things.
 * astropy >= 7.2
 * corner (only for fitting)
 * dynesty (only for fitting)
-* emcee >= 3.0 (only for fitting)
+* emcee >= 3.1.5 (only for fitting)
 * ffmpeg (only for movie)
 * matplotlib
 * numpy >= 2.0
 * pillow (only for RGB figures)
 * plotly (only for html cube)
 * ptemcee (only for fitting)
+* pydantic >= 2
 * scikit-image (only for html cube)
 * scipy
 * tqdm (only for fitting)

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/README.md

@@ -56,13 +56,14 @@ plotastrodata can do the following things.
 * astropy >= 7.2
 * corner (only for fitting)
 * dynesty (only for fitting)
-* emcee >= 3.0 (only for fitting)
+* emcee >= 3.1.5 (only for fitting)
 * ffmpeg (only for movie)
 * matplotlib
 * numpy >= 2.0
 * pillow (only for RGB figures)
 * plotly (only for html cube)
 * ptemcee (only for fitting)
+* pydantic >= 2
 * scikit-image (only for html cube)
 * scipy
 * tqdm (only for fitting)

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/plotastrodata/__init__.py

@@ -1,4 +1,4 @@
 import warnings
 
 warnings.simplefilter('ignore', FutureWarning)
-__version__ = '1.9.21'
+__version__ = '1.10.0'

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/plotastrodata/analysis_utils.py

@@ -3,7 +3,8 @@ import warnings
 from dataclasses import dataclass
 from scipy.interpolate import RegularGridInterpolator as RGI
 from scipy.signal import convolve
-from typing import Any, Callable
+from pydantic.dataclasses import dataclass as pydantic_dataclass
+from typing import Any, Callable, Literal
 
 from plotastrodata import const_utils as cu
 from plotastrodata.coord_utils import coord2xy, rel2abs, xy2coord
@@ -621,7 +622,7 @@ ASTRODATA_ARGS = ['fitsimage', 'data', 'Tb', 'sigma', 'center', 'restfreq',
                   'beam_org', 'fitsheader', 'pv', 'pvpa']
 
 
-@dataclass
+@pydantic_dataclass
 class AstroFrame():
     """Parameter set to limit and reshape the data in the AstroData format.
 
@@ -662,7 +663,7 @@ class AstroFrame():
     yflip: bool = False
     swapxy: bool = False
     pv: bool = False
-    quadrants: str | None = None
+    quadrants: Literal['13', '24'] | None = None
 
     def __post_init__(self) -> None:
         self.xdir = -1 if self.xflip else 1

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/plotastrodata/plot_utils.py

@@ -1,9 +1,10 @@
 import matplotlib as mpl
 import matplotlib.pyplot as plt
 import numpy as np
-from dataclasses import dataclass
 from matplotlib.patches import Ellipse, Rectangle
-from typing import Any, TypeVar, Callable
+from pydantic import Field, field_validator
+from pydantic.dataclasses import dataclass as pydantic_dataclass
+from typing import Any, Callable, Literal, TypeVar
 
 from plotastrodata.analysis_utils import AstroData, AstroFrame
 from plotastrodata.coord_utils import (coord2xy, xy2coord,
@@ -17,6 +18,13 @@ from plotastrodata.other_utils import (close_figure, listing,
 plt.ioff()  # force to turn off interactive mode
 
 T = TypeVar('T')
+Stretch = Literal['linear', 'log', 'asinh', 'power']
+AxisScale = Literal['linear', 'log', 'symlog', 'asinh', 'logit']
+FloatOrList = float | list[float]
+OptionalFloatOrList = float | list[float | None] | None
+BeamTriple = list[float | None]
+BeamValue = BeamTriple | list[BeamTriple]
+BeamPosition = list[float] | list[list[float] | None] | None
 
 
 def set_rcparams(fontsize: int = 18, nancolor: str = 'w',
@@ -187,24 +195,24 @@ def _get_vskipfill(nv: int, v_org: np.ndarray, vskip: int,
     return vskipfill
 
 
-@dataclass
+@pydantic_dataclass
 class Stretcher():
     """Arguments and methods related to the stretch in PlotAstroData.add_color() and add_rgb().
 
         Args:
             stretch (str, optional): 'log', 'asinh', 'power', or 'linear'. Any other means 'linear'. 'log' means the mapped data are logarithmic. 'asinh' means the mapped data are arc sin hyperbolic. 'power' means the mapped data are power-law (see also stretchpower). Defaults to 'linear'.
-            stretchscale (float, optional): The output is asinh(data / stretchscale). Defaults to None.
-            stretchpower (float, optional): The output is data**stretchpower / stretchpower. 1 means the linear scale, while 0 means the logarithmic scale. Defaults to 0.5.
-            vmin (float, optional): The minimum value for Axes.pcolormesh() of matplotlib. Defaults to None.
-            vmax (float, optional): The maximum value for Axes.pcolormesh() of matplotlib. Defaults to None.
-            sigma (float, optional): Noise level. Defaults to 0.
+            stretchscale (float or list, optional): The output is asinh(data / stretchscale). Defaults to None.
+            stretchpower (float or list, optional): The output is data**stretchpower / stretchpower. 1 means the linear scale, while 0 means the logarithmic scale. Defaults to 0.5.
+            vmin (float or list, optional): The minimum value for Axes.pcolormesh() of matplotlib. Defaults to None.
+            vmax (float or list, optional): The maximum value for Axes.pcolormesh() of matplotlib. Defaults to None.
+            sigma (float, list, or None, optional): Noise level. None means no noise level is used. Defaults to 0.
     """
-    stretch: str = 'linear'
-    stretchscale: float | None = None
-    stretchpower: float = 0.5
-    vmin: float | None = None
-    vmax: float | None = None
-    sigma: float = 0
+    stretch: Stretch | list[Stretch] = 'linear'
+    stretchscale: OptionalFloatOrList = None
+    stretchpower: FloatOrList = 0.5
+    vmin: OptionalFloatOrList = None
+    vmax: OptionalFloatOrList = None
+    sigma: OptionalFloatOrList = 0
 
     def __post_init__(self) -> None:
         self.n = 1 if isinstance(self.stretch, str) else len(self.stretch)
@@ -301,27 +309,88 @@ class Stretcher():
         return dataout, vminout, vmaxout
 
 
+@pydantic_dataclass
 class Beam():
     """Arguments for PlotAstroData.add_beam().
 
         Args:
             show_beam (bool, optional): Defaults to True.
-            beam (list, optional): [bmaj, bmin, bpa]. This may be a list of list. Defaults to [None, None, None].
-            beamcolor (str, optional): matplotlib color. This may be a list of str. Defaults to 'gray'.
-            beampos (list, optional): Relative position. This may be a list of list or a list of None. Defaults to None.
-            beam_kwargs (dict, optional): Additional arguments for matplotlib.patches. Defaults to {}.
+            beam (list or np.ndarray, optional): One ``[bmaj, bmin, bpa]`` triple or a list of triples. ``bmaj`` and ``bmin`` must be positive; ``bpa`` is in degrees. ``[None, None, None]`` means no beam is available. Partial triples are not supported. Defaults to ``[None, None, None]``.
+            beamcolor (str or list of str, optional): Matplotlib color. One color is used for every beam; when a list is given, provide one color per beam. Defaults to ``'gray'``.
+            beampos (list or list of list, optional): One relative ``[x, y]`` position is used for every beam; when a list of positions is given, provide one position per beam. Each coordinate must be from 0 (left or bottom) to 1 (right or top). None selects the automatic position. Defaults to None.
+            beam_kwargs (dict, optional): Additional Matplotlib patch arguments. Defaults to {}.
     """
-    def __init__(self,
-                 show_beam: bool = True,
-                 beam: list[float | None] = [None] * 3,
-                 beamcolor: str = 'gray',
-                 beampos: list[float] | None = None,
-                 beam_kwargs: dict = {}) -> None:
-        self.show_beam = show_beam
-        self.beam = beam
-        self.beamcolor = beamcolor
-        self.beampos = beampos
-        self.beam_kwargs = beam_kwargs
+    show_beam: bool = True
+    beam: BeamValue = Field(default_factory=lambda: [None] * 3)
+    beamcolor: str | list[str] = 'gray'
+    beampos: BeamPosition = None
+    beam_kwargs: dict[str, Any] = Field(default_factory=dict)
+
+    @field_validator('beam', mode='before')
+    @classmethod
+    def _convert_beam_arrays(cls, value: Any) -> Any:
+        """Convert documented NumPy beam inputs to the canonical list form.
+
+        A single NumPy triple becomes a list, and NumPy triples inside a
+        list of beams are converted individually. This keeps subsequent
+        validation and plotting code independent of the input container.
+        """
+        if isinstance(value, np.ndarray):
+            value = value.tolist()
+        if isinstance(value, list):
+            return [item.tolist() if isinstance(item, np.ndarray) else item
+                    for item in value]
+        return value
+
+    @field_validator('beam')
+    @classmethod
+    def _validate_beam(cls, value: BeamValue) -> BeamValue:
+        beams = value if value and isinstance(value[0], list) else [value]
+        for beam in beams:
+            if len(beam) != 3:
+                raise ValueError('Each beam must contain [bmaj, bmin, bpa].')
+            if all(component is None for component in beam):
+                continue
+            if any(component is None for component in beam):
+                raise ValueError('A beam must be complete or all None.')
+            if not all(np.isfinite(component) for component in beam):
+                raise ValueError('Beam values must be finite.')
+            if beam[0] <= 0 or beam[1] <= 0:
+                raise ValueError('bmaj and bmin must be positive.')
+        return value
+
+    @field_validator('beampos')
+    @classmethod
+    def _validate_beampos(cls, value: BeamPosition) -> BeamPosition:
+        if value is None:
+            return value
+        positions = [value] if cls._is_position(value) else value
+        for position in positions:
+            if position is None:
+                continue
+            if len(position) != 2:
+                raise ValueError('Each beam position must contain [x, y].')
+            if not all(0 <= coordinate <= 1 for coordinate in position):
+                raise ValueError('Beam positions must be between 0 and 1.')
+        return value
+
+    @staticmethod
+    def _is_position(value: Any) -> bool:
+        return (isinstance(value, list) and len(value) == 2
+                and all(isinstance(coordinate, float)
+                        for coordinate in value))
+
+    def validate_display(self) -> None:
+        """Validate color and position lists against the number of beams."""
+        multi = self.beam and isinstance(self.beam[0], list)
+        beams = self.beam if multi else [self.beam]
+        nbeams = len(beams)
+        if isinstance(self.beamcolor, list) and len(self.beamcolor) != nbeams:
+            raise ValueError('Provide one beamcolor for each beam.')
+        if (self.beampos is not None
+                and not self._is_position(self.beampos)
+                and len(self.beampos) != nbeams):
+            raise ValueError('Provide one beampos for each beam.')
 
     def todict(self) -> dict[str, Any]:
         """Return beam display settings as a dictionary.
@@ -337,13 +406,13 @@ class Beam():
         return tmp
 
 
-@dataclass
+@pydantic_dataclass
 class PlotAxes2D():
     """Use Axes.set_* to adjust x and y axes.
 
     Args:
         samexy (bool, optional): True supports same ticks between x and y. Defaults to True.
-        loglog (float, optional): If a float is given, plot on a log-log plane, and xim=(xmax / loglog, xmax) and so does ylim. Defaults to None.
+        loglog (float, optional): A positive value plots on a log-log plane, with xim=(xmax / loglog, xmax) and similarly for ylim. Defaults to None.
         xscale (str, optional): ``'log'`` labels decade ticks and ticks near the limits; other intermediate ticks are minor and unlabeled. Defaults to ``'linear'``.
         yscale (str, optional): ``'log'`` labels decade ticks and ticks near the limits; other intermediate ticks are minor and unlabeled. Defaults to ``'linear'``.
         xlim (list, optional): Defaults to None.
@@ -360,9 +429,9 @@ class PlotAxes2D():
         aspect (dict or float, optional): Defaults to None.
     """
     samexy: bool = True
-    loglog: float | None = None
-    xscale: str = 'linear'
-    yscale: str = 'linear'
+    loglog: float | None = Field(default=None, gt=0)
+    xscale: AxisScale = 'linear'
+    yscale: AxisScale = 'linear'
     xlim: list | None = None
     ylim: list | None = None
     xlabel: str | None = None
@@ -618,9 +687,12 @@ class PlotAstroData(AstroFrame):
         self.sigma = d.sigma
         singlepix = d.dx is None or d.dy is None
         if len(d.beam) == 4:
-            b.beam = self.beam = next(b for b in d.beam if None not in b)
+            beam = next((onebeam for onebeam in d.beam
+                         if all(a is not None for a in onebeam)),
+                        [None, None, None],)
         else:
-            b.beam = self.beam = d.beam
+            beam = d.beam
+        b.beam = self.beam = Beam(beam=beam).beam
         self.add_beam(**b.todict())
         return (d.data, d.x, d.y, d.v, d.sigma, d.bunit,
                 self._kw, singlepix)
@@ -678,7 +750,7 @@ class PlotAstroData(AstroFrame):
     def add_beam(self, **kwargs: Any) -> None:
         """Use add_region() to plot the beam.
 
-        kwargs may include the arguments of Beam, except for beam_kwargs, to specify the beam appearance. Those arguments may be a list of each format.
+        kwargs may include the arguments of Beam, except for beam_kwargs, to specify the beam appearance. A single ``beamcolor`` or ``beampos`` value applies to every beam; per-beam lists must provide one value for each beam. A ``[None, None, None]`` beam is skipped.
 
         Default keyword values:
             Beam patch: ``facecolor=beamcolor`` and ``edgecolor=None``. Other keyword arguments override these values and are passed to ``add_region``.
@@ -687,6 +759,7 @@ class PlotAstroData(AstroFrame):
         show_beam, beamcolor, beampos = b.show_beam, b.beamcolor, b.beampos
         beam = b.beam
         del kwargs['beam']
+        b.validate_display()
         if not show_beam:
             return
 
@@ -695,7 +768,7 @@ class PlotAstroData(AstroFrame):
         blist = [beam] if np.ndim(beam) == 1 else beam
         n = len(blist)
         bclist = beamcolor if isinstance(beamcolor, list) else [beamcolor] * n
-        islist = beampos == [None] * 3 or np.ndim(beampos) == 2
+        islist = beampos is not None and not b._is_position(beampos)
         bplist = beampos if islist else [beampos] * n
         for (bmaj, bmin, bpa), bc, bp in zip(blist, bclist, bplist):
             if None in [bmaj, bmin, bpa]:

{plotastrodata-1.9.21 → plotastrodata-1.10.0/plotastrodata.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotastrodata
-Version: 1.9.21
+Version: 1.10.0
 Summary: plotastrodata is a tool for astronomers to create figures from FITS files and perform fundamental data analyses with ease.
 Home-page: https://github.com/yusukeaso-astron/plotastrodata
 Download-URL: https://github.com/yusukeaso-astron/plotastrodata
@@ -14,12 +14,13 @@ License-File: LICENSE
 Requires-Dist: astropy>=7.2
 Requires-Dist: corner
 Requires-Dist: dynesty
-Requires-Dist: emcee>=3.0
+Requires-Dist: emcee>=3.1.5
 Requires-Dist: matplotlib
 Requires-Dist: numpy>=2.0
 Requires-Dist: pillow
 Requires-Dist: plotly
 Requires-Dist: ptemcee
+Requires-Dist: pydantic>=2
 Requires-Dist: scikit-image
 Requires-Dist: scipy
 Requires-Dist: tqdm
@@ -84,13 +85,14 @@ plotastrodata can do the following things.
 * astropy >= 7.2
 * corner (only for fitting)
 * dynesty (only for fitting)
-* emcee >= 3.0 (only for fitting)
+* emcee >= 3.1.5 (only for fitting)
 * ffmpeg (only for movie)
 * matplotlib
 * numpy >= 2.0
 * pillow (only for RGB figures)
 * plotly (only for html cube)
 * ptemcee (only for fitting)
+* pydantic >= 2
 * scikit-image (only for html cube)
 * scipy
 * tqdm (only for fitting)

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/plotastrodata.egg-info/requires.txt

@@ -1,12 +1,13 @@
 astropy>=7.2
 corner
 dynesty
-emcee>=3.0
+emcee>=3.1.5
 matplotlib
 numpy>=2.0
 pillow
 plotly
 ptemcee
+pydantic>=2
 scikit-image
 scipy
 tqdm

{plotastrodata-1.9.21 → plotastrodata-1.10.0}/setup.cfg

@@ -19,12 +19,13 @@ install_requires =
 	astropy >= 7.2
 	corner
 	dynesty
-	emcee >= 3.0
+	emcee >= 3.1.5
 	matplotlib
 	numpy >= 2.0
 	pillow
 	plotly
 	ptemcee
+	pydantic >= 2
 	scikit-image
 	scipy
 	tqdm