xarpes 0.3.3__py3-none-any.whl → 0.4.0__py3-none-any.whl

xarpes/__init__.py

@@ -1,4 +1,4 @@
-__version__ = '0.3.3'
+__version__ = '0.4.0'
 
 from .spectral import *
 from .distributions import *

xarpes/functions.py

@@ -254,65 +254,119 @@ def download_examples():
     import shutil
     import io
     import jupytext
+    import tempfile
+    import re
 
-    # Main xARPES repo (examples now live in /examples here)
-    repo_url = 'https://github.com/xARPES/xARPES'
-    output_dir = '.'  # Directory from which the function is called
+    # Main xARPES repo (examples live under /examples there)
+    repo_url = "https://github.com/xARPES/xARPES"
+    output_dir = "."  # Directory from which the function is called
 
     # Target 'examples' directory in the user's current location
-    final_examples_path = os.path.join(output_dir, 'examples')
+    final_examples_path = os.path.join(output_dir, "examples")
     if os.path.exists(final_examples_path):
         print("Warning: 'examples' folder already exists. "
               "No download will be performed.")
         return 1  # Exit the function if 'examples' directory exists
 
-    # Proceed with download if 'examples' directory does not exist
-    repo_parts = repo_url.replace('https://github.com/', '').rstrip('/')
-    zip_url = f'https://github.com/{repo_parts}/archive/refs/heads/main.zip'
-
-    # Make the HTTP request to download the zip file
-    print(f'Downloading {zip_url}')
-    response = requests.get(zip_url)
-    if response.status_code == 200:
-        zip_file_bytes = io.BytesIO(response.content)
-
-        with zipfile.ZipFile(zip_file_bytes, 'r') as zip_ref:
-            zip_ref.extractall(output_dir)
-
-        # Path to the extracted main folder (e.g. xARPES-main)
-        main_folder_path = os.path.join(
-            output_dir,
-            repo_parts.split('/')[-1] + '-main'
-        )
-        examples_path = os.path.join(main_folder_path, 'examples')
-
-        # Move the 'examples' directory to the target location
-        if os.path.exists(examples_path):
-            shutil.move(examples_path, final_examples_path)
-            print(f"'examples' subdirectory moved to {final_examples_path}")
-
-            # Convert all .Rmd files in the examples directory to .ipynb
-            # and delete the .Rmd files
-            for dirpath, dirnames, filenames in os.walk(final_examples_path):
-                for filename in filenames:
-                    if filename.endswith('.Rmd'):
-                        full_path = os.path.join(dirpath, filename)
-                        jupytext.write(
-                            jupytext.read(full_path),
-                            full_path.replace('.Rmd', '.ipynb')
-                        )
-                        os.remove(full_path)  # Deletes .Rmd file afterwards
-                        print(f'Converted and deleted {full_path}')
-
-        # Remove the rest of the extracted content
-        shutil.rmtree(main_folder_path)
-        print(f'Cleaned up temporary files in {main_folder_path}')
-        return 0
+    # --- Determine version from xarpes.__init__.__version__ -----------------
+    try:
+        # Import inside the function, avoiding circular imports at import time
+        import xarpes as _xarpes
+        raw_version = getattr(_xarpes, "__version__", None)
+    except Exception as exc:
+        print(f"Warning: could not import xarpes to determine version: {exc}")
+        raw_version = None
+
+    tag_version = None
+    if raw_version is not None:
+        raw_version = str(raw_version)
+        # Strip dev/local suffixes so that '0.3.3.dev1' or '0.3.3+0.gHASH'
+        # maps to the tag 'v0.3.3'. If you use plain '0.3.3' already, this is 
+        # a no-op.
+        m = re.match(r"(\d+\.\d+\.\d+)", raw_version)
+        if m:
+            tag_version = m.group(1)
+        else:
+            tag_version = raw_version
+
+        print(f"Determined xARPES version from __init__: {raw_version} "
+              f"(using tag version '{tag_version}').")
     else:
-        print('Failed to download the repository. Status code: '
-              f'{response.status_code}')
+        print("Warning: xarpes.__version__ is not defined; will skip "
+        "tag-based download and try the main branch only.")
+
+    # --- Build refs and use for–else to try them in order -------------------
+    repo_parts = repo_url.replace("https://github.com/", "").rstrip("/")
+
+    refs_to_try = []
+    if tag_version is not None:
+        refs_to_try.append(f"tags/v{tag_version}")  # version-matched examples
+    refs_to_try.append("heads/main")                # fallback: latest examples
+
+    response = None
+    for ref in refs_to_try:
+        zip_url = f"https://github.com/{repo_parts}/archive/refs/{ref}.zip"
+        print(f"Attempting to download examples from '{ref}':\n  {zip_url}")
+        response = requests.get(zip_url)
+
+        if response.status_code == 200:
+            if ref.startswith("tags/"):
+                print(f"Successfully downloaded examples from tagged release "
+                      f"'v{tag_version}'.")
+            else:
+                print("Tagged release not available; using latest examples "
+                "from the 'main' branch instead.")
+            break
+        else:
+            print("Failed to download from this ref. HTTP status code: "
+                  f"{response.status_code}")
+    else:
+        # for–else: only executed if we never hit 'break'
+        print("Error: could not download examples from any ref "
+              f"(tried: {', '.join(refs_to_try)}).")
         return 1
 
