pmagpy 4.3.7__py3-none-any.whl → 4.3.8__py3-none-any.whl

pmagpy/ipmag.py

@@ -1041,52 +1041,113 @@ def common_mean_bootstrap(Data1, Data2, NumSims=1000,
                           save=False, save_folder='.', fmt='svg', 
                           figsize=(7, 2.3), x_tick_bins=4,verbose=True):
     """
-    Conduct a bootstrap test (Tauxe, 2010) for a common mean on two declination,
-    inclination data sets. Plots are generated of the cumulative distributions
-    of the Cartesian coordinates of the means of the pseudo-samples (one for x,
-    one for y and one for z). If the 95 percent confidence bounds for each
-    component overlap, the two set of directions "pass" the test and are
-    consistent with sharing a common mean.
+    Conducts a bootstrap test for a common mean on two directional data sets.
 
-    Parameters:
-        Data1 : a nested list of directional data [dec,inc] (a di_block)
-        Data2 : a nested list of directional data [dec,inc] (a di_block)
-                if Data2 is length of 1, treat as single direction
-        NumSims : number of bootstrap samples (default is 1000)
-        save : optional save of plots (default is False)
-        save_folder : path to directory where plots should be saved
-        fmt : format of figures to be saved (default is 'svg')
-        figsize : optionally adjust figure size (default is (7, 2.3))
-        x_tick_bins : because they occasionally overlap depending on the data, this
-            argument allows you adjust number of tick marks on the x axis of graphs
-            (default is 4)
+    This function implements the bootstrap test from Tauxe (2010) to determine
+    if two sets of directional data are consistent with sharing a common mean.
+    It generates cumulative distribution plots for the X, Y, and Z components
+    of the bootstrapped means. The test "passes" if the 95% confidence bounds
+    for each of the three components overlap.
 
-    Returns:
-        **three plots** (cumulative distributions of the X, Y, Z of bootstrapped means, 
-        **result** (a boolean where 0 is fail and 1 is pass)
+    Alternatively, if a single direction is provided for `Data2`, the function
+    tests if that direction falls within the 95% confidence bounds of `Data1`.
 
-    Examples:
-        Develop two populations of directions using ``ipmag.fishrot()``. Use the
-        function to determine if they share a common mean.
+    Parameters
+    ----------
+    Data1 : array-like
+        A list of lists or NumPy array of directional data, where each inner
+        list is [declination, inclination].
+    Data2 : array-like
+        A second set of directional data in the same format as `Data1`, or a
+        single direction as [declination, inclination].
+    NumSims : int, optional
+        The number of bootstrap samples to generate. Defaults to 1000.
+    color1 : str, optional
+        Matplotlib color for the first dataset. Defaults to 'r' (red).
+    color2 : str, optional
+        Matplotlib color for the second dataset. Defaults to 'b' (blue).
+    save : bool, optional
+        If True, saves the generated plots. Defaults to False.
+    save_folder : str, optional
+        The directory path where plots will be saved. Defaults to '.'.
+    fmt : str, optional
+        The file format for saved plots (e.g., 'svg', 'png', 'pdf').
+        Defaults to 'svg'.
+    figsize : tuple, optional
+        The size of the figure for the plots. Defaults to (7, 2.3).
+    x_tick_bins : int, optional
+        The maximum number of tick mark bins for the x-axis of the plots.
+        Defaults to 4.
+    verbose : bool, optional
+        If True, prints the test result ('Pass' or 'Fail') to the console.
+        Defaults to True.
 
-        >>> directions_A = ipmag.fishrot(k=20, n=30, dec=40, inc=60)
-        >>> directions_B = ipmag.fishrot(k=35, n=25, dec=42, inc=57)
-        >>> ipmag.common_mean_bootstrap(directions_A, directions_B)
+    Returns
+    -------
+    int
+        Returns 1 if the datasets pass the common mean test, and 0 if they fail.
+
+    Notes
+    -----
+    The function also displays or saves three plots showing the cumulative
+    distributions for the X, Y, and Z components of the bootstrapped means. These
+    plots are a visual representation of the statistical test.
+
+    Examples
+    --------
+    Develop two populations of directions using ``ipmag.fishrot()`` and then
+    use the function to determine if they share a common mean.
+
+    >>> directions_A = ipmag.fishrot(k=20, n=30, dec=40, inc=60)
+    >>> directions_B = ipmag.fishrot(k=35, n=25, dec=42, inc=57)
+    >>> result = ipmag.common_mean_bootstrap_new(directions_A, directions_B)
+    Pass
+    >>> print(result)
+    1
+    
+    Compare a single direction to a population.
+    
+    >>> directions_A = ipmag.fishrot(k=100, n=30, dec=45, inc=45)
+    >>> direction_B = [45,45]
+    >>> common_mean_bootstrap_new(directions_A, direction_B)
+    Pass
     """
