integrate_module 0.99.3__tar.gz → 0.99.6__tar.gz

{integrate_module-0.99.3/integrate_module.egg-info → integrate_module-0.99.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: integrate_module
-Version: 0.99.3
+Version: 0.99.6
 Summary: Localized probabilistic data integration
 Author-email: Thomas Mejer Hansen <tmeha@geo.au.dk>
 License: MIT
@@ -34,6 +34,13 @@ Requires-Dist: jax
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Requires-Dist: black; extra == "dev"
+Provides-Extra: ml
+Requires-Dist: tensorflow; extra == "ml"
+Requires-Dist: scikit-learn; extra == "ml"
+Requires-Dist: keras_tuner; extra == "ml"
+Provides-Extra: examples
+Requires-Dist: geopandas; extra == "examples"
+Requires-Dist: shapely; extra == "examples"
 Provides-Extra: docs
 Requires-Dist: sphinx; extra == "docs"
 Requires-Dist: nbsphinx; extra == "docs"
@@ -43,6 +50,8 @@ Requires-Dist: myst-parser; extra == "docs"
 Requires-Dist: sphinx-rtd-theme; extra == "docs"
 Requires-Dist: furo; extra == "docs"
 Requires-Dist: tomli; python_version < "3.11" and extra == "docs"
+Provides-Extra: jax-cuda
+Requires-Dist: jax[cuda12]; extra == "jax-cuda"
 Dynamic: license-file
 
 # INTEGRATE Python Module

{integrate_module-0.99.3 → integrate_module-0.99.6}/integrate/__init__.py

@@ -36,6 +36,7 @@ from integrate.integrate import posterior_cumulative_thickness
 from integrate.integrate import use_parallel
 from integrate.integrate import kl_divergence
 from integrate.integrate import entropy
+from integrate.integrate import discrete_data_entropy
 from integrate.integrate import class_id_to_idx
 from integrate.integrate import is_notebook
 from integrate.integrate import get_hypothesis_probability
@@ -94,6 +95,7 @@ from integrate.integrate_plot import plot_profile_discrete
 from integrate.integrate_plot import plot_cumulative_probability_profile
 from integrate.integrate_plot import plot_T_EV
 from integrate.integrate_plot import plot_data_xy
+from integrate.integrate_plot import plot_discrete_data_entropy
 from integrate.integrate_plot import plot_data
 from integrate.integrate_plot import plot_data_prior_post
 from integrate.integrate_plot import plot_data_prior

{integrate_module-0.99.3 → integrate_module-0.99.6}/integrate/integrate.py

@@ -2963,12 +2963,95 @@ def entropy(P, base = None):
     >>> entropy(P)
     array([1.0, 0.469])
     """
-    P = np.atleast_2d(P)    
+    P = np.atleast_2d(P)
     if base is None:
         base = P.shape[1]
     H = -np.sum(P*np.log(P)/np.log(base), axis=1)
     return H
 
+
+def discrete_data_entropy(f_data_h5, id_list, depth_reduce='min', showInfo=1):
+    """
+    Compute the pointwise (per survey location) entropy of one or more
+    multinomial discrete /D{id} data entries in a DATA HDF5 file.
+
+    Each location's discrete observation is a probability-over-classes
+    profile spanning ``nm`` depth layers (shape ``(ns, nclass, nm)`` per id,
+    as written by :func:`save_data_multinomial`, e.g. via
+    :func:`save_borehole_data`). Entropy is computed per (location,
+    depth-layer) using ``scipy.stats.entropy`` (which correctly handles
+    exact-zero probabilities, unlike :func:`entropy`), the depth axis is
+    then collapsed per ``depth_reduce``, and — if more than one id is given —
+    the pointwise minimum across ids is returned (i.e. the best-informed id
+    at each location; adding more ids can only lower or keep equal the
+    entropy at a given location, never raise it).
+
+    Parameters
+    ----------
+    f_data_h5 : str
+        Path to the DATA HDF5 file.
+    id_list : int or list of int
+        One or more dataset ids referencing multinomial /D{id} groups
+        (e.g. from ``save_borehole_data()``'s ``id_out`` / ``id_borehole_list``).
+    depth_reduce : {'min', 'mean'}, optional
+        How to collapse the per-location depth-layer axis, per id, before
+        combining across ids. ``'min'`` (default) takes the lowest (most
+        informative) entropy value across depth layers, i.e. each id's best
+        depth-layer represents it at that location; ``'mean'`` averages
+        entropy across depth layers instead.
+    showInfo : int, optional
+        Verbosity level passed through to :func:`load_data`. Default 1.
+
+    Returns
+    -------
+    H : ndarray, shape (ns,)
+        Pointwise entropy in [0, 1] (base = nclass). NaN at locations not
+        covered by any of the given ids (``i_use == 0`` for all of them).
+
+    Examples
+    --------
+    >>> H = ig.discrete_data_entropy(f_data_h5, id_borehole_list)
+    >>> H = ig.discrete_data_entropy(f_data_h5, id_borehole_list, depth_reduce='mean')
+    """
+    import scipy as sp
+    import warnings
+    import integrate as ig
+
+    if not isinstance(id_list, list):
+        id_list = [id_list]
+    if depth_reduce not in ('mean', 'min'):
+        raise ValueError("depth_reduce must be 'mean' or 'min'")
+
+    DATA = ig.load_data(f_data_h5, id_arr=id_list, showInfo=showInfo)
+
+    H_per_id = []
+    for i, id in enumerate(id_list):
+        if DATA['noise_model'][i] != 'multinomial':
+            raise ValueError(
+                "D%d is not a multinomial dataset (noise_model=%r)" %
+                (id, DATA['noise_model'][i]))
+        P = DATA['d_obs'][i]                     # (ns, nclass, nm)
+        i_use = np.asarray(DATA['i_use'][i]).ravel().astype(bool)
+        ns, nclass, nm = P.shape
+
+        H = np.full((ns, nm), np.nan)
+        if np.any(i_use):
+            H[i_use, :] = sp.stats.entropy(
+                P[i_use].transpose(1, 0, 2).reshape(nclass, -1),
+                base=nclass
+            ).reshape(-1, nm)
+
+        with warnings.catch_warnings():
+            warnings.simplefilter('ignore', category=RuntimeWarning)
+            H_id = np.nanmean(H, axis=1) if depth_reduce == 'mean' else np.nanmin(H, axis=1)
+        H_per_id.append(H_id)
+
+    with warnings.catch_warnings():
+        warnings.simplefilter('ignore', category=RuntimeWarning)
+        H_map = np.nanmin(np.vstack(H_per_id), axis=0)
+    return H_map
+
+
 def class_id_to_idx(D, class_id=None):
     """
     Convert class identifiers to indices.

{integrate_module-0.99.3 → integrate_module-0.99.6}/integrate/integrate_borehole.py

@@ -572,8 +572,8 @@ def rescale_P_obs_temperature(P_obs, T=1.0):
 
     return P_obs_scaled
 
-def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, r_data=10, r_dis=100, doPlot=False,
-                     nan_freq=0.8, r_data_i_use=None):
+def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, range_data=10, range_xyz=100, doPlot=False,
+                     range_data_nan_freq=0.8, range_data_i_use=None):
     """
     Convert point-based discrete probability observations to gridded data with distance-based weighting.
 
@@ -594,23 +594,23 @@ def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, r_data=10, r_dis=100, doPlot=False,
         Y coordinate (e.g., UTM Northing) of the observation point.
     f_data_h5 : str
         Path to HDF5 data file containing survey geometry (X, Y coordinates).
-    r_data : float, optional
+    range_data : float, optional
         Inner radius in meters within which observations have full strength.
         Default is 10 meters.
-    r_dis : float, optional
+    range_xyz : float, optional
         Outer radius in meters for distance-based weighting. Beyond this distance,
         observations are fully attenuated (temperature → ∞). Default is 100 meters.
     doPlot : bool, optional
         If True, creates diagnostic plots showing weight distributions.
         Default is False.
-    nan_freq : float, optional
+    range_data_nan_freq : float, optional
         NaN-frequency threshold for automatic data-gate selection inside
         :func:`get_weight_from_position`. Gates where the fraction of
         non-NaN values is below this threshold are excluded. Default 0.8.
-        Ignored when ``r_data_i_use`` is provided.
-    r_data_i_use : array-like of int or None, optional
+        Ignored when ``range_data_i_use`` is provided.
+    range_data_i_use : array-like of int or None, optional
         Explicit gate/channel indices to use for data-distance computation
-        inside :func:`get_weight_from_position`. Overrides ``nan_freq`` when
+        inside :func:`get_weight_from_position`. Overrides ``range_data_nan_freq`` when
         provided. Default None.
 
     Returns
@@ -649,7 +649,7 @@ def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, r_data=10, r_dis=100, doPlot=False,
     >>> P_obs = compute_P_obs_discrete(depth_top, depth_bottom, lithology, z, class_id)
     >>> X_well, Y_well = 543000.0, 6175800.0
     >>> d_obs, i_use, T_all = Pobs_to_datagrid(P_obs, X_well, Y_well, 'survey_data.h5',
-    ...                                  r_data=10, r_dis=100)
+    ...                                  range_data=10, range_xyz=100)
     >>> # Write to data file
     >>> ig.save_data_multinomial(d_obs, i_use=i_use, id=2, f_data_h5='survey_data.h5')
 
@@ -673,8 +673,8 @@ def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, r_data=10, r_dis=100, doPlot=False,
 
     # Compute distance-based weights for all grid points
     w_combined, w_dis, w_data, i_use_from_func = ig.get_weight_from_position(
-        f_data_h5, X, Y, r_data=r_data, r_dis=r_dis, doPlot=doPlot,
-        nan_freq=nan_freq, r_data_i_use=r_data_i_use
+        f_data_h5, X, Y, range_data=range_data, range_xyz=range_xyz, doPlot=doPlot,
+        range_data_nan_freq=range_data_nan_freq, range_data_i_use=range_data_i_use
     )
 
     # Convert distance weight to temperature
@@ -703,9 +703,9 @@ def Pobs_to_datagrid(P_obs, X, Y, f_data_h5, r_data=10, r_dis=100, doPlot=False,
 
 
 
-def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400, r_data=2,
+def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, range_xyz=400, range_data=2,
                              useLog=True, doPlot=False, plFile=None, showInfo=0,
-                             nan_freq=0.8, r_data_i_use=None):
+                             range_data_nan_freq=0.8, range_data_i_use=None):
     """Calculate weights based on distance and data similarity to a reference point.
 
     This function computes three sets of weights:
@@ -723,9 +723,9 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
         Y coordinate of reference point (well). Default 0.
     i_ref : int, optional
         Index of reference point. Default -1 (auto-calculated as closest to x_well, y_well).
-    r_dis : float, optional
+    range_xyz : float, optional
         Geographic XY distance range [m] for spatial weighting. Default 400.
-    r_data : float, optional
+    range_data : float, optional
         Data-space similarity range parameter for data weighting. Default 2.
     useLog : bool, optional
         Apply log10 transform to data before computing similarity. Default True.
@@ -735,16 +735,16 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
         Output filename for the diagnostic plot. Auto-generated if None.
     showInfo : int, optional
         Verbosity level. Default 0.
-    nan_freq : float, optional
+    range_data_nan_freq : float, optional
         NaN-frequency threshold for automatic gate selection. Gates where the
         fraction of non-NaN values across all soundings is below this threshold
         are excluded from the data-distance computation. Default 0.8.
-        Ignored when ``r_data_i_use`` is provided.
-    r_data_i_use : array-like of int or None, optional
+        Ignored when ``range_data_i_use`` is provided.
+    range_data_i_use : array-like of int or None, optional
         Explicit gate/channel indices to use for the data-distance computation.
-        When provided, overrides the ``nan_freq`` automatic selection.
+        When provided, overrides the ``range_data_nan_freq`` automatic selection.
         A NaN check at the reference sounding is still applied.