+    # At this point, 'response' holds a successful download
+    zip_file_bytes = io.BytesIO(response.content)
+
+    # --- Extract into a temporary directory to avoid polluting CWD ----------
+    with tempfile.TemporaryDirectory() as tmpdir:
+        with zipfile.ZipFile(zip_file_bytes, "r") as zip_ref:
+            zip_ref.extractall(tmpdir)
+            # First member gives us the top-level directory in the archive,
+            # typically something like 'xARPES-0.3.3/' or 'xARPES-main/'.
+            first_member = zip_ref.namelist()[0]
+
+        top_level_dir = first_member.split("/")[0]
+        main_folder_path = os.path.join(tmpdir, top_level_dir)
+        examples_path = os.path.join(main_folder_path, "examples")
+
+        if not os.path.exists(examples_path):
+            print("Error: downloaded archive does not contain an 'examples' "
+            "directory.")
+            return 1
+
+        # Move the 'examples' directory to the target location in the CWD
+        shutil.move(examples_path, final_examples_path)
+        print(f"'examples' subdirectory moved to {final_examples_path}")
+
+        # Convert all .Rmd files in the examples directory to .ipynb
+        # and delete the .Rmd files
+        for dirpath, dirnames, filenames in os.walk(final_examples_path):
+            for filename in filenames:
+                if filename.endswith(".Rmd"):
+                    full_path = os.path.join(dirpath, filename)
+                    jupytext.write(
+                        jupytext.read(full_path),
+                        full_path.replace(".Rmd", ".ipynb")
+                    )
+                    os.remove(full_path)  # Deletes .Rmd file afterwards
+                    print(f"Converted and deleted {full_path}")
+
+    # Temporary directory is cleaned up automatically
+    print("Cleaned up temporary files.")
+    return 0
+
 
 def set_script_dir():
     r"""This function sets the directory such that the xARPES code can be

xarpes/plotting.py

@@ -12,14 +12,19 @@
 """Functions related to plotting."""
 
 from functools import wraps
+from IPython import get_ipython
 import matplotlib.pyplot as plt
 import matplotlib as mpl
 
-def plot_settings(name='default'):
+
+def plot_settings(name='default', register_pre_run=True):
+    """Configure default plotting style for xARPES."""
+
     mpl.rc('xtick', labelsize=10, direction='in')
     mpl.rc('ytick', labelsize=10, direction='in')
     plt.rcParams['legend.frameon'] = False
     lw = dict(default=2.0, large=4.0)[name]
+
     mpl.rcParams.update({
         'lines.linewidth': lw,
         'lines.markersize': 3,
@@ -30,6 +35,31 @@ def plot_settings(name='default'):
         'axes.ymargin': 0.15,
     })
 
+    if register_pre_run:
+        _maybe_register_pre_run_close_all()
+
+
+def _maybe_register_pre_run_close_all():
+    """Register a pre_run_cell hook once, and only inside Jupyter."""
+
+    # Create the function attribute on first call
+    if not hasattr(_maybe_register_pre_run_close_all, "_registered"):
+        _maybe_register_pre_run_close_all._registered = False
+
+    if _maybe_register_pre_run_close_all._registered:
+        return
+
+    ip = get_ipython()
+    if ip is None or ip.__class__.__name__ != "ZMQInteractiveShell":
+        return
+
+    def _close_all(_info):
+        plt.close('all')
+
+    ip.events.register('pre_run_cell', _close_all)
+    _maybe_register_pre_run_close_all._registered = True
+
+
 def get_ax_fig_plt(ax=None, **kwargs):
     r"""Helper function used in plot functions supporting an optional `Axes`
     argument.

xarpes/spectral.py

@@ -16,7 +16,7 @@ from igor2 import binarywave
 from .plotting import get_ax_fig_plt, add_fig_kwargs
 from .functions import fit_leastsq, extend_function
 from .distributions import FermiDirac, Linear
-from .constants import uncr, pref, dtor, kilo
+from .constants import uncr, pref, dtor, kilo, stdv
 
 class BandMap:
     r"""
@@ -346,27 +346,41 @@ class BandMap:
         return mdcs, angle_range_out, self.angle_resolution, \
         enel_range_out, self.hnuminphi
 
-
     @add_fig_kwargs
     def plot(self, abscissa='momentum', ordinate='electron_energy',
-            self_energies=None, ax=None, **kwargs):
+             self_energies=None, ax=None, markersize=None,
+             plot_dispersions='none', **kwargs):
         r"""
-        Plot the band map. Optionally attach a collection of self-energies,
+        Plot the band map. Optionally overlay a collection of self-energies,
         e.g. a CreateSelfEnergies instance or any iterable of self-energy
