sofm 0.1.4__tar.gz

sofm-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 daniel-s-cunha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sofm-0.1.4/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: sofm
+Version: 0.1.4
+Summary: Spatially Orthogonal Factor Model (SOFM)
+Author-email: Dan Cunha <dcunha@bu.edu>
+License: MIT
+Project-URL: Homepage, https://github.com/daniel-s-cunha/SOFM
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scikit-sparse>=0.4.12
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: seaborn>=0.12.0
+Requires-Dist: sympy>=1.12.0
+Requires-Dist: threadpoolctl>=3.2.0
+Requires-Dist: torch>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: xarray>=2023.5.0
+Requires-Dist: xeofs>=2.0.0
+Dynamic: license-file
+
+# SOFM
+Spatially orthogonal factor models
+
+## Installation
+
+Please install `scikit-sparse` via conda before installing this package:
+
+```bash
+conda install -c conda-forge scikit-sparse
+pip install sofm
+```
+
+## Data
+Please use the `spatialLIBD_to_netcdf.R` script to download the DLPFC data from R and save as a netcdf file to be imported into xarray.
+
+## Code example
+```
+from sofm import SOFM
+
+# 1. Load netcdf into xarray
+# Please see `spatialLIBD_to_netcdf.R` for directions on formatting the netcdf file.
+da = xr.open_dataset("/data_directory/spatial_transcriptomic_data.nc", engine='netcdf4')['logcounts']
+
+da = da - da.mean(dim='spot') #SOFM assumes the mean structure has been subtracted
+da = da.rename({ #SOFM assumes `da` has `location` dimension indexed by `lat,lon` coordinates
+    'spot': 'location', 
+    'array_col': 'lon', 
+    'array_row': 'lat'
+})
+da = da.set_index(location=['lat', 'lon'])
+
+# 2. Initialize SOFM model
+sofm_model = SOFM(
+    data=da, 
+    n_components=5, 
+    n_cores=-1 #please set number of cores
+)
+
+# 3. Fit model
+sofm_model.fit()
+
+# 4. Visualize spatial loadings
+fig = sofm_model.plot_loadings(robust=True)
+fig.show()
+
+# 5. Analyze latent factors
+latent_factors = sofm_model.Ez_
+```
+
+If helpful, try out the code using a synthetic dataset,
+```
+import numpy as np
+import xarray as xr
+from sofm import SOFM
+
+# 1. Generate Synthetic Data
+# Create a 30x30 spatial grid
+lats, lons = np.meshgrid(np.linspace(-5, 5, 30), np.linspace(-5, 5, 30))
+lat_flat = lats.flatten()
+lon_flat = lons.flatten()
+n_locations = len(lat_flat)
+n_features = 20
+
+factor1 = np.sin(lat_flat) + np.cos(lon_flat)      
+factor2 = np.exp(-(lat_flat**2 + lon_flat**2) / 2) 
+factor3 = lat_flat + lon_flat                      
+Z = np.column_stack([factor1, factor2, factor3])
+
+np.random.seed(42)
+W = np.random.randn(3, n_features) # Synthetic loadings
+data_matrix = Z @ W + np.random.randn(n_locations, n_features) * 0.5
+
+da = xr.DataArray(
+    data_matrix,
+    dims=['location', 'feature'],
+    coords={
+        'lat': ('location', lat_flat),
+        'lon': ('location', lon_flat),
+        'feature': np.arange(n_features)
+    }
+)
+da = da.set_index(location=['lat', 'lon'])
+da = da - da.mean(dim='location')
+
+# 2. Initialize SOFM model
+sofm_model = SOFM(
+    data=da, 
+    n_components=3, 
+    n_cores=-1 #please set number of cores
+)
+
+# 3. Fit model
+sofm_model.fit()
+
+# 4. Visualize spatial loadings
+fig = sofm_model.plot_loadings(robust=True)
+fig.show()
+
+# 5. Analyze latent factors
+latent_factors = sofm_model.Ez_
+```

sofm-0.1.4/README.md

