pmagpy 4.2.115__py3-none-any.whl → 4.2.120__py3-none-any.whl

pmagpy/ipmag.py

@@ -381,6 +381,70 @@ def kent_distribution_95(dec=None, inc=None, di_block=None):
         return pmag.dokent(di_block, len(di_block), distribution_95=True)
     else:
         return pmag.dokent(di_block, len(di_block), distribution_95=True)
+    
+    
+def mean_bootstrap_confidence(dec=None,inc=None,di_block=None,num_sims=10000,alpha=0.05):
+    """
+    Estimates the bootstrap confidence region for the mean of a collection of paleomagnetic 
+    directions based on the approach of Heslop et al. (2023). This approach involves the projection
+    onto a tangent plane for a tractable statistical analysis in two dimensions.
+    
+    Parameters:
+        dec (list or None): List of declination values. Default is None.
+        inc (list or None): List of inclination values. Default is None.
+        di_block (list or None): List of [dec, inc] pairs. Default is None.
+            A di_block can be provided instead of dec, inc lists in which case it
+            will be used. Either dec, inc lists or a di_block needs to be provided.
+        num_sims (int): Number of bootstrap iterations. Default is 10,000.
+        alpha (float): Confidence region. Default is 0.05 corresponding to 95% region.
+    
+    Returns:
+        tuple: A tuple containing:
+                (1) a dictionary of parameters the includes the estimated mean 
+                direction and the T statistic which is the basis of the bootstrap confidence region, 
+                (2) list of [dec, inc] pairs that represent the boundary of the confidence region.
+                The bootstrap confidence region cannot be reported readily in a compact form so is
+                instead a long list of points along the boundary of the confidence region.
+               
+    References:
+        Heslop, D., Scealy, J. L., Wood, A. T. A., Tauxe, L., & Roberts, A. P. (2023). 
+        A bootstrap common mean direction test. Journal of Geophysical Research: Solid Earth, 128, e2023JB026983.
+        https://doi.org/10.1029/2023JB026983
+    """
+    
+    if di_block is None:
+        di_block = make_di_block(dec, inc)
+        
+    pars = {}
+    X = np.transpose(pmag.dir2cart(di_block))
+    n = np.shape(X)[1] #number of directions
+    mhat = np.mean(X,axis=1)
+    mhat /= np.linalg.norm(mhat) #estimate mean direction
+
+    mean_direction = pmag.cart2dir(mhat)
+    pars["dec"] = mean_direction[0]
+    pars["inc"] = mean_direction[1]
+
+    T_b = np.zeros(num_sims) #predefine output array for bootstrapped T values
+
+    for i in range(num_sims): #loop through bootstrap iterations
+        idx = np.random.randint(0,n,n) #select observation indicies with replacement
+        X_b = X[:,idx] #form bootstrap sample
+        mhat_b = np.mean(X_b,axis=1) #mean direction of bootstrap sample
+        mhat_b /= np.linalg.norm(mhat_b)
+        Mhat_b = pmag.form_Mhat(mhat_b) #\hat{M} for bootstrap sample
+        Ghat_b = pmag.form_Ghat(X_b,Mhat_b) #\hat{G} for bootstrap sample
+        T_b[i] = pmag.find_T(mhat,n,Mhat_b,Ghat_b) #T for bootstrap sample
+        
+    Tc = np.quantile(T_b,1-alpha) #find 1-alpha quantile of T
+    pars["T_critical"] = Tc
+
+    Mhat = pmag.form_Mhat(mhat)
+    Ghat = pmag.form_Ghat(X,Mhat)
+    Xc = pmag.find_CR(mhat,Mhat,Ghat,n,Tc) #calculate points along boundary of 95% confidence region
+    confidence_DI = pmag.cart2dir(np.transpose(Xc)) #convert to dec and inc for plotting 
+    
+    return pars, confidence_DI
 
 
 def print_direction_mean(mean_dictionary):
@@ -981,7 +1045,7 @@ def bootstrap_fold_test(Data, num_sims=1000, min_untilt=-10, max_untilt=120, bed
 def common_mean_bootstrap(Data1, Data2, NumSims=1000, 
                           color1='r', color2='b',
                           save=False, save_folder='.', fmt='svg', 
-                          figsize=(7, 2.3), x_tick_bins=4):
+                          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
@@ -1082,39 +1146,190 @@ def common_mean_bootstrap(Data1, Data2, NumSims=1000,
     plt.show()
     
     if ((x_overlap != 0) and (y_overlap != 0) and (z_overlap != 0)):
-        print('Pass')
+        if verbose:print('Pass')
         result = 1
         return result
     elif ((x_overlap == 0) and (y_overlap != 0) and (z_overlap != 0)):
-        print('Fail, distinct in x')
+        if verbose:print('Fail, distinct in x')
         result = 0
         return result
     elif ((x_overlap != 0) and (y_overlap == 0) and (z_overlap != 0)):
-        print('Fail, distinct in y')
+        if verbose:print('Fail, distinct in y')
         result = 0
         return result
     elif ((x_overlap != 0) and (y_overlap != 0) and (z_overlap == 0)):
-        print('Fail, distinct in z')
+        if verbose:print('Fail, distinct in z')
         result = 0
         return result
     elif ((x_overlap == 0) and (y_overlap == 0) and (z_overlap != 0)):
-        print('Fail, distinct in x and y')
+        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)):
-        print('Fail, distinct in x and z')
+        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)):
-        print('Fail, distinct in y and z')
+        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)):
-        print('Fail, distinct in x, y and z')
+        if verbose:print('Fail, distinct in x, y and z')
         result = 0
         return result
         
 
