docs: 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'):
      """
      This function calculates paleomagnetic poles using directional data and site
      location data within a pandas.DataFrame. The function adds the columns
      'paleolatitude', 'vgp_lat', 'vgp_lon', 'vgp_lat_rev', and 'vgp_lon_rev'
      to the dataframe. The '_rev' columns allow for subsequent choice as to which
      polarity will be used for the VGPs.
  
      Parameters
      -----------
      dataframe : the name of the pandas.DataFrame containing the data
      tilt-correction : 'yes' is the default and uses tilt-corrected data (dec_tc, inc_tc), 'no' uses data that is not tilt-corrected and is in geographic coordinates
      dataframe['site_lat'] : the name of the Dataframe column containing the latitude of the site
      dataframe['site_lon'] : the name of the Dataframe column containing the longitude of the site
      dataframe['inc_tc'] : the name of the Dataframe column containing the tilt-corrected inclination (used by default tilt-correction='yes')
      dataframe['dec_tc'] : the name of the Dataframe column containing the tilt-corrected declination (used by default tilt-correction='yes')
      dataframe['inc_is'] : the name of the Dataframe column containing the insitu inclination (used when tilt-correction='no')
      dataframe['dec_is'] : the name of the Dataframe column containing the insitu declination (used when tilt-correction='no')
  
      Returns
      -------
      dataframe['paleolatitude']
      dataframe['colatitude']
      dataframe['vgp_lat']
      dataframe['vgp_lon']
      dataframe['vgp_lat_rev']
      dataframe['vgp_lon_rev']
      """
      dataframe.is_copy = False
      if tilt_correction == 'yes':
          # calculate the paleolatitude/colatitude
          dataframe['paleolatitude'] = np.degrees(
              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])) *
                                                      np.cos(np.radians(dataframe['colatitude'])) +
                                                      np.cos(np.radians(dataframe[site_lat])) *
                                                      np.sin(np.radians(dataframe['colatitude'])) *
                                                      np.cos(np.radians(dataframe[dec_tc]))))
          # calculate the longitudinal difference between the pole and the site
          # (beta)
          dataframe['beta'] = np.degrees(np.arcsin(old_div((np.sin(np.radians(dataframe['colatitude'])) *
                                                            np.sin(np.radians(dataframe[dec_tc]))),
                                                           (np.cos(np.radians(dataframe['vgp_lat']))))))
          # 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']) %
                                          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.
          # 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']
      if tilt_correction == 'no':
          # calculate the paleolatitude/colatitude
          dataframe['paleolatitude'] = np.degrees(
              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])) *
                                                      np.cos(np.radians(dataframe['colatitude'])) +
                                                      np.cos(np.radians(dataframe[site_lat])) *
                                                      np.sin(np.radians(dataframe['colatitude'])) *
                                                      np.cos(np.radians(dataframe[dec_is]))))
          # calculate the longitudinal difference between the pole and the site
          # (beta)
          dataframe['beta'] = np.degrees(np.arcsin(old_div((np.sin(np.radians(dataframe['colatitude'])) *
                                                            np.sin(np.radians(dataframe[dec_is]))),
                                                           (np.cos(np.radians(dataframe['vgp_lat']))))))
          # 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']) %
                                          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.
          # 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)