⚠️ Design-phase package. nat.python is being extracted from fafbseg and is not yet ready for general use. The API is unstable and may change without notice. See
nat.python-plan.mdfor the full design, scope and migration plan.
nat.python is a small shared layer of library-agnostic Python interoperability helpers built on reticulate. It holds only the code that does not care which Python library you are talking to:
-
introspection — which modules are installed and at what version (
py_module_info(),py_module_info2(),module_version(),module_available()); -
conversion — turn generic Python return values into idiomatic R:
pandas2df()(pandasDataFrame→ R data frame, preserving 64-bit ids, object columns and datetimes),ts2pydatetime(),null2na(); -
id bridging — 64-bit integer ids between R (
bit64), numpy and raw bytes (pyids2bit64(),rids2pyint(),rids2raw(),int64_overflows()).
It contains no knowledge of any specific Python package (cloudvolume, caveclient, seatable_api, navis, …) or scientific domain. Packages such as fafbseg, bancr and seatabler depend on nat.python and supply that specificity themselves.
The name follows the nat* family (nat, nat.utils, nat.nblast) — read it as “nat + Python interop”. It is unrelated to the PyPI package natpy.
Status
This repository currently implements Phase 1 of the plan: the module introspection, pandas/numpy → R conversion, and large-integer bridging code, lifted out of fafbseg. The Python environment engine (the mechanics under simple_python) and the diagnostic py_report() are Phase 2 and not yet here. See nat.python-plan.md.
Installation
# install.packages("remotes")
remotes::install_github("flyconnectome/nat.python")nat.python does not manage Python environments itself (yet — see the plan). It uses whatever interpreter reticulate resolves. The conversion functions need numpy and pandas in that environment; the use_arrow = TRUE path additionally needs the R arrow package.
Usage
library(nat.python)
# What is installed?
module_version("pandas")
py_module_info(c("numpy", "pandas"))
# Convert a pandas DataFrame, keeping 64-bit ids exact
pd <- reticulate::import("pandas")
df <- pd$DataFrame(list(id = c("720575940621039145", "720575940626877799")))
pandas2df(df)