autoFRK 1.1.0

autoFRK: Automatic Fixed Rank Kriging. The Python version with PyTorch

autoFRK-python

• Repository: https://github.com/Josh-test-lab/autoFRK-python

autoFRK-python is a Python implementation of the R package autoFRK v1.4.3 (Tzeng S et al., 2021). autoFRK provides a Resolution Adaptive Fixed Rank Kriging (FRK) approach for handling regular and irregular spatial data, reducing computational cost through multi-resolution basis functions.

Features

• Spatial modeling based on multi-resolution basis functions
• Supports single or multiple time points
• Offers approximate or EM-based model estimation
• Suitable for global latitude-longitude data
• Implemented in PyTorch, supporting CPU and GPU (requires PyTorch with CUDA support for GPU)

Installation

Install via pip:

pip install autoFRK

Install directly from GitHub:

pip install git+https://github.com/Josh-test-lab/autoFRK-python.git

Or clone and install manually:

git clone https://github.com/Josh-test-lab/autoFRK-python.git
cd autoFRK-python
pip install .

Usage

1. Import and Initialize

import torch
from autoFRK import AutoFRK

# Initialize the autoFRK model
model = AutoFRK(dtype=torch.float64, device="cpu")

2. Model Fitting

# Assume `data` is (n, T) observations and `loc` is (n, d) spatial coordinates
data = torch.randn(100, 1)  # Example data
loc = torch.rand(100, 2)    # Example 2D coordinates

result = model.forward(
    data=data,
    loc=loc,
    maxit=50,
    tolerance=1e-6,
    method="fast",          # "fast" or "EM"
    n_neighbor=3,
    maxK=50,
    calculate_with_spherical=False
)

print(result.keys())
# ['M', 's', 'negloglik', 'w', 'V', 'G', 'LKobj', 'calculate_with_spherical']

forward() returns a dictionary including:

• M: Covariance matrix of random effects
• s: Measurement error variance
• negloglik: Final negative log-likelihood
• w: Estimated random effects for each time point
• V: Prediction error covariance of w
• G: Basis function matrix used

3. Predicting New Data

# Assume `newloc` contains new spatial coordinates
newloc = torch.rand(20, 2)

pred = model.predict(
    obj=result,
    newloc=newloc,
    se_report=True
)

print(pred['pred.value'].shape)  # Predicted values
print(pred.get('se'))            # Standard errors

predict() can optionally return standard errors (se_report=True). If obj is not provided, the most recent forward() result is used.

Advanced Settings

forward() supports various parameters:

Parameter	Description	Default
mu	Mean value (scalar or tensor)	0.0
D	Measurement error covariance	None (identity matrix used)
G	Basis function matrix (optional)	None (TPS basis auto-generated)
finescale	Include fine-scale process η[t]	False
maxit	Maximum iterations	50
tolerance	Convergence tolerance	1e-6
maxK	Maximum number of basis functions	Auto-set based on n
method	Model estimation method	"fast"
n_neighbor	Number of neighbors for fast method	3
calculate_with_spherical	Use spherical distance calculation	False

Example Code

import torch
from autoFRK import AutoFRK

# Generate fake data
n, T = 200, 1
data = torch.randn(n, T)
loc = torch.rand(n, 2)

# Initialize model
model = AutoFRK(device="cpu")

# Fit model
res = model.forward(
    data=data,
    loc=loc,
    maxit=100,
    method="fast"
)

# Predict new data
newloc = torch.rand(10, 2)
pred = model.predict(obj=res, newloc=newloc, se_report=True)

print("Predicted values:", pred['pred.value'])
print("Prediction standard errors:", pred.get('se'))

Experimental Features

• Spherical coordinate basis function computation
• Gradient tracking (torch's requires_grad_()).

Authors

• ShengLi Tzeng — Original Paper Author
• Hsin-Cheng Huang — Original Paper Author
• Wen-Ting Wang — R Package Author
• Yao-Chih Hsu — Python Package Author
• Yi-Xuan Xie — Python Package Tester
• Xuan-Chun Wang — Python Package Tester

License

• GPL (>= 3)

Development and Contribution

• Built with PyTorch, supporting GPU acceleration
• Report bugs or request features on GitHub issues

References

• Tzeng S, Huang H, Wang W, Nychka D, Gillespie C (2021). autoFRK: Automatic Fixed Rank Kriging. R package version 1.4.3, https://CRAN.R-project.org/package=autoFRK
• Wang, J. W.-T. (n.d.). autoFRK. GitHub. Retrieved January 7, 2023, from https://egpivo.github.io/autoFRK/
• Tzeng, S. & Huang, H.-C. (2018). Resolution Adaptive Fixed Rank Kriging. Technometrics. https://doi.org/10.1080/00401706.2017.1345701
• Nychka, D., Hammerling, D., Sain, S., & Lenssen, N. (2016). LatticeKrig: Multiresolution Kriging Based on Markov Random Fields

Citation

• To cite the Python package autoFRK-python in publications use:

  Yao-Chih Hsu (2025). _autoFRK-python: Automatic Fixed Rank Kriging. The Python version with PyTorch_. Python package version 1.0.0, 
  <https://github.com/Josh-test-lab/autoFRK-python>.

• A BibTeX entry for LaTeX users is:

  @Manual{,
    title = {autoFRK-python: Automatic Fixed Rank Kriging. The Python version with PyTorch},
    author = {Yao-Chih Hsu},
    year = {2025},
    note = {Python package version 1.0.0},
    url = {https://github.com/Josh-test-lab/autoFRK-python},
  }

• To cite the original R package autoFRK:

  Tzeng S, Huang H, Wang W, Nychka D, Gillespie C (2021). _autoFRK: Automatic Fixed Rank Kriging_. R package version 1.4.3,
  <https://CRAN.R-project.org/package=autoFRK>.

• A BibTeX entry for the original R package is:

  @Manual{,
    title = {autoFRK: Automatic Fixed Rank Kriging},
    author = {ShengLi Tzeng and Hsin-Cheng Huang and Wen-Ting Wang and Douglas Nychka and Colin Gillespie},
    year = {2021},
    note = {R package version 1.4.3},
    url = {https://CRAN.R-project.org/package=autoFRK},
  }

Release Notes

v1.1.0

• Added dtype and device parameters to AutoFRK.predict() and MRTS.predict().
• Added logger_level parameter to AutoFRK.__init__() and MRTS.__init__() (default: 20). Options include NOTSET(0), DEBUG(10), INFO(20), WARNING(30), ERROR(40), CRITICAL(50).
• Enhanced automatic device selection, including MPS support.
• Fixed device assignment issue when device is not specified, preventing redundant parameter transfers.

v1.0.0

• Ported R package autoFRK to Python.