Paper Title: "Thin-plate Splines on the Sphere for Interpolation, Computing Spherical Averages, and Solving Inverse Problems"
Paper link: https://www.ipol.im/pub/pre/451/
Version 1, January 9, 2023
Author: Max Dunitz (mdunitz@ens-paris-saclay.fr)

The contents of this directory (src) are as follows:

INFORMATIONAL:
readme.txt - this file
requirements.txt - list of requirements (useful for creating a virtual environment that matches the environment in which the code was written and tested)
license.txt - the license file for this demo

CODE FOR THE DEMO:
tps_min.py - the demo file

CODE FOR GENERATING PRECOMPUTED RESULTS:
GENERATE_INT_VALS.py - generates the file int_vals.npy
GENERATE_PLOG.py - generates the files plog3.npy and plog2.npy

PRECOMPUTED RESULTS:
plog3.npy - polylogarithms Li_3(z) precomputed at uniformly spaced points between -1 and 1, with 1e-8 separating the sample points (used to compute the spherical spline kernel)
plog2.npy - polylogarithms Li_2(z) precomputed at uniformly spaced points between -1 and 1, with 1e-8 separating the sample points (used to compute the spherical spline kernel)
int_vals.npy - precomputed integral values of ||x-x_i||*log||x-x_i|| for points x_i in [0,pi]x[0,2*pi], with x ranging over [0,pi]x[0,2*pi] and with 1e-3 separating the sample points in both axes (used to estimate the global mean of the Euclidean thin-plate spline interpolating surface)


This program may be run locally as follows:

(1) Install the requirements:
> pip install requirements.txt

(2) Move a single .csv or .png file you wish to analyze into this directory (src).

(3) Set environmental variables or replace them in the following terminal command the desired values. Then run the command:
> python3 tps_min.py -p $penalty -o $order -mila $minimum_latitude -mala $maximum_latitude -milo $minimum_longitude -malo $maximum_longitude

The variables are as follows:
'-o' (long name: '--order'): Spline order (either 2 or 3)
'-p' (long name: '--penalty'): log10 of the smoothing penalty (i.e., penalty is 10^{value chosen here}). Generally a value between roughly -5 and 0.
'-mila' (long name: '--minimum_latitude'): Minimum latitude (degrees) of output planisphere image. To output a full planisphere, use -90.
'-mala' (long name: '--maximum_latitude'): Maximum latitude (degrees) of output planisphere image. To output a full planisphere, use 90.
'-milo' (long name: '--minimum_longitude'): Minimum longitude of output planisphere image. To output a full planisphere, use -180.
'-malo' (long name: '--maximum_longitude'): Maximum longitude of output planisphere image. To output a full planisphere, use 180.
'-loc' (long name: '--location'):  Location of the folder src in which this file resides. Defaults to '..' if not given.

Note: There must be a data file in the directory. First, the demo searches for a .csv file. If it cannot find one, it searches for a .png file.

(4) The output files are saved in the local directory:
'data.png': Scattered data set, colored by observation values. The sample mean is displayed.
'interp_sphere.png': Samples of the spherical thin-plate spline interpolation surface at latitudes and longitudes uniformly spaced (on the plane after equirectangular projection) in the box [minimum_latitude, maximum_latitude]x[minimum_longitude, maximum_longitude]. The 200x400 image of the spline is given, along with its mean value over the sphere, extracted via the spline weight alpha_0.
'interp_plane.png': Samples of the planar thin-plate spline surface at latitudes and longitudes uniformly spaced (on the plane after equirectangular projection) in the box [minimum_latitude, maximum_latitude]x[minimum_longitude, maximum_longitude]. The 200x400 image of the spline is given, along with its mean value over the sphere, extracted via the spline weights and numerically integrating the representers of evaluation at each data point over [0,pi]x[0,2pi]. (The mean value diverges from reality when the Gram matrix is badly conditioned.)
'diff_sphere_plane.png': Pixelwise absolute difference between the interpolating surface splines at each sample point in the image.
'naturalcubicspline.png': The natural cubic spline fit to the scattered data, when plotted in one dimension against the sine of the latitude (not colatitude!). The mean value of this interpolating spline is also presented.
'reconstruction_err_sphere.png': Pixelwise absolute difference between the spherical TPS interpolating surface and the scattered data on which it was trained.
'reconstruction_err_plane.png': Pixelwise absolute difference between the planar TPS interpolating surface and the scattered data on which it was trained.

Finally, if the kernel Gram matrix is badly conditioned, a warning will be issued encouraging the user to increase the penalty.