+def common_mean_bootstrap_H23(Data1, Data2, num_sims=10000, alpha=0.05, plot=True, reversal=False,
+                              save=False, save_folder='.', fmt='svg',verbose=False):
+    """
+    Perform a bootstrap common mean direction test following Heslop et al. (2023).
+
+    This function uses a nonparametric bootstrap approach to test the null hypothesis of common 
+    mean directions between two datasets. It extends the bootstrap common mean direction test of 
+    Tauxe et al. 1991 by incorporating a null hypothesis significance testing framework.
+
+    Parameters:
+        Data1 (array): Directional data of the first set; each row is [declination, inclination].
+        Data2 (array): Directional data of the second set; each row is [declination, inclination].
+        num_sims (int, optional): Number of bootstrap simulations to run. Default is 10000.
+        alpha (float, optional): Significance level for hypothesis testing. Default is 0.05.
+        plot (bool, optional): If True, produces a histogram plot of the test statistic. Default is True.
+        reversal (bool, optional): If True, considers antipodal directions for the second dataset. Default is False.
+        save (bool, optional): If True, saves the histogram plot. Default is False.
+        save_folder (str, optional): Directory where the histogram plot will be saved. Default is the current directory.
+        fmt (str, optional): File format for saving the histogram plot. Default is 'svg'.
+
+    Returns:
+        tuple: Contains the following elements:
+            - result (int): 0 if null hypothesis is rejected, 1 otherwise.
+            - Lmin (float): The test statistic value.
+            - Lmin_c (float): The critical test statistic value.
+            - p (float): The p-value of the test.
+
+    References:
+        Heslop, D., Scealy, J. L., Wood, A. T. A., Tauxe, L., & Roberts, A. P. (2023). 
+        A bootstrap common mean direction test. Journal of Geophysical Research: Solid Earth, 128, e2023JB026983.
+        https://doi.org/10.1029/2023JB026983
+    """
+    
+    X1 = np.transpose(pmag.dir2cart(Data1)) # normal directions in Cartesian coordinates (one direction per column)
+    
+    if reversal == True:
+        X2 = -np.transpose(pmag.dir2cart(Data2)) # inverted reversed directions in Cartesian coordinates
+    else:
+        X2 = np.transpose(pmag.dir2cart(Data2))
+
+    n1 = np.shape(X1)[1] #number of observations in first data set
+    n2 = np.shape(X2)[1] #number of observations in second data set
+    n = n1 + n2 #total number of observations
+
+    X12 = np.hstack((X1,X2)) #form pooled data set
+
+    mhat1 = np.mean(X1,axis=1)
+    mhat1 /= np.linalg.norm(mhat1) #mean of first data set
+
+    mhat2 = np.mean(X2,axis=1)
+    mhat2 /= np.linalg.norm(mhat2) #mean of second data set
+
+    mhat12 = np.mean(X12,axis=1)
+    mhat12 /= np.linalg.norm(mhat12) #mean of pooled data set
+
+    Mhat1 = pmag.form_Mhat(mhat1) #Mhat of first data set
+    Ghat1 = pmag.form_Ghat(X1,Mhat1) #Ghat of first data set
+
+    Mhat2 = pmag.form_Mhat(mhat2) #Mhat of second data set
+    Ghat2 = pmag.form_Ghat(X2,Mhat2) #Ghat of second data set
+
+    Ahat = Mhat1.getH()*np.linalg.inv(Ghat1)*Mhat1
+    Ahat += Mhat2.getH()*np.linalg.inv(Ghat2)*Mhat2
+    Ahat *= n
+
+    D,V = np.linalg.eig(Ahat)
+    idx = np.argmin(D)
+    Lmin = D[idx] #minimum eigenvalue
+    mhat0 = V[:,idx] #eigenvector corresponding to pooled sample mean
+
+    Q1 = pmag.form_Q(mhat0,mhat1) #rotation matrix for first data set
+    X10 = np.matmul(Q1,X1) #rotated version of first data set
+
+    Q2 = pmag.form_Q(mhat0,mhat2) #rotation matrix for second data set
+    X20 = np.matmul(Q2,X2) #rotated version of second data set
+
+    Lmin_b = np.zeros(num_sims) #predefine output array for minimum eigenvalues
+    T_b = np.zeros(num_sims) ##predefine output array for Tb (equation 11)
+
+    for i in range(num_sims): #loop through bootstrap iterations
+        idx1 = np.random.randint(0,n1,n1) #select observation indicies with replacement
+        X10_b = np.asarray(X10[:,idx1]) #form bootstrap sample from rotated version of first data set
+        
+        mhat10_b = np.mean(X10_b,axis=1) #mean direction of bootstrap sample
+        mhat10_b /= np.linalg.norm(mhat10_b)
+        mhat10_b = (np.asarray(mhat10_b)).flatten()
+        Mhat10_b = pmag.form_Mhat(mhat10_b) #\hat{M} for bootstrap sample
+        Ghat10_b = pmag.form_Ghat(X10_b,Mhat10_b) #\hat{G} for bootstrap sample
+        
+        idx2 = np.random.randint(0,n2,n2) #select observation indicies with replacement
+        X20_b = np.asarray(X20[:,idx2]) #form bootstrap sample from rotated version of second data set
+        
+        mhat20_b = np.mean(X20_b,axis=1) #mean direction of bootstrap sample
+        mhat20_b /= np.linalg.norm(mhat20_b)
+        mhat20_b = (np.asarray(mhat20_b)).flatten()
+        Mhat20_b = pmag.form_Mhat(mhat20_b) #\hat{M} for bootstrap sample
+        Ghat20_b = pmag.form_Ghat(X20_b,Mhat20_b) #\hat{G} for bootstrap sample
+        
+        Ahat_b = Mhat10_b.getH()*np.linalg.inv(Ghat10_b)*Mhat10_b #bootstrap estimate of \hat{A}_0 (equation 8)
+        Ahat_b += Mhat20_b.getH()*np.linalg.inv(Ghat20_b)*Mhat20_b
+        Ahat_b *= n
+        
+        D_b,V_b = np.linalg.eig(Ahat_b) #Eigenvalues and eigenvectors
+        Lmin_b[i] = np.min(D_b) #minimum eigenvalue for boostrap sample
+        T_b[i] = np.matmul(np.matmul(np.transpose(mhat0),Ahat_b),mhat0) #Bootstrap T for pooled data (equation 11)
+        
+    p = (1+np.sum(Lmin_b>=Lmin))/(num_sims+1) # p-value (step 8 of CMDT, Section 3)
+    # (n.b., if p > 0.05 cannot reject null of common means at alpha = 0.05)
+
+    Lmin_c = np.quantile(Lmin_b,1-alpha) #test critical value
+    # (n.b., if Lmin > Lmin_c reject null of common means at alpha significance level)
+
+    if verbose: print("Heslop et al. (2023) test statistic value = {:.2f}".format(Lmin))
+    if verbose: print("Heslop et al. (2023) critical test statistic value = {:.2f}".format(Lmin_c))
+    if verbose: print("Estimated p-value = {:.2f}".format(p))
+    if p < alpha:
+        if verbose:print("Reject null of common means at alpha = {:.2f} confidence level".format(alpha))
+        result = 0
+    else:
+        if verbose:print("Cannot reject null of common means at alpha = {:.2f} confidence level".format(alpha))
+        result = 1
+        
+    if plot==True:
+        fig=plt.figure()
+        ax1=fig.add_subplot(111)
+        plt.hist(Lmin_b,bins=int(np.sqrt(num_sims)),color = "0.6", ec="0.6");
+        #axes = plt.gca()
+        y_min, y_max = ax1.get_ylim()
+        plt.plot([Lmin,Lmin],[y_min,y_max],'--r',label='Test statistic:')
+        plt.plot([Lmin_c,Lmin_c],[y_min,y_max],'-k',label='Critical value')
+        if y_max<Lmin:y_max=Lmin+5
+        plt.ylim([y_min,y_max])
+        plt.xlim(np.min(Lmin_b),np.max(Lmin_b)+10)
+        plt.xlabel(r'$\lambda_{\rm{min}}^{(b)}$')
+        plt.ylabel('Frequency')
+        plt.minorticks_on()
+        plt.rcParams.update({'font.size': 12})
+        plt.legend(loc='upper right')
+        if result==0:
+            plt.text(.8,.7,'Fail',color='red',transform=ax1.transAxes)
+        else:
+            plt.text(.8,.7,'Pass',color='blue',transform=ax1.transAxes)
+
+        if save == True:
+            plt.savefig(os.path.join(
+                save_folder, 'bootstrap_test_histogram') + '.' + fmt)
+        plt.show()
+        
+    return result, Lmin, Lmin_c, p
+
+
 def common_mean_watson(Data1, Data2, NumSims=5000, print_result=True, plot='no', save=False, save_folder='.', fmt='svg'):
     """
     Conduct a Watson V test for a common mean on two directional data sets.
@@ -1365,9 +1580,49 @@ def common_mean_bayes(Data1, Data2, reversal_test=False):
     return BF0, P, support
 
 
+def separate_directions(dec=None, inc=None, di_block=None):
+    """
+    Separates directional data into two modes based on the principal direction.
+
+    Parameters:
+        dec (list, optional): List of declinations. Defaults to None.
+        inc (list, optional): List of inclinations. Defaults to None.
+        di_block (list of lists, optional): Nested list of [dec,inc]. Can be provided 
+            instead of separate dec, inc lists. If provided, it takes precedence.
+
+    Returns:
+        tuple: Depending on input, either:
+            - dec1, inc1, dec2, inc2: Lists of declinations and inclinations for the 
+              two modes (if separate dec, inc lists are provided)
+            - polarity1, polarity2: Nested lists of [dec,inc] for the two modes (if 
+              di_block is provided)
+    """
+    if di_block is None:
+        di_block = make_di_block(dec, inc, unit_vector=False)
+    
+    polarity1, polarity2 = pmag.separate_directions(di_block)
+    
+    if dec is not None and inc is not None:
+        if len(polarity1) > 0 :
+            dec1 = polarity1[:, 0].tolist()
+            inc1 = polarity1[:, 1].tolist()
+        else:
+            dec1 = None
+            inc1 = None
+        if len(polarity2) > 0 :
+            dec2 = polarity2[:, 0].tolist()
+            inc2 = polarity2[:, 1].tolist()
+        else:
+            dec2 = None
+            inc2 = None
+        return dec1, inc1, dec2, inc2
+    else:
+        return make_di_block(dec1, inc1), make_di_block(dec2, inc2)
+    
+
 def reversal_test_bootstrap(dec=None, inc=None, di_block=None, plot_stereo=False,
                             color1='blue', color2='red',
-                            save=False, save_folder='.', fmt='svg'):
+                            save=False, save_folder='.', fmt='svg',verbose=True):
     """
     Conduct a reversal test using bootstrap statistics (Tauxe, 2010) to
     determine whether two populations of directions could be from an antipodal