@@ -0,0 +1,101 @@
+# SOFM
+Spatially orthogonal factor models
+
+## Installation
+
+Please install `scikit-sparse` via conda before installing this package:
+
+```bash
+conda install -c conda-forge scikit-sparse
+pip install sofm
+```
+
+## Data
+Please use the `spatialLIBD_to_netcdf.R` script to download the DLPFC data from R and save as a netcdf file to be imported into xarray.
+
+## Code example
+```
+from sofm import SOFM
+
+# 1. Load netcdf into xarray
+# Please see `spatialLIBD_to_netcdf.R` for directions on formatting the netcdf file.
+da = xr.open_dataset("/data_directory/spatial_transcriptomic_data.nc", engine='netcdf4')['logcounts']
+
+da = da - da.mean(dim='spot') #SOFM assumes the mean structure has been subtracted
+da = da.rename({ #SOFM assumes `da` has `location` dimension indexed by `lat,lon` coordinates
+    'spot': 'location', 
+    'array_col': 'lon', 
+    'array_row': 'lat'
+})
+da = da.set_index(location=['lat', 'lon'])
+
+# 2. Initialize SOFM model
+sofm_model = SOFM(
+    data=da, 
+    n_components=5, 
+    n_cores=-1 #please set number of cores
+)
+
+# 3. Fit model
+sofm_model.fit()
+
+# 4. Visualize spatial loadings
+fig = sofm_model.plot_loadings(robust=True)
+fig.show()
+
+# 5. Analyze latent factors
+latent_factors = sofm_model.Ez_
+```
+
+If helpful, try out the code using a synthetic dataset,
+```
+import numpy as np
+import xarray as xr
+from sofm import SOFM
+
+# 1. Generate Synthetic Data
+# Create a 30x30 spatial grid
+lats, lons = np.meshgrid(np.linspace(-5, 5, 30), np.linspace(-5, 5, 30))
+lat_flat = lats.flatten()
+lon_flat = lons.flatten()
+n_locations = len(lat_flat)
+n_features = 20
+
+factor1 = np.sin(lat_flat) + np.cos(lon_flat)      
+factor2 = np.exp(-(lat_flat**2 + lon_flat**2) / 2) 
+factor3 = lat_flat + lon_flat                      
+Z = np.column_stack([factor1, factor2, factor3])
+
+np.random.seed(42)
+W = np.random.randn(3, n_features) # Synthetic loadings
+data_matrix = Z @ W + np.random.randn(n_locations, n_features) * 0.5
+
+da = xr.DataArray(
+    data_matrix,
+    dims=['location', 'feature'],
+    coords={
+        'lat': ('location', lat_flat),
+        'lon': ('location', lon_flat),
+        'feature': np.arange(n_features)
+    }
+)
+da = da.set_index(location=['lat', 'lon'])
+da = da - da.mean(dim='location')
+
+# 2. Initialize SOFM model
+sofm_model = SOFM(
+    data=da, 
+    n_components=3, 
+    n_cores=-1 #please set number of cores
+)
+
+# 3. Fit model
+sofm_model.fit()
+
+# 4. Visualize spatial loadings
+fig = sofm_model.plot_loadings(robust=True)
+fig.show()
+
+# 5. Analyze latent factors
+latent_factors = sofm_model.Ez_
+```

sofm-0.1.4/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sofm"
+version = "0.1.4"
+description = "Spatially Orthogonal Factor Model (SOFM)"
+readme = "README.md"
+authors = [
+    { name = "Dan Cunha", email = "dcunha@bu.edu" }
+]
+license = { text = "MIT" }
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "joblib>=1.3.0",
+    "matplotlib>=3.7.0",
+    "numpy>=1.24.0",
+    "pandas>=2.0.0",
+    "scikit-learn>=1.3.0",
+    "scikit-sparse>=0.4.12",
+    "scipy>=1.10.0",
+    "seaborn>=0.12.0",
+    "sympy>=1.12.0",
+    "threadpoolctl>=3.2.0",
+    "torch>=2.0.0",
+    "tqdm>=4.65.0",
+    "xarray>=2023.5.0",
+    "xeofs>=2.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/daniel-s-cunha/SOFM"