-        objects. They are stored on `self` for later overlay plotting.
+        objects. Self-energies are *not* stored internally; they are used
+        only for this plotting call.
+
+        When self-energies are present and ``abscissa='momentum'``, their
+        MDC maxima are overlaid with 95 % confidence intervals.
+
+        The `plot_dispersions` argument controls bare-band plotting:
+
+        - "full"   : use the full momentum range of the map (default)
+        - "none"   : do not plot bare dispersions
+        - "kink"   : for each self-energy, use the min/max of its own
+          momentum range (typically its MDC maxima), with
+          `len(self.angles)` points.
+        - "domain" : for SpectralQuadratic, use only the left or right
+          domain relative to `center_wavevector`, based on the self-energy
+          attribute `side` ("left" / "right"); for other cases this behaves
+          as "full".
         """
+        import warnings
+
+        plot_disp_mode = plot_dispersions
+        valid_disp_modes = ('full', 'none', 'kink', 'domain')
+        if plot_disp_mode not in valid_disp_modes:
+            raise ValueError(
+                f"Invalid plot_dispersions '{plot_disp_mode}'. "
+                f"Valid options: {valid_disp_modes}."
+            )
 
-        # Optionally store self-energies on the instance
-        if self_energies is not None:
-            # You can wrap here if you like, e.g.:
-            # from .containers import CreateSelfEnergies
-            # if not isinstance(self_energies, CreateSelfEnergies):
-            #     self_energies = CreateSelfEnergies(self_energies)
-            self._self_energies = self_energies
-        elif not hasattr(self, "_self_energies"):
-            self._self_energies = None
-
-        # Validate options early
         valid_abscissa = ('angle', 'momentum')
         valid_ordinate = ('kinetic_energy', 'electron_energy')
 
@@ -381,57 +395,247 @@ class BandMap:
                 f"Valid options: {valid_ordinate}"
             )
 
+        if self_energies is not None:
+
+            # MDC maxima are defined in momentum space, not angle space
+            if abscissa == 'angle':
+                raise ValueError(
+                    "MDC maxima cannot be plotted against angles; they are "
+                    "defined in momentum space. Use abscissa='momentum' "
+                    "when passing self-energies."
+                )
+
         ax, fig, plt = get_ax_fig_plt(ax=ax)
 
         Angl, Ekin = np.meshgrid(self.angles, self.ekin)
-        mesh = None  # sentinel to detect missing branch
 
         if abscissa == 'angle':
             ax.set_xlabel('Angle ($\\degree$)')
             if ordinate == 'kinetic_energy':
                 mesh = ax.pcolormesh(
-                    Angl, Ekin, self.intensities, shading='auto',
-                    cmap=plt.get_cmap('bone').reversed(), **kwargs
-                )
+                    Angl, Ekin, self.intensities,
+                    shading='auto',
+                    cmap=plt.get_cmap('bone').reversed())
                 ax.set_ylabel('$E_{\\mathrm{kin}}$ (eV)')
             elif ordinate == 'electron_energy':
                 Enel = Ekin - self.hnuminphi
                 mesh = ax.pcolormesh(
-                    Angl, Enel, self.intensities, shading='auto',
-                    cmap=plt.get_cmap('bone').reversed(), **kwargs
-                )
+                    Angl, Enel, self.intensities,
+                    shading='auto',
+                    cmap=plt.get_cmap('bone').reversed())
                 ax.set_ylabel('$E-\\mu$ (eV)')
 
         elif abscissa == 'momentum':
-            Mome = np.sqrt(Ekin / pref) * np.sin(Angl * dtor)
             ax.set_xlabel(r'$k_{//}$ ($\mathrm{\AA}^{-1}$)')
-            if ordinate == 'kinetic_energy':
-                mesh = ax.pcolormesh(
-                    Mome, Ekin, self.intensities, shading='auto',
-                    cmap=plt.get_cmap('bone').reversed(), **kwargs
+
+            with warnings.catch_warnings(record=True) as wlist:
+                warnings.filterwarnings(
+                    "always",
+                    message=(
+                        "The input coordinates to pcolormesh are "
+                        "interpreted as cell centers, but are not "
+                        "monotonically increasing or decreasing."
+                    ),
+                    category=UserWarning,
                 )
-                ax.set_ylabel('$E_{\\mathrm{kin}}$ (eV)')
-            elif ordinate == 'electron_energy':
-                Enel = Ekin - self.hnuminphi
-                mesh = ax.pcolormesh(
-                    Mome, Enel, self.intensities, shading='auto',
-                    cmap=plt.get_cmap('bone').reversed(), **kwargs
+
+                Mome = np.sqrt(Ekin / pref) * np.sin(Angl * dtor)
+                mome_min = np.min(Mome)
+                mome_max = np.max(Mome)
+                full_disp_momenta = np.linspace(
+                    mome_min, mome_max, len(self.angles)
                 )
-                ax.set_ylabel('$E-\\mu$ (eV)')
 
-        # If no branch set 'mesh', fail with a clear message
-        if mesh is None:
-            raise RuntimeError(
-                "No plot produced for the combination: "
-                f"abscissa='{abscissa}', ordinate='{ordinate}'. "
-                f"Valid abscissa: {valid_abscissa}; "
-                f"valid ordinate: {valid_ordinate}."
-            )
+                if ordinate == 'kinetic_energy':
+                    mesh = ax.pcolormesh(
+                        Mome, Ekin, self.intensities,
+                        shading='auto',
+                        cmap=plt.get_cmap('bone').reversed())
+                    ax.set_ylabel('$E_{\\mathrm{kin}}$ (eV)')
+                elif ordinate == 'electron_energy':
+                    Enel = Ekin - self.hnuminphi
+                    mesh = ax.pcolormesh(
+                        Mome, Enel, self.intensities,
+                        shading='auto',
+                        cmap=plt.get_cmap('bone').reversed())
+                    ax.set_ylabel('$E-\\mu$ (eV)')
+
+                y_lims = ax.get_ylim()
+
+            if any("cell centers" in str(w.message) for w in wlist):
+                warnings.warn(
+                    "Conversion from angle to momenta causes warping of the "
+                    "cell centers. \n Cell edges of the mesh plot may look "
+                    "irregular.",
+                    UserWarning,
+                    stacklevel=2,
+                )
 
-        plt.colorbar(mesh, ax=ax, label='counts (-)')
-        return fig
+        if abscissa == 'momentum' and self_energies is not None:
+            for self_energy in self_energies:
+
+                mdc_maxima = getattr(self_energy, "mdc_maxima", None)
+
+                # If this self-energy doesn't contain maxima, don't plot
+                if mdc_maxima is None:
+                    continue
+
+                # Reserve a colour from the axes cycle for this self-energy,
+                # and use it consistently for MDC maxima and dispersion.
+                line_color = ax._get_lines.get_next_color()
+
+                peak_sigma = getattr(
+                    self_energy, "peak_positions_sigma", None
+                )
+                xerr = stdv * peak_sigma if peak_sigma is not None else None
+
+                if ordinate == 'kinetic_energy':
+                    y_vals = self_energy.ekin_range
+                else:
+                    y_vals = self_energy.enel_range
+
+                x_vals = mdc_maxima
+                label = getattr(self_energy, "label", None)
+
+                # First plot the MDC maxima, using the reserved colour
+                if xerr is not None:
+                    ax.errorbar(
+                        x_vals, y_vals, xerr=xerr, fmt='o',
+                        linestyle='', label=label,
+                        markersize=markersize,
+                        color=line_color, ecolor=line_color,
+                    )
+                else:
+                    ax.plot(
+                        x_vals, y_vals, linestyle='',
+                        marker='o', label=label,
+                        markersize=markersize,
+                        color=line_color,
+                    )
+
+                # Bare-band dispersion for SpectralLinear / SpectralQuadratic
+                spec_class = getattr(
+                    self_energy, "_class",
+                    self_energy.__class__.__name__,
+                )
+
+                if (plot_disp_mode != 'none'
+                        and spec_class in ("SpectralLinear",
+                                           "SpectralQuadratic")):
+
+                    # Determine momentum grid for the dispersion
+                    if plot_disp_mode == 'kink':
+                        x_arr = np.asarray(x_vals)
+                        mask = np.isfinite(x_arr)
+                        if not np.any(mask):
+                            # No valid k-points to define a range
+                            continue
+                        k_min = np.min(x_arr[mask])
+                        k_max = np.max(x_arr[mask])
+                        disp_momenta = np.linspace(
+                            k_min, k_max, len(self.angles)
+                        )
+                    elif (plot_disp_mode == 'domain'
+                          and spec_class == "SpectralQuadratic"):
+                        side = getattr(self_energy, "side", None)
+                        if side == 'left':
+                            disp_momenta = np.linspace(
+                                mome_min, self_energy.center_wavevector,
+                                len(self.angles)
+                            )
+                        elif side == 'right':
+                            disp_momenta = np.linspace(
+                                self_energy.center_wavevector, mome_max,
+                                len(self.angles)
+                            )
+                        else:
+                            # Fallback: no valid side, use full range
+                            disp_momenta = full_disp_momenta
+                    else:
+                        # 'full' or 'domain' for SpectralLinear
+                        disp_momenta = full_disp_momenta
+
+                    # --- Robust parameter checks before computing base_disp ---
+                    if spec_class == "SpectralLinear":
+                        fermi_vel = getattr(
+                            self_energy, "fermi_velocity", None
+                        )
+                        fermi_k = getattr(
+                            self_energy, "fermi_wavevector", None
+                        )
+                        if fermi_vel is None or fermi_k is None:
+                            missing = []
+                            if fermi_vel is None:
+                                missing.append("fermi_velocity")
+                            if fermi_k is None:
+                                missing.append("fermi_wavevector")
+                            raise TypeError(
+                                "Cannot plot bare dispersion for "
+                                "SpectralLinear: "
+                                f"{', '.join(missing)} is None."
+                            )
+
+                        base_disp = (
+                            fermi_vel * (disp_momenta - fermi_k)
+                        )
+
+                    else:  # SpectralQuadratic
+                        bare_mass = getattr(
+                            self_energy, "bare_mass", None
+                        )
+                        center_k = getattr(
+                            self_energy, "center_wavevector", None
+                        )
+                        fermi_k = getattr(
+                            self_energy, "fermi_wavevector", None
+                        )
 
+                        missing = []
+                        if bare_mass is None:
+                            missing.append("bare_mass")
+                        if center_k is None:
+                            missing.append("center_wavevector")
+                        if fermi_k is None:
+                            missing.append("fermi_wavevector")
+
+                        if missing:
+                            raise TypeError(
+                                "Cannot plot bare dispersion for "
+                                "SpectralQuadratic: "
+                                f"{', '.join(missing)} is None."
+                            )
+
+                        dk = disp_momenta - center_k
+                        base_disp = (
+                            pref * (dk ** 2 - fermi_k ** 2) / bare_mass
+                        )
+                    # --- end parameter checks and base_disp construction ---
+
+                    if ordinate == 'electron_energy':
+                        disp_vals = base_disp
+                    else:  # kinetic energy
+                        disp_vals = base_disp + self.hnuminphi
+
+                    band_label = getattr(self_energy, "label", None)
+                    if band_label is not None:
+                        band_label = f"{band_label} (bare)"
+
+                    ax.plot(
+                        disp_momenta, disp_vals,
+                        label=band_label,
+                        linestyle='--',
+                        color=line_color,
+                    )
+
+            handles, labels = ax.get_legend_handles_labels()
+            if any(labels):
+                ax.legend()
 
+            ax.set_ylim(y_lims)
+
+        plt.colorbar(mesh, ax=ax, label='counts (-)')
+        return fig
+    
     @add_fig_kwargs
     def fit_fermi_edge(self, hnuminphi_guess, background_guess=0.0,
                        integrated_weight_guess=1.0, angle_min=-np.inf,
@@ -1233,14 +1437,25 @@ class MDCs:
                 label = getattr(dist, 'label', str(dist))
                 individual_labels.append(label)
 
-                # ---- collect parameters for this distribution 
+                # ---- collect parameters for this distribution
                 # (Aggregated over slices)
                 cls = getattr(dist, 'class_name', None)
                 wanted = param_spec.get(cls, ())
 
                 # ensure dicts exist
                 label_bucket = aggregated_properties.setdefault(label, {})
-                class_bucket = label_bucket.setdefault(cls, {'label': label, '_class': cls})
+                class_bucket = label_bucket.setdefault(
+                    cls, {'label': label, '_class': cls}
+                )
+
+                # store center_wavevector (scalar) for SpectralQuadratic
+                if (
+                    cls == 'SpectralQuadratic'
+                    and hasattr(dist, 'center_wavevector')
+                ):
+                    class_bucket.setdefault(
+                        'center_wavevector', dist.center_wavevector
+                    )
 
                 # ensure keys for both values and sigmas
                 for pname in wanted:
@@ -1560,8 +1775,8 @@ class MDCs:
         return final_result
     
 
-    def expose_parameters(self, select_label, fermi_wavevector=None, 
-                        fermi_velocity=None, bare_mass=None, side=None):
+    def expose_parameters(self, select_label, fermi_wavevector=None,
+                          fermi_velocity=None, bare_mass=None, side=None):
         r"""
         Select and return fitted parameters for a given component label, plus a
         flat export dictionary containing values **and** 1σ uncertainties.