@@ -1424,11 +1679,50 @@ def reversal_test_bootstrap(dec=None, inc=None, di_block=None, plot_stereo=False
 
     result = common_mean_bootstrap(directions1, directions2,
                                    color1=color1, color2=color2,
-                                   save=save, save_folder=save_folder, fmt=fmt)
+                                   save=save, save_folder=save_folder, fmt=fmt,verbose=True)
     
     return result
 
 
+def reversal_test_bootstrap_H23(dec=None, inc=None, di_block=None, num_sims=10000, alpha=0.05, plot=True,
+                          save=False, save_folder='.', fmt='svg',verbose=True):
+    """
+    Bootstrap reversal test following Heslop et al. (2023).
+
+    This function calls common_mean_bootstrap_H23 with directional data that have been flipped, 
+    for a reversal test. The directional data can be provided either as separate 
+    declination and inclination arrays or as a di_block array.
+
+    Parameters:
+        dec (array): Array of declinations, only considered if di_block is None.
+        inc (array): Array of inclinations, only considered if di_block is None.
+        di_block (array, optional): Directional data as [dec, inc] for each sample. If provided, 
+                                    dec and inc are ignored.
+        num_sims (int, optional): Number of bootstrap simulations. Default is 1000.
+        alpha (float, optional): Significance level for hypothesis testing. Default is 0.05.
+        plot (bool, optional): If True, produce a histogram plot of the test statistic. Default is True.
+        save (bool, optional): If True, save the histogram plot. Default is False.
+        save_folder (str, optional): Directory where the histogram plot will be saved. Default is the current directory.
+        fmt (str, optional): File format for saving the histogram plot. Default is 'svg'.
+
+    Returns:
+        tuple: Contains the following elements:
+            - result (int): 0 if null hypothesis is rejected, 1 otherwise.
+            - Lmin (float): The test statistic value.
+            - Lmin_c (float): The critical test statistic value.
+            - p (float): The p-value of the test.
+    """
+    if di_block is None:
+        all_dirs = make_di_block(dec, inc)
+    else:
+        all_dirs = di_block
+
+    F1, F2 = pmag.flip(all_dirs)
+    
+    return common_mean_bootstrap_H23(F1, F2, num_sims=num_sims, alpha=alpha, plot=plot,
+                                     save=save, save_folder=save_folder, fmt=fmt,verbose=verbose)
+
+
 def reversal_test_MM1990(dec=None, inc=None, di_block=None, plot_CDF=False, 
                          plot_stereo=False, save=False, save_folder='.', fmt='svg'):
     """
@@ -1441,29 +1735,22 @@ def reversal_test_MM1990(dec=None, inc=None, di_block=None, plot_CDF=False,
     the data into two polarities using the pmag.flip() function and flipping
     the reverse direction to their antipode.
 
-    Parameters:
-        dec: list of declinations
-        inc: list of inclinations
-            or
-        di_block: a nested list of [dec,inc]
-            *A di_block can be provided in which case it will be used instead of
-            dec, inc lists.*
+     Parameters:
+        dec (list, optional): List of declinations.
+        inc (list, optional): List of inclinations.
+        di_block (list of lists, optional): Nested list of [dec,inc]. If provided, it 
+            takes precedence over separate dec and inc lists.
+        plot_CDF (bool, optional): If True, plot the CDF accompanying the results. Defaults to False.
+        plot_stereo (bool, optional): If True, plot stereonet with bidirectionally separated data. Defaults to False.
+        save (bool, optional): If True, save the plots. Defaults to False.
+        save_folder (str, optional): Directory path for saving plots. Defaults to current directory.
+        fmt (str, optional): Format of saved figures. Defaults to 'svg'.
 
-        plot_CDF : plot the CDF accompanying the printed results (default is False)
-        plot_stereo : plot stereonet with the bidirectionally separated data
-            (default is False)
-        save : boolean argument to save plots (default is False)
-        save_folder : relative directory where plots will be saved
-            (default is current directory, '.')
-        fmt : format of saved figures (default is 'svg')
-    
     Returns:
-        **printed text** (text describing the test result is printed), 
-        **result** (a boolean where 0 is fail and 1 is pass),
-        **angle** (angle between the Fisher means of the two data sets),
-        **critical_angle** (critical angle for the test to pass),
-        **classification** (MM1990 classification for a positive test).
-        Plots are shown if plot parameters are set to True.
+        result (bool): 0 indicates fail, 1 indicates pass.
+        angle (float): Angle between the Fisher means of the two data sets.
+        critical_angle (float): Critical angle for the test to pass.
+        classification (str): MM1990 classification for a positive test.
 
     Examples:
         Populations of roughly antipodal directions are developed here using
@@ -2018,6 +2305,38 @@ def plot_di_mean_ellipse(dictionary, fignum=1, color='k', marker='o', markersize
     pmagplotlib.plot_ell(fignum, pars, color, 0, 1)
 
 
+def plot_bootstrap_confidence(mean_dec, mean_inc, confidence_DI, 
+                              mean_color='k', confidence_color='k', 
+                              mean_marker='o', confidence_marker='.', 
+                              mean_markersize=20, confidence_markersize=1):
+    """
+    Plot mean and bootstrap confidence outline on an equal area plot. The input confidence_DI
+    is the output from the mean_bootstrap_confidence() function.
+
+    Before this function is called a plot needs to be initialized with code that looks
+    something like:
+    >fignum = 1
+    >plt.figure(num=fignum,figsize=(10,10),dpi=160)
+    >ipmag.plot_net(fignum)
+
+    Parameters:
+        mean_dec: Declination of the mean point.
+        mean_inc: Inclination of the mean point.
+        confidence_DI: A nested list of [dec, inc, 1.0] representing the bootstrap confidence.
+        mean_color: Color of the mean point. Default is black.
+        confidence_color: Color of the confidence points. Default is black.
+        mean_marker: Marker style for the mean point. Default is 'o' (circle).
+        confidence_marker: Marker style for the confidence points. Default is 'o' (circle).
+        mean_markersize: Marker size for the mean point. Default is 20.
+        confidence_markersize: Marker size for the confidence points. Default is 1.
+    """
+    plot_di(dec=mean_dec, inc=mean_inc, color=mean_color, marker=mean_marker, 
+            markersize=mean_markersize)
+    plot_di(di_block=confidence_DI, color=confidence_color, marker=confidence_marker, 
+            markersize=confidence_markersize)
+
+
+
 def make_orthographic_map(central_longitude=0, central_latitude=0, figsize=(8, 8),
                           add_land=True, land_color='tan', land_edge_color='black',
                           add_ocean=False, ocean_color='lightblue', grid_lines=True,
@@ -2610,7 +2929,9 @@ def plot_vgp_basemap(mapname, vgp_lon=None, vgp_lat=None, di_block=None, label='
         plt.legend(loc=2)
 
 
-def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='site_lat', dec_is='dec_is', inc_is='inc_is', dec_tc='dec_tc', inc_tc='inc_tc'):
+def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='site_lat', 
+             dec_is='dec_is', inc_is='inc_is', dec_tc='dec_tc', inc_tc='inc_tc',
+             recalc_label=False):
     """
     This function calculates paleomagnetic poles using directional data and site
     location data within a pandas.DataFrame. The function adds the columns