-    counter = 0
     BDI1 = pmag.di_boot(Data1)
     cart1 = pmag.dir2cart(BDI1).transpose()
     X1, Y1, Z1 = cart1[0], cart1[1], cart1[2]
-    if np.array(Data2).shape[0] > 2:
-        BDI2 = pmag.di_boot(Data2)
-        cart2 = pmag.dir2cart(BDI2).transpose()
+    
+    Data2_arr = np.asarray(Data2, dtype=float)
+
+    # Determine if Data2 is a single direction or a block
+    if Data2_arr.ndim == 1 and Data2_arr.size in (2, 3):
+        is_block = False
+        single_direction = Data2_arr  # (2,) or (3,)
+    elif Data2_arr.ndim == 2 and Data2_arr.shape[1] in (2, 3):
+        is_block = Data2_arr.shape[0] > 1
+        direction_block = Data2_arr  # (N, 2) or (N, 3)
+    elif Data2_arr.ndim == 2 and Data2_arr.shape[0] in (2, 3) and Data2_arr.shape[1] > 1:
+        # Handle transposed input like (2, N) or (3, N)
+        direction_block = Data2_arr.T
+        if direction_block.shape[1] not in (2, 3):
+            raise ValueError(f"Expected (N, 2) or (N, 3), got {direction_block.shape}.")
+        is_block = direction_block.shape[0] > 1
+    else:
+        raise ValueError(
+            f"Expected [dec, inc(, intensity)] or an array with 2 or 3 columns; "
+            f"got shape {Data2_arr.shape}."
+        )
+
+    if is_block:
+        BDI2 = pmag.di_boot(direction_block)
+        cart2 = pmag.dir2cart(BDI2).T
         X2, Y2, Z2 = cart2[0], cart2[1], cart2[2]
     else:
-        cart = pmag.dir2cart(Data2).transpose()
-    
+        cart2 = pmag.dir2cart(single_direction).T
+        X2, Y2, Z2 = cart2[0], cart2[1], cart2[2]
+
     minimum = int(0.025 * len(X1))
     maximum = int(0.975 * len(X1))
-    
+
     fignum = 1
     fig = plt.figure(figsize=figsize)
 
@@ -1094,43 +1155,45 @@ def common_mean_bootstrap(Data1, Data2, NumSims=1000,
     X1, y = pmagplotlib.plot_cdf(fignum, X1, "X component", color1, "")
     bounds1 = [X1[minimum], X1[maximum]]
     pmagplotlib.plot_vs(fignum, bounds1, color1, '-')
-    if np.array(Data2).shape[0] > 2:
+    if is_block:
         X2, y = pmagplotlib.plot_cdf(fignum, X2, "X component", color2, "")
         bounds2 = [X2[minimum], X2[maximum]]
         pmagplotlib.plot_vs(fignum, bounds2, color2, '--')
+        x_overlap = pmag.interval_overlap(bounds1, bounds2)
     else:
-        pmagplotlib.plot_vs(fignum, [cart[0]], 'k', '--')
+        x_in_bounds = X1[minimum] <= X2 <= X1[maximum]
+        pmagplotlib.plot_vs(fignum, [X2], color2, ':')
     plt.ylim(0, 1)
     plt.locator_params(nbins=x_tick_bins)
-    x_overlap = pmag.interval_overlap(bounds1,bounds2)
 
     plt.subplot(1, 3, 2)
     Y1, y = pmagplotlib.plot_cdf(fignum, Y1, "Y component", color1, "")
     bounds1 = [Y1[minimum], Y1[maximum]]
     pmagplotlib.plot_vs(fignum, bounds1, color1, '-')
-    if np.array(Data2).shape[0] > 2:
+    if is_block:
         Y2, y = pmagplotlib.plot_cdf(fignum, Y2, "Y component", color2, "")
         bounds2 = [Y2[minimum], Y2[maximum]]
         pmagplotlib.plot_vs(fignum, bounds2, color2, '--')
+        y_overlap = pmag.interval_overlap(bounds1, bounds2)
     else:
-        pmagplotlib.plot_vs(fignum, [cart[1]], 'k', '--')
+        y_in_bounds = Y1[minimum] <= Y2 <= Y1[maximum]
+        pmagplotlib.plot_vs(fignum, [Y2], color2, ':')
     plt.ylim(0, 1)
-    y_overlap = pmag.interval_overlap(bounds1,bounds2)
-    
+
     plt.subplot(1, 3, 3)
     Z1, y = pmagplotlib.plot_cdf(fignum, Z1, "Z component", color1, "")
     bounds1 = [Z1[minimum], Z1[maximum]]
     pmagplotlib.plot_vs(fignum, bounds1, color1, '-')
-
-    if np.array(Data2).shape[0] > 2:
+    if is_block:
         Z2, y = pmagplotlib.plot_cdf(fignum, Z2, "Z component", color2, "")
         bounds2 = [Z2[minimum], Z2[maximum]]
         pmagplotlib.plot_vs(fignum, bounds2, color2, '--')
+        z_overlap = pmag.interval_overlap(bounds1, bounds2)
     else:
-        pmagplotlib.plot_vs(fignum, [cart[2]], 'k', '--')
+        z_in_bounds = Z1[minimum] <= Z2 <= Z1[maximum]
+        pmagplotlib.plot_vs(fignum, [Z2], color2, ':')
     plt.ylim(0, 1)
     plt.locator_params(nbins=x_tick_bins)
-    z_overlap = pmag.interval_overlap(bounds1,bounds2)
 
     plt.tight_layout()
     if save:
@@ -1138,39 +1201,67 @@ def common_mean_bootstrap(Data1, Data2, NumSims=1000,
             save_folder, 'common_mean_bootstrap') + '.' + fmt,
                     dpi=300,bbox_inches='tight')
     plt.show()
