Package: deepsensor
A Python package and open-source project for modelling environmental
data with neural processesDeepSensor streamlines the application of neural processes (NPs) to environmental sciences by
providing a simple interface for building, training, and evaluating NPs usingxarrayandpandasdata. Our developers and users form an open-source community whose vision is to accelerate the next
generation of environmental ML research. The DeepSensor Python package facilitates this by
drastically reducing the time and effort required to apply NPs to environmental prediction tasks.
This allows DeepSensor users to focus on the science and rapidly iterate on ideas.DeepSensor is an experimental package, and we
welcomecontributions from the community.
We have an active Slack channel for code and research discussions; you can request to
joinvia this Google Form.Why neural processes?NPs are a highly flexible class of probabilistic models that offer unique opportunities to model
satellite observations, climate model output, and in-situ measurements.
Their key features are the ability to:ingest multiple data streams of pointwise or gridded modalitieshandle missing data and varying resolutionspredict at arbitrary target locationsquantify prediction uncertaintyThese capabilities make NPs well suited to a range of
spatio-temporal data fusion tasks such as downscaling, sensor placement, gap-filling, and forecasting.Why DeepSensor?This package aims to faithfully match the flexibility of NPs with a simple and intuitive interface.
Under the hood, DeepSensor wraps around the
powerfulneuralprocessesspackage for core modelling
functionality, while allowing users to stay in the familiarxarrayandpandasworld from end-to-end.
DeepSensor also provides convenient plotting tools and active learning functionality for finding
optimalsensor placements.DocumentationWe have an extensive documentation pagehere,
containing steps for getting started, a user guide built from reproducible Jupyter notebooks,
learning resources, research ideas, community information, an API reference, and more!DeepSensor GalleryFor real-world DeepSensor research demonstrators, check out theDeepSensor Gallery.
Consider submitting a notebook showcasing your research!Deep learning library agnosticismDeepSensor leverages thebackendspackage to be compatible with
eitherPyTorchorTensorFlow.
Simplyimport deepsensor.torchorimport deepsensor.tensorflowto choose between them!Quick startHere we will demonstrate a simple example of training a convolutional conditional neural process
(ConvCNP) to spatially interpolate random grid cells of NCEP reanalysis air temperature data
over the US. First, pip install the package. In this case we will use the PyTorch backend
(note: follow thePyTorch installation instructionsif you
want GPU support).pipinstalldeepsensor
pipinstalltorchWe can go from imports to predictions with a trained model in less than 30 lines of code!importdeepsensor.torchfromdeepsensor.dataimportDataProcessor,TaskLoaderfromdeepsensor.modelimportConvNPfromdeepsensor.trainimportTrainerimportxarrayasxrimportpandasaspdimportnumpyasnpfromtqdmimporttqdm# Load raw datads_raw=xr.tutorial.open_dataset("air_temperature")# Normalise datadata_processor=DataProcessor(x1_name="lat",x2_name="lon")ds=data_processor(ds_raw)# Set up task loadertask_loader=TaskLoader(context=ds,target=ds)# Set up modelmodel=ConvNP(data_processor,task_loader)# Generate training tasks with up 100 grid cells as context and all grid cells#   as targetstrain_tasks=[]fordateinpd.date_range("2013-01-01","2014-11-30")[::7]:N_context=np.random.randint(0,100)task=task_loader(date,context_sampling=N_context,target_sampling="all")train_tasks.append(task)# Train modeltrainer=Trainer(model,lr=5e-5)forepochintqdm(range(10)):batch_losses=trainer(train_tasks)# Predict on new task with 50 context points and a dense grid of target pointstest_task=task_loader("2014-12-31",context_sampling=50)pred=model.predict(test_task,X_t=ds_raw)After training, the model can predict directly toxarrayin your data's original units and
coordinate system:>>>pred["air"]<xarray.Dataset>Dimensions:(time:1,lat:25,lon:53)Coordinates:*time(time)datetime64[ns]2014-12-31*lat(lat)float3275.072.570.067.565.0...25.022.520.017.515.0*lon(lon)float32200.0202.5205.0207.5...322.5325.0327.5330.0Datavariables:mean(time,lat,lon)float32267.7267.2266.4...297.5297.8297.9std(time,lat,lon)float329.8559.8459.848...1.3561.361.487We can also predict directly topandascontaining a timeseries of predictions at off-grid
locations
by passing anumpyarray of target locations to theX_targument of.predict:# Predict at two off-grid locations over December 2014 with 50 random, fixed context pointstest_tasks=task_loader(pd.date_range("2014-12-01","2014-12-31"),50,seed_override=42)pred=model.predict(test_tasks,X_t=np.array([[50,280],[40,250]]).T)>>>pred["air"]meanstdtimelatlon2014-12-0150280260.2825625.74397640250270.7701114.2715462014-12-0250280255.5720986.16595640250277.5887453.7274042014-12-0350280260.8941966.02924.........2014-12-2940250266.5944214.2684692014-12-3050280250.9363867.04837940250262.2254644.6625922014-12-3150280249.3979197.16714240250257.9555054.697775[62rowsx2columns]DeepSensor offers far more functionality than this simple example demonstrates.
For more information on the package's capabilities, check out theUser Guidein the documentation.Citing DeepSensorIf you use DeepSensor in your research, please consider citing this repository.
You can generate a BiBTeX entry by clicking the 'Cite this repository' button
on the top right of this page.FundingDeepSensor is funded byThe Alan Turing Instituteunder theEnvironmental monitoring: blending satellite and surface dataandScivisionprojects, led by PIDr Scott Hosking.ContributorsWe appreciate all contributions to DeepSensor, big or small, code-related or not, and we thank all
contributors below for supporting open-source software and research.
For code-specific contributions, check out our graph ofcode contributions.
See ourcontribution guidelinesif you would like to join this list!Alejandro ©📓🐛🧑‍🏫🤔🔬Anna Vaughan🔬Jonas Scholz📓🔬💻🐛🤔Kalle Westerling📖🚇🤔📆📣💬Kenza Tazi🤔Magnus Ross✅🔣Nils Lehmann🤔📓🐛Paolo Pelucchi📓🐛Rohit Singh Rathaur💻Scott Hosking🔍🤔📆Tom Andersson💻🔬🚧🐛⚠️✅📖👀📢💬Wessel🔬💻🤔Zeel B Patel🐛💻📓🤔ots22🤔