@@ -2638,6 +2959,17 @@ def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='si
     dataframe['vgp_lat_rev']
     dataframe['vgp_lon_rev']
     """
+    if recalc_label:
+        vgp_lat_name = 'vgp_lat_recalc'
+        vgp_lon_name = 'vgp_lon_recalc'
+        vgp_lat_rev_name = 'vgp_lat_rev_recalc'
+        vgp_lon_rev_name = 'vgp_lon_rev_recalc'
+    else:
+        vgp_lat_name = 'vgp_lat'
+        vgp_lon_name = 'vgp_lon'
+        vgp_lat_rev_name = 'vgp_lat_rev'
+        vgp_lon_rev_name = 'vgp_lon_rev'
+    
     dataframe.is_copy = False
     if tilt_correction == 'yes':
         # calculate the paleolatitude/colatitude
@@ -2645,7 +2977,7 @@ def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='si
             np.arctan(0.5 * np.tan(np.radians(dataframe[inc_tc]))))
         dataframe['colatitude'] = 90 - dataframe['paleolatitude']
         # calculate the latitude of the pole
-        dataframe['vgp_lat'] = np.degrees(np.arcsin(np.sin(np.radians(dataframe[site_lat])) *
+        dataframe[vgp_lat_name] = np.degrees(np.arcsin(np.sin(np.radians(dataframe[site_lat])) *
                                                     np.cos(np.radians(dataframe['colatitude'])) +
                                                     np.cos(np.radians(dataframe[site_lat])) *
                                                     np.sin(np.radians(dataframe['colatitude'])) *
@@ -2654,17 +2986,17 @@ def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='si
         # (beta)
         dataframe['beta'] = np.degrees(np.arcsin((np.sin(np.radians(dataframe['colatitude'])) *
                                                           np.sin(np.radians(dataframe[dec_tc])))/
-                                                         (np.cos(np.radians(dataframe['vgp_lat'])))))
+                                                         (np.cos(np.radians(dataframe[vgp_lat_name])))))
         # generate a boolean array (mask) to use to distinguish between the two possibilities for pole longitude
         # and then calculate pole longitude using the site location and
         # calculated beta
         mask = np.cos(np.radians(dataframe['colatitude'])) > np.sin(
-            np.radians(dataframe[site_lat])) * np.sin(np.radians(dataframe['vgp_lat']))
-        dataframe['vgp_lon'] = np.where(mask, (dataframe[site_lon] + dataframe['beta']) %
+            np.radians(dataframe[site_lat])) * np.sin(np.radians(dataframe[vgp_lat_name]))
+        dataframe[vgp_lon_name] = np.where(mask, (dataframe[site_lon] + dataframe['beta']) %
                                         360., (dataframe[site_lon] + 180 - dataframe['beta']) % 360.)
         # calculate the antipode of the poles
-        dataframe['vgp_lat_rev'] = -dataframe['vgp_lat']
-        dataframe['vgp_lon_rev'] = (dataframe['vgp_lon'] - 180.) % 360.
+        dataframe[vgp_lat_rev_name] = -dataframe[vgp_lat_name]
+        dataframe[vgp_lon_rev_name] = (dataframe[vgp_lon_name] - 180.) % 360.
         # the 'colatitude' and 'beta' columns were created for the purposes of the pole calculations
         # but aren't of further use and are deleted
         del dataframe['colatitude']
@@ -2675,7 +3007,7 @@ def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='si
             np.arctan(0.5 * np.tan(np.radians(dataframe[inc_is]))))
         dataframe['colatitude'] = 90 - dataframe['paleolatitude']
         # calculate the latitude of the pole
-        dataframe['vgp_lat'] = np.degrees(np.arcsin(np.sin(np.radians(dataframe[site_lat])) *
+        dataframe[vgp_lat_name] = np.degrees(np.arcsin(np.sin(np.radians(dataframe[site_lat])) *
                                                     np.cos(np.radians(dataframe['colatitude'])) +
                                                     np.cos(np.radians(dataframe[site_lat])) *
                                                     np.sin(np.radians(dataframe['colatitude'])) *
@@ -2684,21 +3016,22 @@ def vgp_calc(dataframe, tilt_correction='yes', site_lon='site_lon', site_lat='si
         # (beta)
         dataframe['beta'] = np.degrees(np.arcsin((np.sin(np.radians(dataframe['colatitude'])) *
                                                           np.sin(np.radians(dataframe[dec_is])))/
-                                                         (np.cos(np.radians(dataframe['vgp_lat'])))))
+                                                         (np.cos(np.radians(dataframe[vgp_lat_name])))))
         # generate a boolean array (mask) to use to distinguish between the two possibilities for pole longitude
         # and then calculate pole longitude using the site location and
         # calculated beta
         mask = np.cos(np.radians(dataframe['colatitude'])) > np.sin(
-            np.radians(dataframe[site_lat])) * np.sin(np.radians(dataframe['vgp_lat']))
-        dataframe['vgp_lon'] = np.where(mask, (dataframe[site_lon] + dataframe['beta']) %
+            np.radians(dataframe[site_lat])) * np.sin(np.radians(dataframe[vgp_lat_name]))
+        dataframe[vgp_lon_name] = np.where(mask, (dataframe[site_lon] + dataframe['beta']) %
                                         360., (dataframe[site_lon] + 180 - dataframe['beta']) % 360.)
         # calculate the antipode of the poles
-        dataframe['vgp_lat_rev'] = -dataframe['vgp_lat']
-        dataframe['vgp_lon_rev'] = (dataframe['vgp_lon'] - 180.) % 360.
+        dataframe[vgp_lat_rev_name] = -dataframe[vgp_lat_name]
+        dataframe[vgp_lon_rev_name] = (dataframe[vgp_lon_name] - 180.) % 360.
         # the 'colatitude' and 'beta' columns were created for the purposes of the pole calculations
         # but aren't of further use and are deleted
         del dataframe['colatitude']
         del dataframe['beta']
+            
     return(dataframe)
 
 
@@ -4646,13 +4979,53 @@ def core_depthplot(input_dir_path='.', meas_file='measurements.txt', spc_file=''
     plt.title(location)
     return main_plot, figname
 
+def unpack_magic(infile=None, dir_path='.', input_dir_path='',
+                    overwrite=False, print_progress=True,
+                    data_model=3., separate_locs=False, txt="",excel=False):
+    """
+    Wrapper function for ipmag.download_magic, to handle the unpacking of a MagIC contribution.
+    
+    This function takes in a text file, typically downloaded from the MagIC database, 
+    and then unpacks it into MagIC-formatted files. The name emphasizes the "unpacking" 
+    nature of the operation over the "downloading" aspect.
+
+    Parameters:
+        infile : str, optional
+            Name of the MagIC-format file to unpack.
+        dir_path : str, optional
+            Directory path for output. Default is the current directory.
+        input_dir_path : str, optional
+            Path to the input file if different from dir_path. Default is dir_path.
+        overwrite : bool, optional
+            Whether to overwrite files in the current directory. Default is False.
+        print_progress : bool, optional
+            Whether to print progress messages. Default is True.
+        data_model : float, optional
+            Specifies the MagIC data model version, either 2.5 or 3. Default is 3.
+        separate_locs : bool, optional
+            If True, create separate directories for each location. Default is False.
+        txt : str, optional
+            Alternative to providing an infile, you can provide the file contents as a string.
+            Useful for directly downloading a MagIC file from EarthRef. Default is an empty string.
+        excel : bool, optional
+            If True, the input file is treated as an Excel spreadsheet. Default is False.
+
+    Returns:
+        bool
+            True if the unpacking operation is successful. False otherwise.
+    """
+
+    return download_magic(infile, dir_path, input_dir_path,
+                    overwrite, print_progress,
+                    data_model, separate_locs, txt, excel)
+
 
 def download_magic(infile=None, dir_path='.', input_dir_path='',
                    overwrite=False, print_progress=True,
                    data_model=3., separate_locs=False, txt="",excel=False):
     """