sofm-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sofm-0.1.4/src/scov.py

@@ -0,0 +1,309 @@
+from matplotlib.patches import Ellipse
+import matplotlib.cm as cm
+import time 
+from joblib import Parallel, delayed
+import itertools
+import matplotlib.pyplot as plt
+import xarray as xr
+import numpy as np
+from numpy.linalg import svd
+import torch
+import torch.nn.functional as F
+import torch.optim as optim
+import pandas as pd
+from sklearn.utils.extmath import randomized_svd
+# import rioxarray as rxr
+# from rasterio import CRS
+import scipy.spatial
+from scipy.spatial import cKDTree
+from scipy.linalg import solve
+import scipy.sparse as sp
+from scipy.interpolate import BSpline
+from sklearn.cluster import KMeans
+from sksparse.cholmod import cholesky
+#
+import utils
+from tqdm import tqdm
+from threadpoolctl import threadpool_limits
+
+class SpatialCovariance:
+
+	def __init__(self, data, nonstationary=True, n_components = 1, max_lag=30, block_sz = 5, n_blocks = 20, n_cores = -1):
+		self.data = self._standardize_input(data).compute()
+		self.nonstationary = nonstationary
+		self.max_lag = max_lag
+		self.block_sz = block_sz
+		self.n_blocks = n_blocks
+		self.n_components = n_components
+		self.n_cores = n_cores
+		#
+		self.holdout_ = None
+		self.holdout_centers_ = None
+		self.holdout_ids_ = None
+		self.spatcov_ = None
+		self.alpha_lat_ = None 
+		self.alpha_lon_ = None 
+		self.alpha_rot_ = None
+		self.t_u_ = None
+		self.t_v_ = None
+		self.lam_lat_ = None
+		self.lam_lon_ = None
+		self.sill_ = None
+		self.ls1_ = None
+		self.ls2_ = None
+		#
+		self.generate_holdout()
+
+	def _standardize_input(self, data):
+		if not isinstance(data, (xr.DataArray, xr.Dataset)):
+			raise TypeError("Input must be an xarray DataArray or Dataset.")
+		
+		if 'location' in data.dims and not isinstance(data.indexes.get('location'), pd.MultiIndex):
+			if 'lat' in data.coords and 'lon' in data.coords:
+				return data.set_index(location=['lat', 'lon'])
+
+		if 'lat' in data.dims and 'lon' in data.dims:
+			return data.stack(location=['lat', 'lon'])
+
+		if 'location' in data.dims and isinstance(data.indexes.get('location'), pd.MultiIndex):
+			return data
+		    
+		raise ValueError("Data must contain 'lat' and 'lon' coordinates or dimensions.")
+
+	def generate_holdout(self):
+		#
+		self.holdout_, self.holdout_ids_, self.holdout_centers_ = utils._create_mask(self.data,n_blocks=self.n_blocks,block_sz=self.block_sz)
+		#
+		#return self
+	
+	def plot_holdout(self):
+		M_da = xr.DataArray(
+		    data=(self.holdout_!=0).numpy().astype(float),
+		    dims=('location'),
+		    coords={
+			        'location': self.data.location
+		    }
+		)
+		M_da = M_da.unstack()
+		M_da = M_da.sortby(['lon','lat'])
+		M_da.plot(add_colorbar=False)
+		plt.show()
+
+	def plot_nonstationary_spatcov(self, invert=True, robust=False):
+		if not self.nonstationary:
+			raise ValueError(
+				"This plot can only be used when nonstationary=True. "
+				"The current model is initialized as stationary."
+			)
+
+		if not hasattr(self, 'lam_lat_'):
+			raise ValueError("plot_nonstationary_spatcov can only be used after .fit() is completed.")
+
+		# --- Data Preparation ---
+		def prep_da(data):
+			da = xr.DataArray(data=data, dims=('location'), coords={'location': self.data.location})
+			return da.unstack().sortby('lon', 'lat')
+
+		W_da = prep_da(self.lam_lat_)
+		W_da2 = prep_da(self.lam_lon_)
+		W_da3 = prep_da(self.rot_)
+		
+		ar = np.maximum(self.lam_lat_, self.lam_lon_) / (np.minimum(self.lam_lat_, self.lam_lon_) + 1e-8)
+		W_da4 = prep_da(ar)
+
+		# --- Plotting Configuration ---
+		title_size = 24
+		label_size = 14
+		fig, axes = plt.subplots(1, 2, figsize=(12, 6)) # Slightly larger fig for larger text
+		
+		# Helper to apply labels consistently
+		def format_ax(ax, title, is_first=False):
+			ax.set_title(title, fontsize=title_size, pad=10)
+			ax.set_xlabel('', fontsize=label_size)
+			ax.set_ylabel('' if is_first else '', fontsize=label_size)
+			# Increase tick label size
+			ax.tick_params(labelsize=10)
+
+		# 1. Latitudinal
+		W_da.plot(ax=axes[0], cmap=cm.plasma, robust=robust, #vmin=3, vmax=5, 
+					add_colorbar=True, cbar_kwargs={'format': '%.1f'})
+		format_ax(axes[0], 'Latitudinal length scale', is_first=True)
+		
+		# 2. Longitudinal
+		W_da2.plot(ax=axes[1], cmap=cm.plasma, robust=robust,#vmin=3, vmax=5, 
+					add_colorbar=True, cbar_kwargs={'format': '%.1f'})
+		format_ax(axes[1], 'Longitudinal length scale')
+		
+		# # 3. Rotation
+		# W_da3.plot(ax=axes[2], cmap=cm.plasma, vmin=0,  robust=True,
+		# 			add_colorbar=True, cbar_kwargs={'format': '%.2f'})
+		# format_ax(axes[2], 'Rotation')
+		
+		# # 4. Anisotropy
+		# W_da4.plot(ax=axes[2], cmap=cm.plasma, add_colorbar=True, robust=True,
+		# 			cbar_kwargs={'format': '%.1f'})
+		# format_ax(axes[2], 'Anisotropy ratio')
+		if invert:
+			for ax in axes:
+				ax.invert_yaxis()
+		plt.tight_layout()
+		return fig
+
+	def _evaluate_ls(self, ls1, ls2, rot, init_phi):
+		Sigma = utils._compute_spat_cov_rs(
+			self.data, 
+			phi=init_phi, 
+			length_scale=ls1, 
+			length_scale2=ls2, 
+			rot = rot,
+			max_lag=self.max_lag
+		)        
+		U, L, Ez, sigma2, loss, loss_tot = utils._cv_spatPCA(
+			self.data, 
+			Sigma, 
+			self.holdout_, 
+			k=self.n_components, 
+			phi=init_phi
+		)
+		if self.nonstationary:
+			return (ls1, ls2, rot, loss)
+		else:
+			return (ls1, ls2, rot, loss_tot)
+
+	def _evaluate_phi(self, phi):
+		Sigma = utils._compute_spat_cov_rs(
+			self.data, 
+			phi=1, 
+			length_scale=1,
+			max_lag=self.max_lag
+		)        
+		#
+		U, L, Ez, sigma2, loss, loss_tot = utils._cv_spatPCA(
+			self.data, 
+			phi*Sigma, 
+			self.holdout_, 
+			k=self.n_components, 
+			phi=phi
+		)
+		
+		return (phi, loss_tot)
+
+	def _evaluate_phi_post(self, phi):
+		Sigma = self.spatcov_
+		#
+		U, L, Ez, sigma2, loss, loss_tot = utils._cv_spatPCA(
+			self.data, 
+			phi*Sigma, 
+			self.holdout_, 
+			k=self.n_components, 
+			phi=phi
+		)
+		
+		return (phi, loss_tot)
+
+	def fit(self, lss=[1,3,5,7], phis=[1e3,5e3,1e4,5e4], rots=[0, 1*np.pi/16, 2*np.pi/16, 3*np.pi/16]):
+		#
+		if self.nonstationary:
+			self._fit_nonstationary(lss, phis, rots)
+		else:
+			self._fit_stationary(lss, phis)
+			
+	def _fit_nonstationary(self, lss, phis, rots):
+		#
+		#
+		#fit best phi for fixed ls
+		#		
+		if len(phis)>1:
+			results = list(tqdm(
+				Parallel(n_jobs=self.n_cores, return_as="generator")(
+					delayed(self._evaluate_phi)(phi) 
+					for phi in phis
+				),
+				total = len(phis),
+				desc = 'Validating sill'
+			))
+			#
+			self.sill_, _ = min(results, key=lambda x: x[1])
+		else:
+			self.sill_ = phis[0]
+		#
+		print(f'The prior sill estimate is {self.sill_}')
+		n_centers = len(self.holdout_ids_)
+		#
+		# k_1d = np.sqrt(n_centers)
+		# opt_knots = int(max(3, np.round(k_1d - 2)))
+		#
+		#fit best lss
+		ls_combinations = list(itertools.product(lss, lss, rots))
+		init_phi = self.sill_
+		#
+		results = list(tqdm(
+			Parallel(n_jobs=self.n_cores, return_as='generator')(
+				delayed(self._evaluate_ls)(ls1, ls2, rot, init_phi) 
+				for ls1, ls2, rot in ls_combinations
+			), 
+			total=len(ls_combinations),
+			desc='Validating length scales'
+		))
+
+		res_dict = {(res[0], res[1], res[2]): res[3] for res in results}
+		loss_df = pd.DataFrame(res_dict)
+
+		loss_df.index = self.holdout_ids_
+
+		minimizer = loss_df.idxmin(axis=1).rename('ls_hat')
+		
+		centers_df = pd.DataFrame(
+			self.holdout_centers_,
+			index=self.holdout_ids_,
+			columns=['mean_lat', 'mean_lon']
+		)
+		
+		final_results = pd.concat([centers_df, minimizer], axis=1).dropna()
+		
+		self.minimizer_ = np.column_stack([
+			np.array(final_results['ls_hat'].tolist()),
+			final_results['mean_lat'].values,
+			final_results['mean_lon'].values
+		])
+		print("Fitting spline to the optimal length scales...")
+		self.alpha_lat_, self.alpha_lon_, self.alpha_rot_, self.t_u_, self.t_v_ = utils._fit_spline(self.data,self.minimizer_)
+		#fit with variance=1 so you only have to run it once and can instead adjust it by multiplying phi
+		self.spatcov_, self.lam_lat_, self.lam_lon_, self.rot_ = utils._construct_nonstat_cov(self.data.lat.values, self.data.lon.values, self.alpha_lat_, self.alpha_lon_, self.alpha_rot_, self.t_u_, self.t_v_, variance=1, max_lag=self.max_lag)
+		#
+		#
+		self.spatcov_ = self.sill_ * self.spatcov_
+
+	def _fit_stationary(self, lss, phis):
+		#
+		#fit best ls for fixed init_phi
+		#
+		ls_combinations = list(itertools.product(lss, lss))
+		init_phi = 1e4
+		
+		results = list(tqdm(
+			Parallel(n_jobs=self.n_cores, return_as='generator')(
+				delayed(self._evaluate_ls)(ls1, ls2, [0], init_phi) 
+				for ls1, ls2 in ls_combinations
+			),
+			total = len(ls_combinations),
+			desc = 'Validating length scales'
+		))
+		
+		self.ls1_, self.ls2_, _, _ = min(results, key=lambda x: x[2])
+		self.spatcov_ = utils._compute_spat_cov_rs(self.data, 1, self.ls1_, self.ls2_, max_lag=self.max_lag)
+		#
+		#fit best phi for fixed ls
+		#		
+		results = list(tqdm(
+			Parallel(n_jobs=self.n_cores,return_as='generator')(
+				delayed(self._evaluate_phi)(phi) 
+				for phi in phis
+			),
+			total = len(phis),
+			desc = 'Validating sill'
+		))
+
+		self.sill_, _ = min(results, key=lambda x: x[1])
+		self.spatcov_ = self.sill_ * self.spatcov_
+