-    
-    if ((x_overlap != 0) and (y_overlap != 0) and (z_overlap != 0)):
-        if verbose:print('Pass')
-        result = 1
-        return result
-    elif ((x_overlap == 0) and (y_overlap != 0) and (z_overlap != 0)):
-        if verbose:print('Fail, distinct in x')
-        result = 0
-        return result
-    elif ((x_overlap != 0) and (y_overlap == 0) and (z_overlap != 0)):
-        if verbose:print('Fail, distinct in y')
-        result = 0
-        return result
-    elif ((x_overlap != 0) and (y_overlap != 0) and (z_overlap == 0)):
-        if verbose:print('Fail, distinct in z')
-        result = 0
-        return result
-    elif ((x_overlap == 0) and (y_overlap == 0) and (z_overlap != 0)):
-        if verbose:print('Fail, distinct in x and y')
-        result = 0
-        return result
-    elif ((x_overlap == 0) and (y_overlap != 0) and (z_overlap == 0)):
-        if verbose:print('Fail, distinct in x and z')
-        result = 0
-        return result
-    elif ((x_overlap != 0) and (y_overlap == 0) and (z_overlap == 0)):
-        if verbose:print('Fail, distinct in y and z')
-        result = 0
-        return result
-    elif ((x_overlap == 0) and (y_overlap == 0) and (z_overlap == 0)):
-        if verbose:print('Fail, distinct in x, y and z')
-        result = 0
-        return result
+
+    if is_block:
+        if ((x_overlap != 0) and (y_overlap != 0) and (z_overlap != 0)):
+            if verbose: print('Pass')
+            result = 1
+            return result
+        elif ((x_overlap == 0) and (y_overlap != 0) and (z_overlap != 0)):
+            if verbose: print('Fail, distinct in x')
+            result = 0
+            return result
+        elif ((x_overlap != 0) and (y_overlap == 0) and (z_overlap != 0)):
+            if verbose: print('Fail, distinct in y')
+            result = 0
+            return result
+        elif ((x_overlap != 0) and (y_overlap != 0) and (z_overlap == 0)):
+            if verbose: print('Fail, distinct in z')
+            result = 0
+            return result
+        elif ((x_overlap == 0) and (y_overlap == 0) and (z_overlap != 0)):
+            if verbose: print('Fail, distinct in x and y')
+            result = 0
+            return result
+        elif ((x_overlap == 0) and (y_overlap != 0) and (z_overlap == 0)):
+            if verbose: print('Fail, distinct in x and z')
+            result = 0
+            return result
+        elif ((x_overlap != 0) and (y_overlap == 0) and (z_overlap == 0)):
+            if verbose: print('Fail, distinct in y and z')
+            result = 0
+            return result
+        elif ((x_overlap == 0) and (y_overlap == 0) and (z_overlap == 0)):
+            if verbose: print('Fail, distinct in x, y and z')
+            result = 0
+            return result
+
+    else:
+        if x_in_bounds and y_in_bounds and z_in_bounds:
+            if verbose: print('Pass')
+            return 1
+        elif (not x_in_bounds) and y_in_bounds and z_in_bounds:
+            if verbose: print('Fail, distinct in x')
+            return 0
+        elif x_in_bounds and (not y_in_bounds) and z_in_bounds:
+            if verbose: print('Fail, distinct in y')
+            return 0
+        elif x_in_bounds and y_in_bounds and (not z_in_bounds):
+            if verbose: print('Fail, distinct in z')
+            return 0
+        elif (not x_in_bounds) and (not y_in_bounds) and z_in_bounds:
+            if verbose: print('Fail, distinct in x and y')
+            return 0
+        elif (not x_in_bounds) and y_in_bounds and (not z_in_bounds):
+            if verbose: print('Fail, distinct in x and z')
+            return 0
+        elif x_in_bounds and (not y_in_bounds) and (not z_in_bounds):
+            if verbose: print('Fail, distinct in y and z')
+            return 0
+        else:
+            # all three out of bounds
+            if verbose: print('Fail, distinct in x, y and z')
+            return 0
         
 
 def common_mean_bootstrap_H23(Data1, Data2, num_sims=10000, alpha=0.05, plot=True, reversal=False,
@@ -2483,6 +2574,7 @@ def make_robinson_map(central_longitude=0, figsize=(8, 8),
         ax.gridlines(xlocs=lon_grid, ylocs=lat_grid)
     return ax
 
+
 def plot_pole(map_axis, plon, plat, A95, label='', color='k', edgecolor='k',
               marker='o', markersize=20, legend='no',outline=True,
               filled_pole=False, fill_color='k', fill_alpha=1.0, 
@@ -2573,7 +2665,9 @@ def plot_poles(map_axis, plon, plat, A95, label='', color='k', edgecolor='k',
         >>> ipmag.plot_poles(map_axis, plons, plats, A95s, color=colors, markersize=40)
 
     """
-
+    if not has_cartopy:
+        print('-W- cartopy must be installed to run ipmag.plot_poles')
+        return
     map_axis.scatter(plon, plat, marker=marker,
                      color=color, edgecolors=edgecolor, s=markersize,
                      label=label, zorder=zorder, transform=ccrs.PlateCarree(), alpha=alpha)
@@ -2599,6 +2693,7 @@ def plot_poles(map_axis, plon, plat, A95, label='', color='k', edgecolor='k',
     if legend == 'yes':
         plt.legend(loc=2)
 
+
 def plot_pole_ellipse(map_axis, dictionary, 
                       color='k', edgecolor='k', marker='s', 
                       markersize=20, label='', alpha=1.0, lw=1, lower=True, zorder=100):
@@ -2634,6 +2729,9 @@ def plot_pole_ellipse(map_axis, dictionary,
         >>> map_axis = ipmag.make_orthographic_map(central_longitude=200,central_latitude=90)
         >>> ipmag.plot_pole_ellipse(map_axis,kent_dict, color='red',markersize=40)
     """
+    if not has_cartopy:
+        print('-W- cartopy must be installed to run ipmag.plot_pole_ellipse')
+        return
     pars = []
     pars.append(dictionary['dec'])
     pars.append(dictionary['inc'])
@@ -2660,7 +2758,7 @@ def plot_pole_ellipse(map_axis, dictionary,
 def plot_pole_dp_dm(map_axis, plon, plat, slon, slat, dp, dm, pole_label='pole', site_label='site',
                     pole_color='k', pole_edgecolor='k', pole_marker='o',
                     site_color='r', site_edgecolor='r', site_marker='s',
-                    markersize=20, legend=True, transform=ccrs.PlateCarree()):
+                    markersize=20, legend=True, transform="PlateCarree"):
     """
     This function plots a paleomagnetic pole and a dp/dm confidence ellipse on a cartopy map axis.
 
@@ -2683,11 +2781,12 @@ def plot_pole_dp_dm(map_axis, plon, plat, slon, slat, dp, dm, pole_label='pole',
         pole_label : string that labels the pole.
         site_label : string that labels the site
         legend : the default is a legend (True). Putting False will suppress legend plotting.
-        transform : the default is the PlateCarree transform in Cartopy. 
-                    Other transforms can be chosen (e.g. ccrs.geodetic), but this parameter 
-                    rarely needs to be changed by the user and is included for completeness
-                    and in case of artifacts arising from the PlateCarree transform on some
-                    map projections in which case the Geodetic transform may work better.
+        transform : str or cartopy.crs.Projection, default "PlateCarree"
+            The coordinate reference system used to interpret input coordinates.
+            Can be a string ("PlateCarree" or "Geodetic") or a Cartopy CRS object
+            (e.g., ccrs.PlateCarree()). If a string is provided, it will be
+            internally mapped to the appropriate Cartopy transform. This parameter
+            rarely needs to be changed, but "Geodetic" may help in certain projections.
 
     Examples:
         >>> dec = 280
@@ -2707,14 +2806,43 @@ def plot_pole_dp_dm(map_axis, plon, plat, slon, slat, dp, dm, pole_label='pole',
     if not has_cartopy:
         print('-W- cartopy must be installed to run ipmag.plot_pole_dp_dm')
         return
+    
+    transform_map = {
+        "PlateCarree": ccrs.PlateCarree(),
+        "Geodetic": ccrs.Geodetic(),
+    }
+
+    if isinstance(transform, str):
+        if transform not in transform_map:
+            raise ValueError(f"Invalid transform '{transform}'. Choose from {list(transform_map)}.")
+        transform_obj = transform_map[transform]
+    else:
+        transform_obj = transform 
+        
     dp_km = dp*111.32
     dm_km = dm*111.32
-    map_axis.scatter(plon, plat, marker=pole_marker,
-                     color=pole_color, edgecolors=pole_edgecolor, s=markersize,
-                     label=pole_label, zorder=101, transform=ccrs.PlateCarree())
-    map_axis.scatter(slon, slat, marker=site_marker,
-                     color=site_color, edgecolors=site_edgecolor, s=markersize,
-                     label=site_label, zorder=101, transform=ccrs.PlateCarree())
+    map_axis.scatter(
+        plon,
+        plat,
+        marker=pole_marker,
+        color=pole_color,
+        edgecolors=pole_edgecolor,
+        s=markersize,
+        label=pole_label,
+        zorder=101,
+        transform=transform_obj,
+    )
+    map_axis.scatter(
+        slon,
+        slat,
+        marker=site_marker,
+        color=site_color,
+        edgecolors=site_edgecolor,
+        s=markersize,
+        label=site_label,
+        zorder=101,
+        transform=transform_obj,
+    )
     # the orientation of the ellipse needs to be determined using the
     # two laws of cosines for spherical triangles where the triangle is
     # A: site, B: north pole, C: paleomagnetic pole (see Fig. A.2 of Butler)
@@ -2757,7 +2885,7 @@ def plot_pole_dp_dm(map_axis, plon, plat, slon, slat, dp, dm, pole_label='pole',
             C_deg = np.abs(np.rad2deg(C_rad))
 
     # print(C_deg)
-    ellipse(map_axis, plon, plat, dp_km, dm_km, C_deg, color=pole_color, transform=transform)
+    ellipse(map_axis, plon, plat, dp_km, dm_km, C_deg, color=pole_color, transform=transform_obj)
 
     if legend:
         plt.legend(loc=2)
@@ -3155,6 +3283,9 @@ def plot_distributions(ax, lon_samples, lat_samples, to_plot='d', resolution=100
         resolution: the resolution at which to plot the distributions
         kwargs: other keyword arguments inherited from matplotlib
     '''
+    if not has_cartopy:
+        print('-W- cartopy must be installed to run ipmag.plot_distributions')
+        return
     cmap=kwargs.get('cmap', 'viridis')
 
     artists = []
@@ -3511,7 +3642,7 @@ def combine_magic(filenames, outfile='measurements.txt', data_model=3, magic_tab
                 magic_table))
             return False
         # figure out file type from first of files to join
-        with open(filenames[0]) as f:
+        with open(filenames[0], encoding="utf-8") as f:
             file_type = f.readline().split()[1]
         if file_type in ['er_specimens', 'er_samples', 'er_sites',
                          'er_locations', 'er_ages', 'pmag_specimens',
@@ -4428,7 +4559,7 @@ def core_depthplot(input_dir_path='.', meas_file='measurements.txt', spc_file=''
     if sum_file:
         # os.path.join(input_dir_path, sum_file)
         sum_file = pmag.resolve_file_name(sum_file, input_dir_path)
-        with open(sum_file, 'r') as fin:
+        with open(sum_file, 'r', encoding="utf-8") as fin:
             indat = fin.readlines()
         if "Core Summary" in indat[0]:
             headline = 1
@@ -5203,7 +5334,7 @@ def download_magic_from_id(magic_id, directory='.', share_key=""):
 
     if response.status_code == 200 and response.text:
         # Write the content to the file only if the request was successful and the content is not empty
-        with open(out_path, 'w') as file:
+        with open(out_path, 'w', encoding="utf-8") as file:
             file.write(response.text)
         print("Download successful. File saved to:", out_path)
         return True, file_name
@@ -5245,7 +5376,7 @@ def download_magic_from_doi(doi):
         for filename in contribution_zip.namelist():
             if (re.match(r'^\d+\/magic_contribution_\d+\.txt', filename)):
                 contribution_text = io.TextIOWrapper(contribution_zip.open(filename)).read()
-                with open('magic_contribution.txt', 'wt') as fh:
+                with open('magic_contribution.txt', 'wt', encoding="utf-8") as fh:
                     fh.write(contribution_text)
                 print(filename, 'extracted to magic_contribution.txt', '\n')
                 return True, ""
@@ -5859,7 +5990,7 @@ def upload_to_private_contribution(contribution_id, upload_file,username="",pass
     response['method']='PUT'
     response['upload_file']=upload_file
     try:
-        with open(upload_file, 'rb') as f:
+        with open(upload_file, 'rb', encoding="utf-8") as f:
             upload_response = requests.put(api.format('private'),
                                           params={'id':contribution_id},
                                           auth=(username, password),
@@ -9685,6 +9816,194 @@ def find_compilation_kent(plon, plat, A95, slon, slat,
     if len(results) == 1:
         return results[0]
     return tuple(results)
+ 
+                              
+def find_svei_kent(
+    di_block,
+    site_latitude,
+    site_longitude,
+    f_low,
+    f_high,
+    kent_color="k",
+    n=1000,
+    save=False,
+    save_folder=".",
+    figprefix="SVEI",
+    fmt="svg",
+    return_poles=False,
+    return_kent_stats=True,
+    return_paleolats=False,
+    vgp_nb=100,
+    cmap="viridis_r",
+    central_longitude=0,
+    central_latitude=0,
+):
+    """
+    Uses a uniform distribution of flattening factors (f) derived from the SVEI analysis
+    of Tauxe et al. (2024) to correct inclination shallowing in sedimentary paleomagnetic
+    data and quantify uncertainty in the resulting mean pole using a Kent distribution.
+
+    The f values are sampled uniformly from a user-defined interval (`f_low`, `f_high`) 
+    that should be determined in advance using the `find_flat` function of the SVEI 
+    module (Tauxe et al., 2024), which identifies the range of flattening factors 
+    consistent with the THG24 geomagnetic field model.
+
+    For each sampled f, the directions are "unflattened" using the tangent transformation,
+    converted to VGPs, and resampled with a Fisher distribution. The resulting distribution
+    of mean poles is summarized with a Kent distribution. Plots of corrected directions,
+    paleolatitudes, and resampled poles are optionally generated and saved.
+
+    Parameters:
+        di_block : list or array-like (a di block)
+            Nested list or array of [dec, inc] or [dec, inc, intensity] directional data.
+        site_latitude : float
+            Latitude of the paleomagnetic sampling site.
+        site_longitude : float
+            Longitude of the paleomagnetic sampling site.
+        f_low : float
+            Lower bound for flattening factor, as determined from SVEI analysis (e.g. 0.51).
+        f_high : float
+            Upper bound for flattening factor, as determined from SVEI analysis (e.g. 0.89).
+        kent_color : str, optional
+            Color of the plotted Kent ellipse (default is 'k').
+        n : int, optional
+            Number of flattening factors to sample (default is 1000).
+        save : bool, optional
+            If True, saves figures to the specified folder (default is False).
+        save_folder : str, optional
+            Directory to save plots (default is current directory).
+        figprefix : str, optional
+            Prefix for saved figure filenames (default is 'SVEI').
+        fmt : str, optional
+            Format for saved figures (e.g., 'svg', 'png') (default is 'svg').
+        return_poles : bool, optional
+            If True, returns the resampled mean pole positions (default is False).
+        return_kent_stats : bool, optional
+            If True, returns the Kent distribution statistics (default is True).
+        return_paleolats : bool, optional
+            If True, returns the distribution of calculated paleolatitudes (default is False).
+        vgp_nb : int, optional
+            Number of Fisher resamples per unflattened mean pole (default is 100).
+        cmap : str, optional
+            Colormap used to indicate f value in directional plots (default is 'viridis_r').
+        central_longitude : float, optional
+            Central longitude of the orthographic projection (default is 0).
+        central_latitude : float, optional
+            Central latitude of the orthographic projection (default is 0).
+
+    Returns:
+        Depending on flags, returns one or more of:
+        - kent_stats : dict
+            Kent distribution parameters summarizing the resampled mean poles.
+        - mean_lons, mean_lats : list of float
+            Longitudes and latitudes of resampled mean poles.
+        - paleolats : list of float
+            Paleolatitudes calculated from resampled mean poles.
+
+    Notes:
+        This function assumes the user has previously run the SVEI `find_flat` function
+        (Tauxe et al., 2024) to determine the range of flattening factors (`f_low`, `f_high`)
+        that are consistent with the THG24 GGP model for the dataset under consideration.
+    """
+    f_resample = np.random.uniform(f_low,f_high,n)
+
+    plt.figure(figsize=(4,4))
+    plot_net()
+    cNorm  = colors.Normalize(vmin=min(f_resample), vmax=max(f_resample))
+    f_scalarMap = cm.ScalarMappable(norm=cNorm, cmap=cmap)
+        
+    di_lists = unpack_di_block(di_block)
+    if len(di_lists) == 3:
+        decs, incs, intensity = di_lists
+    if len(di_lists) == 2:
+        decs, incs = di_lists
+
+    mean_lons = []
+    mean_lats = []
+    paleolats=[]
+    
+    VGPs = pmag.dia_vgp(np.array([decs, incs, np.zeros(len(decs)), np.full(len(decs), site_latitude), np.full(len(decs),site_longitude)]).T)
+    VGPs_lons, VGPs_lats = VGPs[0], VGPs[1]
+    uncorrected_pole = fisher_mean(VGPs_lons, VGPs_lats)
+    plon = uncorrected_pole['dec'] 
+    plat = uncorrected_pole['inc']
+    A95 = uncorrected_pole['alpha95']
+    
+    for f in f_resample:
+        unsquish_incs = unsquish(incs, f)
+        #unsquish_mean_dir=fisher_mean(dec=decs,inc=unsquish_incs)
+        unsquish_VGPs = pmag.dia_vgp(np.array([decs, unsquish_incs, np.zeros(len(decs)), np.full(len(decs), site_latitude), np.full(len(decs),site_longitude)]).T)
+        unsquish_lons, unsquish_lats = unsquish_VGPs[0], unsquish_VGPs[1]
+        unsquish_VGPs_mean = fisher_mean(unsquish_lons, unsquish_lats)
+        resampled_lons, resampled_lats = fisher_mean_resample(alpha95=unsquish_VGPs_mean['alpha95'], n=vgp_nb, 
+                                                        dec=unsquish_VGPs_mean['dec'], inc=unsquish_VGPs_mean['inc'], di_block=0)
+        resampled_poles = np.column_stack((resampled_lons, resampled_lats))
+        N = resampled_poles.shape[0]  # Number of rows
+        site_array = np.tile([site_longitude,site_latitude], (N, 1))
+        mean_lons.extend(resampled_lons)
+        mean_lats.extend(resampled_lats)
+        plats = 90 - pmag.angle(resampled_poles, site_array)
+        paleolats.extend(plats.tolist())
+        rgba = f_scalarMap.to_rgba(f)
+        hex_color = colors.rgb2hex(rgba)
+        plot_di(decs, unsquish_incs, color = hex_color, alpha=0.02)
+    cb = plt.colorbar(f_scalarMap, ax=plt.gca(),orientation='horizontal',fraction=0.05, pad=0.05)
+    cb.ax.tick_params(labelsize=14)
+    cb.ax.set_title(label='$f$ values', fontsize=14)
+
+    if save:
+        plt.savefig(save_folder+'/'+figprefix+'_corrected_directions'+'.'+fmt, bbox_inches='tight', dpi=300)
+
+    plat_med=np.median(paleolats)
+    plat_lower, plat_upper = np.round(np.percentile(paleolats, [2.5, 97.5]), 1)
+    mu, std = stats.norm.fit(paleolats)
+    x = np.linspace(min(paleolats), max(paleolats), 100)
+    p = stats.norm.pdf(x, mu, std)
+
+    plt.figure(figsize=(4, 4))
+    plt.hist(paleolats, bins=15, alpha=0.6, density=1)
+    plt.plot(x, p, 'k', linewidth=1)
+
+    plt.axvline(x=plat_lower, color = 'gray', ls='--')
+    plt.axvline(x=plat_upper, color = 'gray', ls='--')
+
+    plt.title('%7.1f [%7.1f, %7.1f]' % (plat_med, plat_lower, plat_upper) + '\nFit result: mu='+str(round(mu,2))+'\nstd='+str(round(std, 2)), fontsize=14)
+    plt.xticks(fontsize=14)
+    plt.yticks(fontsize=14)
+    plt.xlabel(r'paleolatitude ($^\circ$)', fontsize=16)
+    plt.ylabel('density', fontsize=16)
+        
+    if save:
+         plt.savefig(save_folder+'/'+figprefix+'_paleolatitudes'+'.'+fmt, bbox_inches='tight', dpi=300)
+        
+    plt.show()
+            
+    # plot resampled mean poles
+    m = make_orthographic_map(central_longitude, central_latitude)
+    plot_vgp(m, mean_lons, mean_lats, color='lightgrey', edge='none', markersize=5, alpha=0.02)
+        
+    kent_stats = kent_distribution_95(dec=mean_lons,inc=mean_lats) 
+    print_kent_mean(kent_stats)
+    plot_pole_ellipse(m,kent_stats, color=kent_color,label="Kent mean pole")
+    plot_pole(m, plon, plat, A95, label="uncorrected pole position", color="C0")
+    plt.legend(loc=8, fontsize=14)
+    
+    if save:
+         plt.savefig(save_folder+'/'+figprefix+'_paleolatitudes'+'.'+fmt, bbox_inches='tight', dpi=300)
+ 
+    plt.show()
+
+    results = []
+    if return_kent_stats:
+        results.append(kent_stats)
+    if return_poles:
+        results.extend([mean_lons, mean_lats])
+    if return_paleolats:
+        results.append(paleolats)
+
+    if len(results) == 1:
+        return results[0]
+    return tuple(results)
 
 
 def pole_comparison_H2019(lon_1,lat_1,k_1,r_1,lon_2,lat_2,k_2,r_2):
@@ -15658,3 +15977,68 @@ def rand_correlation_prob(sec_var, delta1, delta2, alpha, trials=10000, print_re
         print ('The probability (average of P1 and P2) that directions represent random samples of the geomagnetic field is: {0:5.3f}'.format((prand1+prand2)/2))
     
     return rand_prob
+
+
+def MADcrit(N,alpha,niter=int(1E8)):
+    """
+    Estimate the MAD critical value at a given significance level to 
+    test a null hypothesis of random demagnetization behavior.
+    function from Heslop and Roberts, 2025, Establishing a Statistical Framework for Assessing Paleomagnetic Data Quality: A Significance Test Based on Maximum Angular Deviation doi: https://doi.org/10.1029/ 2025JB031417
+
+    Parameters
+    ----------
+    N : integer
+        Number of demagnetization points in the unanchored PCA fit.
+    alpha : float
+        Array of significance values for which the critical MAD values should be estimated.
+    niter: integer
+        Number of Monte Carlo iterations (default is 1E8).
+        Because α values of interest are in the lower tail of the MAD distribution, it is important to ensure that B is sufficiently large to sample the distribution extremes accurately.
+    Returns
+    -------
+    float
+        Array of estimated critical MAD values.
+
+    Examples
+    --------
+    >>> N = 10
+    >>> alpha = np.array([0.0001,0.001,0.01,0.05,0.1])
+    >>> MADcrit(N, alpha)
+    [19.5, 23.1, 27.6, 31.7, 33.9]
+    """
+    
+    df = N-1 #degrees of freedom of the Wishart distribution
+    X = wishart.rvs(df, scale=np.ones(3),size=niter) #Generate samples from the Wishart distribution
+    X = np.sort(np.linalg.eig(X)[0],axis=1) #find and sort the eigenvalues of each case
+    #find the MAD values and estimate critical values based on the percentiles corresponding to alpha
+    MAD_prc = np.nanpercentile(np.arctan(np.sqrt((X[:,0]+X[:,1])/X[:,2])),alpha*100) 
+    
+    return np.rad2deg(MAD_prc) #return critical values in degrees
+
+def MADcrit_95_filter(N, MAD):
+    '''
+    A convenience function to quickly filter for MADcrit values at the 95% significance level.
+    '''
+    if N < 3:
+        raise ValueError("N must be greater than 2 for MADcrit_95_filter")
+    if N > 50:
+        raise ValueError("N must be less than 51 for MADcrit_95_filter")
+    Ns = np.arange(3, 51)
+    MADcrit_95 = np.array([6.5, 14.8, 20.13, 23.8, 26.54, 28.64, 30.34,
+                            31.74, 32.93, 33.96, 34.86, 35.63,
+                            36.34, 36.95, 37.53, 38.04, 38.51,
+                            38.94, 39.34, 39.72, 40.08, 40.39,
+                            40.7, 40.99, 41.25, 41.51, 41.75,
+                            41.98, 42.18, 42.4, 42.6, 42.77,
+                            42.96, 43.13, 43.29, 43.44, 43.59,
+                            43.74, 43.87, 44.01, 44.14, 44.26,
+                            44.38, 44.5, 44.61, 44.72, 44.83,
+                            44.92])
+    MADcrit_table = pd.Series(MADcrit_95, index=Ns, name='MADcrit_95')
+    # compare a given MAD to the critical value for the given N
+    MADcrit = MADcrit_table.loc[N]
+
+    if MAD < MADcrit:
+        return True
+    else:
+        return False