@@ -1575,7 +1790,8 @@ class MDCs:
         fermi_velocity : float, optional
             Optional Fermi velocity to include.
         bare_mass : float, optional
-            Optional bare mass to include (used for SpectralQuadratic dispersions).
+            Optional bare mass to include (used for SpectralQuadratic
+            dispersions).
         side : {'left','right'}, optional
             Optional side selector for SpectralQuadratic dispersions.
 
@@ -1588,30 +1804,41 @@ class MDCs:
         label : str
             Label of the selected distribution.
         selected_properties : dict or list of dict
-            Nested dictionary (or list thereof) containing <param> and 
-            <param>_sigma arrays.
+            Nested dictionary (or list thereof) containing <param> and
+            <param>_sigma arrays. For SpectralQuadratic components, a
+            scalar `center_wavevector` is also present.
         exported_parameters : dict
-            Flat dictionary of parameters and their uncertainties, plus optional
-            Fermi quantities and `side`.
+            Flat dictionary of parameters and their uncertainties, plus
+            optional Fermi quantities and `side`. For SpectralQuadratic
+            components, `center_wavevector` is included and taken directly
+            from the fitted distribution.
         """
 
         if self._ekin_range is None:
-            raise AttributeError("ekin_range not yet set. Run `.fit_selection()` first.")
+            raise AttributeError(
+                "ekin_range not yet set. Run `.fit_selection()` first."
+            )
 
         store = getattr(self, "_individual_properties", None)
         if not store or select_label not in store:
-            all_labels = (sorted(store.keys()) if isinstance(store, dict) else [])
+            all_labels = (sorted(store.keys())
+                          if isinstance(store, dict) else [])
             raise ValueError(
-                f"Label '{select_label}' not found in available labels: {all_labels}"
+                f"Label '{select_label}' not found in available labels: "
+                f"{all_labels}"
             )
 
-        # Convert lists → numpy arrays within the selected label’s classes
+        # Convert lists → numpy arrays within the selected label’s classes.
+        # Keep scalar center_wavevector as a scalar.
         per_class_dicts = []
         for cls, bucket in store[select_label].items():
             dct = {}
             for k, v in bucket.items():
                 if k in ("label", "_class"):
                     dct[k] = v
+                elif k == "center_wavevector":
+                    # keep scalar as-is, do not wrap in np.asarray
+                    dct[k] = v
                 else:
                     dct[k] = np.asarray(v)
             per_class_dicts.append(dct)
@@ -1628,20 +1855,23 @@ class MDCs:
             "side": side,
         }
 
-        # Collect parameters without prefixing by class
+        # Collect parameters without prefixing by class. This will also include
+        # center_wavevector from the fitted SpectralQuadratic class, and since
+        # there is no function argument with that name, it cannot be overridden.
         if isinstance(selected_properties, dict):
             for key, val in selected_properties.items():
                 if key not in ("label", "_class"):
                     exported_parameters[key] = val
         else:
-            # If multiple classes, merge sequentially (last overwrites same-name keys)
+            # If multiple classes, merge sequentially
+            # (last overwrites same-name keys).
             for cls_bucket in selected_properties:
                 for key, val in cls_bucket.items():
                     if key not in ("label", "_class"):
                         exported_parameters[key] = val
 
-        return self._ekin_range, self.hnuminphi, select_label, \
-            selected_properties, exported_parameters
+        return (self._ekin_range, self.hnuminphi, select_label,
+                selected_properties, exported_parameters)
 
 
 class SelfEnergy:
@@ -1697,6 +1927,7 @@ class SelfEnergy:
         self._peak_sigma       = self._properties.get("peak_sigma")
         self._broadening       = self._properties.get("broadening")
         self._broadening_sigma = self._properties.get("broadening_sigma")
+        self._center_wavevector = self._properties.get("center_wavevector")
 
         # lazy caches
         self._peak_positions = None
@@ -1763,6 +1994,7 @@ class SelfEnergy:
         self._peak_positions = None
         self._real = None
         self._real_sigma = None
+        self._mdc_maxima = None
 
     @property
     def fermi_wavevector(self):
@@ -1838,6 +2070,7 @@ class SelfEnergy:
         # invalidate dependent cache
         self._peak_positions = None
         self._real = None
+        self._mdc_maxima = None
 
     @property
     def peak_sigma(self):
@@ -1870,6 +2103,11 @@ class SelfEnergy:
         self._properties["broadening_sigma"] = x
         self._imag_sigma = None
 
+    @property
+    def center_wavevector(self):
+        """Read-only center wavevector (SpectralQuadratic, if present)."""
+        return self._center_wavevector
+    
     # ---------------- derived outputs ----------------
     @property
     def peak_positions(self):
@@ -1936,7 +2174,7 @@ class SelfEnergy:
                     "(SpectralLinear): set `fermi_velocity` first.")
                 self._imag_sigma = np.abs(self._fermi_velocity) * \
                     np.sqrt(self._ekin_range / pref) * self._broadening_sigma
-            else:  # SpectralQuadratic
+            else:
                 if self._bare_mass is None:
                     raise AttributeError("Cannot compute `imag_sigma` "
                     "(SpectralQuadratic): set `bare_mass` first.")
@@ -1987,6 +2225,178 @@ class SelfEnergy:
                     * np.abs(self.peak_positions / self._bare_mass)
         return self._real_sigma
 
+    @property
+    def mdc_maxima(self):
+        """
+        MDC maxima (lazy).
+
+        SpectralLinear:
+            identical to peak_positions
+
+        SpectralQuadratic:
+            peak_positions + center_wavevector
+        """
+        if getattr(self, "_mdc_maxima", None) is None:
+            if self.peak_positions is None:
+                return None
+
+            if self._class == "SpectralLinear":
+                self._mdc_maxima = self.peak_positions
+            elif self._class == "SpectralQuadratic":
+                self._mdc_maxima = (
+                    self.peak_positions + self._center_wavevector
+                )
+
+        return self._mdc_maxima
+    
+    def _se_legend_labels(self):
+        """Return (real_label, imag_label) for legend with safe subscripts."""
+        se_label = getattr(self, "label", None)
+
+        if se_label is None:
+            real_label = r"$\Sigma'(E)$"
+            imag_label = r"$-\Sigma''(E)$"
+            return real_label, imag_label
+
+        safe_label = str(se_label).replace("_", r"\_")
+
+        # If the label is empty after conversion, fall back
+        if safe_label == "":
+            real_label = r"$\Sigma'(E)$"
+            imag_label = r"$-\Sigma''(E)$"
+            return real_label, imag_label
+
+        real_label = rf"$\Sigma_{{\mathrm{{{safe_label}}}}}'(E)$"
+        imag_label = rf"$-\Sigma_{{\mathrm{{{safe_label}}}}}''(E)$"
+
+        return real_label, imag_label
+
+    @add_fig_kwargs
+    def plot_real(self, ax=None, **kwargs):
+        r"""Plot the real part Σ' of the self-energy as a function of E-μ.
+
+        Parameters
+        ----------
+        ax : Matplotlib-Axes or None
+            Axis to plot on. Created if not provided by the user.
+        **kwargs :
+            Additional keyword arguments passed to ``ax.errorbar``.
+
+        Returns
+        -------
+        fig : Matplotlib-Figure
+            Figure containing the Σ'(E) plot.
+        """
+
+        ax, fig, plt = get_ax_fig_plt(ax=ax)
+
+        x = self.enel_range
+        y = self.real
+        y_sigma = self.real_sigma
+
+        real_label, _ = self._se_legend_labels()
+        kwargs.setdefault("label", real_label)
+
+        if y_sigma is not None:
+            if np.isnan(y_sigma).any():
+                print(
+                    "Warning: some Σ'(E) uncertainty values are missing. "
+                    "Error bars omitted at those energies."
+                )
+            kwargs.setdefault("yerr", stdv * y_sigma)
+
+        ax.errorbar(x, y, **kwargs)
+        ax.set_xlabel(r"$E-\mu$ (eV)")
+        ax.set_ylabel(r"$\Sigma'(E)$ (eV)")
+        ax.legend()
+
+        return fig
+
+    @add_fig_kwargs
+    def plot_imag(self, ax=None, **kwargs):
+        r"""Plot the imaginary part -Σ'' of the self-energy vs. E-μ.
+
+        Parameters
+        ----------
+        ax : Matplotlib-Axes or None
+            Axis to plot on. Created if not provided by the user.
+        **kwargs :
+            Additional keyword arguments passed to ``ax.errorbar``.
+
+        Returns
+        -------
+        fig : Matplotlib-Figure
+            Figure containing the -Σ''(E) plot.
+        """
+
+        ax, fig, plt = get_ax_fig_plt(ax=ax)
+
+        x = self.enel_range
+        y = self.imag
+        y_sigma = self.imag_sigma
+
+        _, imag_label = self._se_legend_labels()
+        kwargs.setdefault("label", imag_label)
+
+        if y_sigma is not None:
+            if np.isnan(y_sigma).any():
+                print(
+                    "Warning: some -Σ''(E) uncertainty values are missing. "
+                    "Error bars omitted at those energies."
+                )
+            kwargs.setdefault("yerr", stdv * y_sigma)
+
+        ax.errorbar(x, y, **kwargs)
+        ax.set_xlabel(r"$E-\mu$ (eV)")
+        ax.set_ylabel(r"$-\Sigma''(E)$ (eV)")
+        ax.legend()
+
+        return fig
+
+    @add_fig_kwargs
+    def plot_both(self, ax=None, **kwargs):
+        r"""Plot Σ'(E) and -Σ''(E) vs. E-μ on the same axis."""
+
+        ax, fig, plt = get_ax_fig_plt(ax=ax)
+
+        x = self.enel_range
+        real = self.real
+        imag = self.imag
+        real_sigma = self.real_sigma
+        imag_sigma = self.imag_sigma
+
+        real_label, imag_label = self._se_legend_labels()
+
+        # --- plot Σ'
+        kw_real = dict(kwargs)
+        if real_sigma is not None:
+            if np.isnan(real_sigma).any():
+                print(
+                    "Warning: some Σ'(E) uncertainty values are missing. "
+                    "Error bars omitted at those energies."
+                )
+            kw_real.setdefault("yerr", stdv * real_sigma)
+        kw_real.setdefault("label", real_label)
+        ax.errorbar(x, real, **kw_real)
+
+        # --- plot -Σ''
+        kw_imag = dict(kwargs)
+        if imag_sigma is not None:
+            if np.isnan(imag_sigma).any():
+                print(
+                    "Warning: some -Σ''(E) uncertainty values are missing. "
+                    "Error bars omitted at those energies."
+                )
+            kw_imag.setdefault("yerr", stdv * imag_sigma)
+        kw_imag.setdefault("label", imag_label)
+        ax.errorbar(x, imag, **kw_imag)
+
+        ax.set_xlabel(r"$E-\mu$ (eV)")
+        ax.set_ylabel(r"$\Sigma'(E),\ -\Sigma''(E)$ (eV)")
+        ax.legend()
+
+        return fig
+
 
 class CreateSelfEnergies:
     r"""
@@ -2063,5 +2473,4 @@ class CreateSelfEnergies:
         r"""
         Return a {label: self_energy} dictionary for convenient access.
         """
-        return {se.label: se for se in self.self_energies}
-    
+        return {se.label: se for se in self.self_energies}

{xarpes-0.3.3.dist-info → xarpes-0.4.0.dist-info}/METADATA

@@ -1,12 +1,13 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: xarpes
-Version: 0.3.3
+Version: 0.4.0
 Summary: Extraction from angle resolved photoemission spectra
 Author: xARPES Developers
 Requires-Python: >=3.7.0
 Description-Content-Type: text/markdown
 Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
 Classifier: Programming Language :: Python :: 3
+License-File: LICENSE
 Requires-Dist: igor2>=0.5.8
 Requires-Dist: jupyterlab
 Requires-Dist: jupytext
@@ -15,7 +16,8 @@ Requires-Dist: numpy
 Requires-Dist: scipy
 Requires-Dist: lmfit
 Requires-Dist: pyqt5
-Requires-Dist: ipympl
+Requires-Dist: ipympl>=0.9.3
+Requires-Dist: ipywidgets>=8.1.5
 Requires-Dist: ipykernel<6.32.0
 Project-URL: Documentation, https://xarpes.github.io
 
@@ -31,7 +33,7 @@ This project is currently undergoing **beta testing**. Some of the functionaliti
 
 # Contributing
 
-Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged.
+Contributions to the code are most welcome. xARPES is intended to co-develop alongside the increasing complexity of experimental ARPES data sets. Contributions can be made by forking the code and creating a pull request. Importing of file formats from different beamlines is particularly encouraged. Files useful for developers can be found in `/dev_tools`, such as the `Rmd2py.py` script for the development of examples.
 
 # Installation
 
@@ -40,6 +42,8 @@ xARPES installation can be divided into graphical package manager instructions,
 - via conda-forge, out-of-the-box or editable installation, sourcing the [conda-forge package](https://anaconda.org/conda-forge/xarpes).  
 - via Pip, out-of-the-box or editable installation, sourcing the [PyPI package](https://pypi.org/project/xarpes).
 
+We strongly recommend installing xARPES in a (conda/pip) virtual environment, and to activate the environment each time before activating xARPES.
+
 ## Graphical package manager installation
 
 Most IDEs and scientific Python distributions include a GUI-based package manager.  
@@ -82,11 +86,13 @@ Example for Linux:
     wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh  
     bash Miniconda3-latest-Linux-x86_64.sh
 
-Create and activate an environment:
+Answer `y` to questions. Create and activate a new environment:
 
-    conda create -n <my_env> -c defaults -c conda-forge  
+    conda create -n <my_env> -c conda-forge  
     conda activate <my_env>
 
+Where `<my_env>` must be replaced by your desired name. Package compatibility ssues may arise if conda installs from different channels. This can be prevented by appending `--strict-channel-priority` to the creation command.
+
 ### Installing xARPES
 
 #### Option A — Out-of-the-box installation (from conda-forge)
@@ -116,8 +122,8 @@ Install venv if necessary:
 
 Create and activate a virtual environment:
 
-    python3 -m venv <my_venv>  
-    source <my_venv>/bin/activate
+    python3 -m venv <my_env>  
+    source <my_env>/bin/activate
 
 Upgrade pip:
 
@@ -146,6 +152,8 @@ After installation of xARPES, the `examples/` folder can be downloaded to the cu
 
     python -c "import xarpes; xarpes.download_examples()"
 
+This attempts to download the examples from the version corresponding encountered in `__init__.py`. If no corresponding tagged version can be downloaded, the code attempts to download the latest examples instead.
+
 # Execution
 
 It is recommended to use JupyterLab to analyse data. JupyterLab is launched using:

xarpes-0.4.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+xarpes/__init__.py,sha256=c_dJwE9MtE67k6ms-2ljYZxPwTHEHDUDtOiI_g6s9QE,125
+xarpes/constants.py,sha256=vQxxFeCdGIxMpdh5XGbeRbn7-HF1d5snWkR09d8spGc,587
+xarpes/distributions.py,sha256=svzhvf994_5gndJA1M04SW4MVfHEVwiAumbhO5Jj22s,23434
+xarpes/functions.py,sha256=4s2atkWyPUb1ipJApRDVMsow_47kt25wvSwLtfqD2fs,14261
+xarpes/plotting.py,sha256=3nwq-6q3i3hUG_tMv6y-62v2FceB2LuayDeE_fSdUr0,6499
+xarpes/spectral.py,sha256=2AmqiyAk3xYJpUj1zPwbdA1Q62mGAVvXJAWmyiGHb6s,93908
+xarpes-0.4.0.dist-info/entry_points.txt,sha256=917UR-cqFTMMI_vMqIbk7boYSuFX_zHwQlXKcj9vlCE,79
+xarpes-0.4.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+xarpes-0.4.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+xarpes-0.4.0.dist-info/METADATA,sha256=cBUTzdc-CF8QCIag1q7kgSISydC2o1Mo4ZlAHMe87n0,6526
+xarpes-0.4.0.dist-info/RECORD,,

{xarpes-0.3.3.dist-info → xarpes-0.4.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: flit 3.6.0
+Generator: flit 3.12.0
 Root-Is-Purelib: true
 Tag: py3-none-any

xarpes-0.3.3.dist-info/RECORD

@@ -1,11 +0,0 @@
-xarpes/__init__.py,sha256=fx6uw8FrJ2VesH-h-V0mQiUciW7oka3RL8jNgO0mtbs,125
-xarpes/constants.py,sha256=vQxxFeCdGIxMpdh5XGbeRbn7-HF1d5snWkR09d8spGc,587
-xarpes/distributions.py,sha256=svzhvf994_5gndJA1M04SW4MVfHEVwiAumbhO5Jj22s,23434
-xarpes/functions.py,sha256=gE76z-Y9UI1KNUUtADyLziLU1UJ43E1CHLDi_khj0bc,12007
-xarpes/plotting.py,sha256=W-5WaKjBtg8PIxTypqja2R29mgWkQ844lgRWci0nhn0,5679
-xarpes/spectral.py,sha256=ze6rPKrOg5jMoTL3Pv2MNdDGu5wOMzJJ2OF_iyrslRc,78580
-xarpes-0.3.3.dist-info/entry_points.txt,sha256=917UR-cqFTMMI_vMqIbk7boYSuFX_zHwQlXKcj9vlCE,79
-xarpes-0.3.3.dist-info/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
-xarpes-0.3.3.dist-info/WHEEL,sha256=jPMR_Dzkc4X4icQtmz81lnNY_kAsfog7ry7qoRvYLXw,81
-xarpes-0.3.3.dist-info/METADATA,sha256=sK0m3UVDAhHi5a5K29zmrz8eTBZLCvYqPkWLAXnnk7s,5741
-xarpes-0.3.3.dist-info/RECORD,,