-        Default None (use ``nan_freq`` threshold).
+        Default None (use ``range_data_nan_freq`` threshold).
 
     Returns
     -------
@@ -760,8 +760,8 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
     Notes
     -----
     Weights are calculated using Gaussian functions:
-    - Distance weights: exp(-dis² / r_dis²)
-    - Data weights:     exp(-sum_dd² / r_data²)
+    - Distance weights: exp(-dis² / range_xyz²)
+    - Data weights:     exp(-sum_dd² / range_data²)
     where dis is geographic distance and sum_dd is cumulative data difference.
     """
     import integrate as ig
@@ -777,12 +777,12 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
         i_ref = np.argmin((X-x_well)**2 + (Y-y_well)**2)
 
     # Select gates to use for data-distance computation
-    if r_data_i_use is not None:
-        gates = np.asarray(r_data_i_use, dtype=int)
+    if range_data_i_use is not None:
+        gates = np.asarray(range_data_i_use, dtype=int)
     else:
         n_not_nan = np.sum(~np.isnan(d_obs), axis=0)
         n_not_nan_freq = n_not_nan / d_obs.shape[0]
-        gates = np.where(n_not_nan_freq > nan_freq)[0]
+        gates = np.where(n_not_nan_freq > range_data_nan_freq)[0]
     # Remove gates that are NaN at the reference sounding
     gates = gates[~np.isnan(d_obs[i_ref, gates])]
     i_use = gates
@@ -795,12 +795,12 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
         d_test =d_obs[:,i_use]
     dd = np.abs(d_test - d_ref)
     sum_dd = np.sum(dd, axis=1)
-    w_data = np.exp(-1*sum_dd**2/r_data**2)
-    
+    w_data = np.exp(-1*sum_dd**2/range_data**2)
+
 
     # Compute the distance from each data point to the actual borehole location
     dis = np.sqrt((X-x_well)**2 + (Y-y_well)**2)
-    w_dis = np.exp(-1*dis**2/r_dis**2)
+    w_dis = np.exp(-1*dis**2/range_xyz**2)
 
     w_combined = w_data * w_dis
 
@@ -838,7 +838,7 @@ def get_weight_from_position(f_data_h5, x_well=0, y_well=0, i_ref=-1, r_dis=400,
         plt.xlabel('X')
         plt.ylabel('Y')
         if plFile is None:
-            plFile = 'weights_%d_%d_%d_rdis%d_rdata%d.png' % (x_well,y_well,i_ref,r_dis,r_data)
+            plFile = 'weights_%d_%d_%d_rdis%d_rdata%d.png' % (x_well,y_well,i_ref,range_xyz,range_data)
         plt.savefig(plFile, dpi=300)
 
     return w_combined, w_dis, w_data, i_ref
@@ -1023,46 +1023,54 @@ def save_borehole_data(f_prior_h5, f_data_h5, BH, **kwargs):
         Path to the prior HDF5 file.
     f_data_h5 : str
         Path to the observed-data HDF5 file.
-    BH : dict
+    BH : dict or list of dict
         Borehole dictionary with keys depth_top, depth_bottom, class_obs,
         class_prob, X, Y, name, method. Two optional keys control the
-        distance-weighting radii when r_data / r_dis are not passed as
-        explicit kwargs:
+        distance-weighting radii when range_data / range_xyz are not passed
+        as explicit kwargs:
 
         * ``range_data`` (float, optional) — data-space similarity radius.
           Survey points whose EM data response is similar to the borehole
           location receive higher weight; points that are more dissimilar are
-          down-weighted. Default: 1,000,000 (effectively no cutoff).
-        * ``range_dis`` (float, optional) — geographic XY distance [m] beyond
+          down-weighted. Only used if present and non-negative; otherwise the
+          default applies. Default: 1,000,000 (effectively no cutoff).
+        * ``range_xyz`` (float, optional) — geographic XY distance [m] beyond
           which the borehole exerts no influence on nearby survey points.
-          Default: 300 m.
-        * ``nan_freq`` (float, optional) — NaN-frequency threshold for automatic
+          Only used if present and non-negative; otherwise the default
+          applies. Default: 300 m.
+        * ``range_data_nan_freq`` (float, optional) — NaN-frequency threshold for automatic
           data-gate selection. Default: 0.8.
-        * ``r_data_i_use`` (list of int, optional) — explicit gate indices for
-          data-distance computation; overrides ``nan_freq`` when provided.
+        * ``range_data_i_use`` (list of int, optional) — explicit gate indices for
+          data-distance computation; overrides ``range_data_nan_freq`` when provided.
+
+        If ``BH`` is a list of dicts, each borehole is processed in turn
+        (one call per element, in order) using the same ``**kwargs`` for
+        every borehole; a per-borehole ``range_data``/``range_xyz``/etc. key
+        set inside an individual dict still takes effect for that borehole
+        exactly as in the single-dict case. See ``Returns`` below.
     **kwargs
         im_prior : int, optional
             Index of the discrete model parameter in f_prior_h5 (e.g. 2 for /M2).
             Default is 2.
         parallel : bool, optional
             Enable parallel mode computation. Default is False.
-        r_data : float, optional
+        range_data : float, optional
             Data-space similarity radius. Overrides ``BH['range_data']`` when
-            provided. Resolution order: explicit kwarg > BH['range_data'] >
-            1,000,000 (no cutoff).
-        r_dis : float, optional
-            Geographic XY fade-out distance [m]. Overrides ``BH['range_dis']``
-            when provided. Resolution order: explicit kwarg > BH['range_dis'] >
-            300 m.
-        nan_freq : float, optional
+            provided. Resolution order: explicit kwarg > BH['range_data']
+            (if present and non-negative) > 1,000,000 (no cutoff).
+        range_xyz : float, optional
+            Geographic XY fade-out distance [m]. Overrides ``BH['range_xyz']``
+            when provided. Resolution order: explicit kwarg > BH['range_xyz']
+            (if present and non-negative) > 300 m.
+        range_data_nan_freq : float, optional
             NaN-frequency threshold for automatic data-gate selection. Gates
             where the fraction of non-NaN soundings is below this threshold are
             excluded from data-distance computation. Resolution order: explicit
-            kwarg > BH['nan_freq'] > 0.8. Ignored when ``r_data_i_use`` is set.
-        r_data_i_use : list of int or None, optional
+            kwarg > BH['range_data_nan_freq'] > 0.8. Ignored when ``range_data_i_use`` is set.
+        range_data_i_use : list of int or None, optional
             Explicit gate/channel indices to use for data-distance computation.
-            Overrides ``nan_freq`` when provided. Resolution order: explicit
-            kwarg > BH['r_data_i_use'] > None.
+            Overrides ``range_data_nan_freq`` when provided. Resolution order: explicit
+            kwarg > BH['range_data_i_use'] > None.
         doPlot : bool, optional
             Plot distance-weight maps. Default is False.
         showInfo : int, optional
@@ -1072,32 +1080,56 @@ def save_borehole_data(f_prior_h5, f_data_h5, BH, **kwargs):
     Returns
     -------
     id_prior : int
-        Dataset index of the new /D entry added to f_prior_h5.
+        If ``BH`` is a single dict: dataset index of the new /D entry added
+        to f_prior_h5.
     id_out : int
-        Dataset index of the new /D entry added to f_data_h5.
+        If ``BH`` is a single dict: dataset index of the new /D entry added
+        to f_data_h5.
+    id_prior_list : list of int
+        If ``BH`` is a list of dicts: dataset indices of the new /D entries
+        added to f_prior_h5, one per borehole, same order as ``BH``.
+    id_borehole_list : list of int
+        If ``BH`` is a list of dicts: dataset indices of the new /D entries
+        added to f_data_h5, one per borehole, same order as ``BH``.
 
     Examples
     --------
     >>> # Single borehole
     >>> id_prior, id_data = ig.save_borehole_data(f_prior_h5, f_data_h5, BH)
 
-    >>> # All boreholes — collect data IDs for joint inversion
-    >>> id_borehole_list = []
-    >>> for BH in BHOLES:
-    ...     _, id_out = ig.save_borehole_data(f_prior_h5, f_data_h5, BH,
-    ...                                       r_data=2, r_dis=300, parallel=True)
-    ...     id_borehole_list.append(id_out)
+    >>> # All boreholes in one call — collect data IDs for joint inversion
+    >>> id_prior_list, id_borehole_list = ig.save_borehole_data(
+    ...     f_prior_h5, f_data_h5, BHOLES,
+    ...     range_data=2, range_xyz=300, parallel=True)
     >>> f_post_h5 = ig.integrate_rejection(f_prior_h5, f_data_h5,
     ...                                    id_use=[1] + id_borehole_list)
     """
+    if isinstance(BH, list):
+        id_prior_list = []
+        id_borehole_list = []
+        for bh in BH:
+            id_prior, id_out = save_borehole_data(f_prior_h5, f_data_h5, bh, **kwargs)
+            id_prior_list.append(id_prior)
+            id_borehole_list.append(id_out)
+        return id_prior_list, id_borehole_list
+
     import integrate as ig
 
+    def _resolve_radius(name, default):
+        val = kwargs.get(name, None)
+        if val is not None:
+            return val
+        val = BH.get(name, None)
+        if val is not None and val >= 0:
+            return val
+        return default
+
     im_prior = kwargs.get('im_prior', 2)
     parallel = kwargs.get('parallel', False)
-    r_data       = kwargs.get('r_data',       BH.get('range_data',   1_000_000))
-    r_dis        = kwargs.get('r_dis',        BH.get('range_dis',    300))
-    nan_freq     = kwargs.get('nan_freq',     BH.get('nan_freq',     0.8))
-    r_data_i_use = kwargs.get('r_data_i_use', BH.get('r_data_i_use', None))
+    range_data   = _resolve_radius('range_data', 1_000_000)
+    range_xyz    = _resolve_radius('range_xyz',  300)
+    range_data_nan_freq     = kwargs.get('range_data_nan_freq',     BH.get('range_data_nan_freq',     0.8))
+    range_data_i_use = kwargs.get('range_data_i_use', BH.get('range_data_i_use', None))
     doPlot   = kwargs.get('doPlot', False)
     showInfo = kwargs.get('showInfo', 1)
 
@@ -1109,8 +1141,8 @@ def save_borehole_data(f_prior_h5, f_data_h5, BH, **kwargs):
     # Step 2: extrapolate point observations to the survey grid
     d_obs, i_use, T_use = Pobs_to_datagrid(
         P_obs, BH['X'], BH['Y'], f_data_h5,
-        r_data=r_data, r_dis=r_dis, doPlot=doPlot,
-        nan_freq=nan_freq, r_data_i_use=r_data_i_use)
+        range_data=range_data, range_xyz=range_xyz, doPlot=doPlot,
+        range_data_nan_freq=range_data_nan_freq, range_data_i_use=range_data_i_use)
 
     # Step 3: save gridded observations to f_data_h5
     id_out, _ = ig.save_data_multinomial(

{integrate_module-0.99.3 → integrate_module-0.99.6}/integrate/integrate_io.py

@@ -3240,7 +3240,7 @@ def save_data_gaussian(D_obs, D_std = [], d_std=[], Cd=[], id=1, id_prior=None,
     return f_data_h5
 
 
-def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None, nan_value=None, showInfo=0, disregardFullNan=True, data_obs=None, data_std=None):
+def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None, nan_value=None, showInfo=0, disregardFullNan=True, data_obs=None, data_std=None, altitude=None, altitude_std=None, tx_altitude=None, tx_altitude_std=None, rx_altitude=None, rx_altitude_std=None):
     """
     Convert Aarhus Workbench XYZ export file(s) to an INTEGRATE HDF5 data file.
 
@@ -3292,6 +3292,38 @@ def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None
         same length as ``data_obs``.  Use ``None`` for an individual entry to
         fall back to ``0.05 * |d_obs|`` for that column.  If the whole
         parameter is omitted, all columns default to ``0.05 * |d_obs|``.
+    altitude : str, optional
+        Flightlines column name (case-insensitive) holding the platform's
+        flight altitude/height, e.g. ``'Alt'``.  When given, written as its
+        own Gaussian data block with ``id=2`` (the second dataset, after the
+        ``/D1`` dbdt data).  Any ``data_obs`` columns are then written
+        starting at ``id=3`` instead of ``id=2``.
+    altitude_std : str, float, or None, optional
+        Uncertainty for ``altitude``.
+        - A **string** is treated as another flightlines column name
+          (case-insensitive) holding the absolute std directly.
+        - A **number** with ``abs(altitude_std) < 1`` is treated as a
+          *relative* std: ``std = altitude_std * altitude``.
+        - A **number** with ``abs(altitude_std) >= 1`` is treated as an
+          *absolute* std in meters, constant for all soundings.
+        - If ``None`` (default), falls back to ``0.05 * |altitude|``.
+    tx_altitude : str, optional
+        Flightlines column name (case-insensitive) holding the transmitter
+        altitude/height. When given, written as its own Gaussian data block,
+        immediately after ``altitude`` (if also given). Optional — omitted
+        entirely if not given.
+    tx_altitude_std : str, float, or None, optional
+        Uncertainty for ``tx_altitude``. Same rules as ``altitude_std``
+        (string column name / relative number / absolute number / default
+        5% relative if ``None``). Only used if ``tx_altitude`` is given.
+    rx_altitude : str, optional
+        Flightlines column name (case-insensitive) holding the receiver
+        altitude/height. When given, written as its own Gaussian data block,
+        after ``altitude`` and ``tx_altitude`` (if also given). Optional —
+        omitted entirely if not given.
+    rx_altitude_std : str, float, or None, optional
+        Uncertainty for ``rx_altitude``. Same rules as ``altitude_std``.
+        Only used if ``rx_altitude`` is given.
 
     Returns
     -------
@@ -3380,9 +3412,22 @@ def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None
     ld = {k: pd.concat([xyz.layer_data[k] for xyz in xyz_list], ignore_index=True)
           for k in xyz_list[0].layer_data}
 
-    # Handle XYZ files that use 'x'/'y' instead of 'utmx'/'utmy'
+    # Handle XYZ files that use alternate column names for geometry
+    # (e.g. tTEM: utmx/utmy/line_no/elevation, SkyTEM: e/n/line/dem)
     if 'utmx' not in fl.columns and 'x' in fl.columns:
         fl = fl.rename(columns={'x': 'utmx', 'y': 'utmy'})
+    if 'utmx' not in fl.columns and 'e' in fl.columns:
+        fl = fl.rename(columns={'e': 'utmx', 'n': 'utmy'})
+    if 'line_no' not in fl.columns and 'line' in fl.columns:
+        fl = fl.rename(columns={'line': 'line_no'})
+    if 'elevation' not in fl.columns and 'dem' in fl.columns:
+        fl = fl.rename(columns={'dem': 'elevation'})
+
+    # Handle single-channel XYZ files (e.g. SkyTEM) that store the sounding
+    # data under a plain component name instead of the tTEM 'ch1gt' naming
+    if 'dbdt_ch1gt' not in ld and 'z_dbdt' in ld:
+        ld['dbdt_ch1gt'] = ld['z_dbdt']
+        ld['dbdt_std_ch1gt'] = ld['relunc_z_dbdt']
 
     # Determine dummy/missing value: explicit arg > XYZ header > fallback 9999
     if nan_value is None:
@@ -3393,7 +3438,12 @@ def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None
     # --- pair ch1 / ch2 rows (mirrors MATLAB logic) ---
     # Every ch1 row becomes a sounding.  HM data is filled where the
     # immediately following row is ch2; otherwise those columns stay NaN.
-    channel_arr = fl['channel_no'].values
+    # Single-channel systems (e.g. SkyTEM) have no 'channel_no' column at
+    # all: every row is its own (channel-1) sounding.
+    if 'channel_no' in fl.columns:
+        channel_arr = fl['channel_no'].values
+    else:
+        channel_arr = np.ones(len(fl))
     ch1_pos = np.where(channel_arr == 1)[0]
 
     # geometry from channel-1 rows (all of them)
@@ -3475,7 +3525,38 @@ def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None
         if n_channels >= 2:
             hf.create_dataset('/D1/i_hm', data=np.arange(i_hm_start, i_hm_end))
 
-    # --- write additional data columns as D2, D3, ... ---
+    # --- write altitude / rx_altitude / tx_altitude (if given) as their own Gaussian data blocks ---
+    def _resolve_std(obs, std_arg):
+        if isinstance(std_arg, str):
+            return fl[std_arg.lower()].values[ch1_pos][keep].reshape(-1, 1).astype(float)
+        elif isinstance(std_arg, (int, float)):
+            if abs(std_arg) < 1:
+                return std_arg * np.abs(obs)  # relative
+            else:
+                return np.full_like(obs, float(std_arg))  # absolute, meters
+        else:
+            return 0.05 * np.abs(obs)  # default: 5% relative
+
+    next_id = 2
+    for col, col_std, name in (
+        (altitude, altitude_std, 'Altitude'),
+        (tx_altitude, tx_altitude_std, 'Tx_altitude'),
+        (rx_altitude, rx_altitude_std, 'Rx_altitude'),
+    ):
+        if col is not None:
+            obs = fl[col.lower()].values[ch1_pos][keep].reshape(-1, 1).astype(float)
+            std = _resolve_std(obs, col_std)
+            save_data_gaussian(
+                obs, D_std=std,
+                f_data_h5=f_data_h5,
+                id=next_id,
+                name=name,
+                delete_if_exist=False,
+                showInfo=showInfo,
+            )
+            next_id += 1
+
+    # --- write additional data columns as D2, D3, ... (or shifted if altitude present) ---
     if data_obs is not None:
         _data_std = data_std if data_std is not None else [None] * len(data_obs)
         for i, col_obs in enumerate(data_obs):
@@ -3488,7 +3569,7 @@ def xyz_to_h5(file_xyz, file_gex, f_data_h5=None, i_lm_skip=None, i_hm_skip=None
             save_data_gaussian(
                 obs, D_std=std,
                 f_data_h5=f_data_h5,
-                id=i + 2,
+                id=next_id + i,
                 name=col_obs,
                 delete_if_exist=False,
                 showInfo=showInfo,
@@ -5198,15 +5279,17 @@ def write_borehole(W, filename, **kwargs):
           Used only by :func:`plot_boreholes` to place the well on a shared
           elevation axis.  Has no effect on inversion.
         * ``range_data`` (float, optional) – data-space similarity radius used by
-          :func:`save_borehole_data` when ``r_data`` is not passed explicitly.
+          :func:`save_borehole_data` when ``range_data`` is not passed explicitly.
+          Only used if present and non-negative, otherwise the default applies.
           Default: 1,000,000 (no cutoff).
-        * ``range_dis`` (float, optional) – geographic XY fade-out distance [m]
-          used by :func:`save_borehole_data` when ``r_dis`` is not passed explicitly.
-          Default: 300 m.
-        * ``nan_freq`` (float, optional) – NaN-frequency threshold for automatic
+        * ``range_xyz`` (float, optional) – geographic XY fade-out distance [m]
+          used by :func:`save_borehole_data` when ``range_xyz`` is not passed
+          explicitly. Only used if present and non-negative, otherwise the
+          default applies. Default: 300 m.
+        * ``range_data_nan_freq`` (float, optional) – NaN-frequency threshold for automatic
           data-gate selection in :func:`save_borehole_data`. Default: 0.8.
-        * ``r_data_i_use`` (list of int, optional) – explicit gate/channel indices
-          for data-distance computation; overrides ``nan_freq`` when provided.
+        * ``range_data_i_use`` (list of int, optional) – explicit gate/channel indices
+          for data-distance computation; overrides ``range_data_nan_freq`` when provided.
 
         numpy arrays and scalars are automatically converted to plain
         Python lists/numbers so the file is human-readable JSON.