-    takes the name of a text file downloaded from the MagIC database and
-    unpacks it into magic-formatted files. by default, download_magic assumes
+    Takes the name of a text file downloaded from the MagIC database and
+    unpacks it into MagIC-formatted files. by default, download_magic assumes
     that you are doing everything in your current directory. if not, you may
     provide optional arguments dir_path (where you want the results to go) and
     input_dir_path (where the downloaded file is IF that location is different from
@@ -4680,6 +5053,10 @@ def download_magic(infile=None, dir_path='.', input_dir_path='',
         excel : bool
             input file is an excel spreadsheet (as downloaded from MagIC)
 
+    Returns:
+        bool
+            True if the unpacking operation is successful. False otherwise.
+
     """
     if data_model == 2.5:
         method_col = "magic_method_codes"
@@ -4742,12 +5119,26 @@ def download_magic(infile=None, dir_path='.', input_dir_path='',
         if line == ">>>>>>>>>>":
             LN += 1
             continue
-        keys = line.replace('\n', '').split('\t')
+
+        # detect MagIC compact format
+        magic_compact_title_lines = {}
+
+        while File[LN][0] == "*": # this means there are measurements made in MagIC compact format
+            this_title_line = File[LN].replace('\n', '').replace('*', '').split('\t')
+            magic_compact_title_lines[this_title_line[0]] = this_title_line[1]
+            LN += 1
+
+        # make key line detection specific
+        key_line = File[LN]
+        keys = key_line.replace('\n', '').split('\t')
+
         if keys[0][0] == '.':
             keys = line.replace('\n', '').replace('.', '').split('\t')
             keys.append('RecNo')  # cludge for new MagIC download format
-        LN += 1
+        
         Recs = []
+        LN += 1
+        
         while LN < len(File):
             line = File[LN]
             # finish up one file type and then break
@@ -4776,6 +5167,9 @@ def download_magic(infile=None, dir_path='.', input_dir_path='',
             else:
                 rec = line.split('\t')
                 Rec = {}
+                if len(magic_compact_title_lines)>0:
+                        for title in list(magic_compact_title_lines.keys()):
+                            Rec[title] = magic_compact_title_lines[title]
                 if len(rec) == len(keys):
                     for k in range(len(rec)):
                         Rec[keys[k]] = rec[k]
@@ -4855,33 +5249,49 @@ def download_magic(infile=None, dir_path='.', input_dir_path='',
     return True
 
 
-def download_magic_from_id(con_id):
+def download_magic_from_id(magic_id, directory='.',share_key=""):
     """
-    Download a public contribution matching the provided
-    contribution ID from earthref.org/MagIC.
+    Downloads a contribution from earthref.org/MagIC using the provided ID.
+    and saves it to the directory. If the directory does not exist, it's created.
+    
+    If a share_key is provided, downloads a private contribution
 
-    Parameters:
-        doi : str
-            DOI for a MagIC
+    Args:
+        magic_id (str): Unique ID for a MagIC contribution.
+        directory (str, optional): Path to save the file. Defaults to current directory.
+        share_key (str): share key for downloading from Private Contribution, Default is "" for public contribution
 
     Returns:
-        result : bool
-        message : str
-            Error message if download didn't succeed
+        bool: True if successful, False otherwise.
+        str: Local file path if successful or error message if failed.
     """
-    try:
-        magic_url = 'https://earthref.org/MagIC/download/{}/magic_contribution_{}.txt'.format(con_id, con_id)
-        res = wget.download(magic_url)
-    except NameError:
-        return False, "wget module is not available, cannot download from MagIC"
-    except urllib.error.HTTPError:
-        return False, "Looks like you didn't provide a valid contribution id, please try again..."
-    except urllib.error.URLError:
-        return False, "Couldn't connect to MagIC site, please check your internet connection"
-    except Exception as ex:
-        print('Unexpected problem downloading from MagIC:', str(ex), type(ex))
+    api = 'https://api.earthref.org/v1/MagIC/{}'
+    # Ensure the directory exists
+    if not os.path.exists(directory): os.makedirs(directory)
+    magic_contribution='magic_contribution_'+magic_id+'.txt'
+    out_path = os.path.join(directory, 'magic_contribution_{}.txt'.format(magic_id))
+    if not os.path.exists(out_path): 
+        f=open(directory+magic_contribution,'x')
+    if share_key!="":
+        contribution = requests.get(api.format('data'), params={'id': magic_id,'key':share_key})
+        f=open(directory+magic_contribution,'w')
+        f.write(contribution.text) 
+        f.close()
+        return True, magic_contribution
+    else:
+        try:
+            magic_url = 'https://earthref.org/MagIC/download/{}/magic_contribution_{}.txt'.format(con_id, con_id)
+            res = wget.download(magic_url, out=out_path)
+            return True, res
+        except NameError:
+            return False, "wget module is not available, cannot download from MagIC"
+        except urllib.error.HTTPError:
+            return False, "Looks like you didn't provide a valid contribution id, please try again..."
+        except urllib.error.URLError:
+            return False, "Couldn't connect to MagIC site, please check your internet connection"
+        except Exception as ex:
+            print('Unexpected problem downloading from MagIC:', str(ex), type(ex))
         return False, str(ex)
-    return True, res
 
 
 def download_magic_from_doi(doi):
@@ -8876,7 +9286,6 @@ def find_ei(data, nb=1000, save=False, save_folder='.', fmt='svg',
 
     upper, lower = int(round(.975 * nb)), int(round(.025 * nb))
     E, I = [], []
-
     plt.figure(num=1, figsize=(4, 4))
     plot_net(1)
     plot_di(di_block=data, color=data_color)
@@ -8916,8 +9325,7 @@ def find_ei(data, nb=1000, save=False, save_folder='.', fmt='svg',
             else:
                 I.append(abs(Isb[-1]))
                 E.append(Esb[-1])
-            b += 1
-
+        b += 1
     I.sort()
     E.sort()
     if tight_axes:
@@ -8927,9 +9335,12 @@ def find_ei(data, nb=1000, save=False, save_folder='.', fmt='svg',
     for i in I:
         Eexp.append(pmag.EI(i))
     plt.plot(I, Eexp, 'k')
+    #print (lower,upper)#DEBUG
+    #print (len(I))#DEBUG
     if Inc == 0:
         title = 'Pathological Distribution: ' + \
             '[%7.1f, %7.1f]' % (I[lower], I[upper])
+        title = 'Pathological Distribution: ' 
     else:
         title = '%7.1f [%7.1f, %7.1f]' % (Inc, I[lower], I[upper])
     if save: