GeoEco.SpatialAnalysis.Interpolation.Interpolator.InterpolateTimeSeriesOfArcGISRastersValuesAtPoints

classmethod Interpolator.InterpolateTimeSeriesOfArcGISRastersValuesAtPoints(points, tField, valueField, workspace, rasterNameExpressions, tCornerCoordType, tIncrement, tIncrementUnit, tSemiRegularity=None, tCountPerSemiRegularPeriod=None, method='Automatic', where=None, noDataValue=None, rastersWrap=False, orderByFields=None, numBlocksToCacheInMemory=256, xBlockSize=128, yBlockSize=128, tBlockSize=1)

Interpolates values of a time series of rasters at a time series of points.

Given points that have a date field and a workspace containing a time series of rasters with dates in their file names, this tool matches the points to the rasters by date, interpolates values of the rasters at the points, and stores the result in a field of the points. To be used with this tool, the rasters must meet several constraints:

The rasters must all have the same coordinate system, spatial extent, cell size, number of rows and columns, data type, and NoData value.
There must only be one raster for any given date.
The rasters must occur at a regular time step (e.g. one per day). Many “level 3” and “level 4” gridded remote sensing products conform to this requirement. For example, level 3 NASA MODIS products are often published at daily, 8-day, monthly, and yearly averages. Most “level 1” and “level 2” products do not conform to this requirement. Those products usually have irregular time spacing between each image. This tool cannot currently handle such products.
It is OK for rasters to be missing from the time series. For example, if the rasters are from a satellite remote sensor that failed for a time, and no images were published during that period, it is OK for those rasters to not exist. The tool will detect this, report a warning, and assume that the values of those rasters were NoData.

Requires: ArcGIS Pro 3.2.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.2.0 or later, Python numpy module, Python bindings for the Geospatial Data Abstraction Library (GDAL).

Parameters:

points (str) –
Feature class or layer containing the points at which values should be interpolated. The points must have a field that contains the date of each point and a field to receive the value interpolated from the raster.

It is recommended but not required that the points and rasters use the same coordinate system. If they do not, this tool will attempt to project the points to the coordinate system of the rasters prior to doing the interpolation. This may fail if a datum transformation is required, in which case you will have to manually project the points and rasters to the same coordinate system before using this tool. Minimum length꞉ 1. Must exist.
tField (str) – Field of the points that specifies the date and time of the point. The field must have a datetime data type. If the field can only represent dates with no time component, the time will assumed to be 00:00:00. Minimum length꞉ 1. Must exist.
valueField (str) – Field of the points to receive the interpolated values. The field must have a floating-point or integer data type. If the field cannot represent the interpolated value at full precision, the closest approximation will be stored and a warning will be issued. This will happen, for example, when you interpolate floating-point values into an integer field. Minimum length꞉ 1. Must exist.
workspace (str) – Directory or geodatabase containing the time series of rasters. If the workspace is a directory, the rasters may be stored all at the root level or they may be nested in a tree that may be multiple levels deep. rasterNameExpressions must reflect the tree structure. Minimum length꞉ 1.

rasterNameExpressions (list of str) –

List of regular expressions specifying how the rasters are named. If the raster workspace is a geodatabase, the list should have just one entry corresponding to the raster name. If the raster workspace is a directory, the list should have one entry for each subdirectory level plus an entry for the file name. If all of the rasters are contained at the root level, there should only be the single entry for the file name.

Each entry is a regular expression conforming to Python Regular Expression Syntax. These expressions have two purposes. First, similar to “wildcard” expressions, they identify which rasters should be included in the time series and which should be ignored. For example, if you have both SST and chlorophyll rasters stored in the same workspace and want to sample values of SST, the expressions should match on the SST rasters but not match on the chlorophyll rasters. On the other hand, if you just have one kind of raster in your workspace and don’t have any that you need to ignore, your expressions can be simpler.

The second purpose of the expressions is to parse the date and time components from the raster names into named regular expression groups. This allows the tool to determine the date of each raster from its name. The table below lists the allowed group names, the typical regular expression syntax for parsing that group from a raster name, and an example fragment from a raster name:

Group Name	Typical RegEx Syntax	Example Raster Name Fragment
`Year`	`(?P<Year>\d\d\d\d)`	`2005`
`Month`	`(?P<Month>\d\d)`	`03`
`Day`	`(?P<Day>\d\d)`	`28`
`DayOfYear`	`(?P<DayOfYear>\d\d\d)`	`265`
`Hour`	`(?P<Hour>\d\d)`	`14`
`Minute`	`(?P<Minute>\d\d)`	`52`
`Second`	`(?P<Second>\d\d)`	`08`

At minimum, the rasterNameExpressions must include the Year. If this is the only date component included, the date will assumed to be January 1. If Month is also included but Day is not, Day will assumed to be 1. If Day is included, Month must also be included. Do not include both Month and DayOfYear, just one or the other. If Hour, Minute, or Second is not included, they will be assumed to be 00.

Here are some examples. If you have any questions, please feel free to email the MGET development team.

Example 1: Monthly SST rasters all in the same workspace

In this example, there is a single workspace with rasters named:

sst_199801
sst_199802
sst_199803
...

Here, you just need one expression:

sst_(?P<Year>\d\d\d\d)(?P<Month>\d\d)

This regular expression means “the characters sst\_ followed by four numeric digits representing the Year followed by two numeric digits representing the Month”. The following expression is more flexible and will match any raster that ends in six digits:

.+(?P<Year>\d\d\d\d)(?P<Month>\d\d)

This regular expression means “one or more of any character followed by four numeric digits representing the Year followed by two numeric digits representing the Month”.

Example 2: Daily SST rasters stored in yearly subdirectories

In this example, the workspace, a directory, contains a subdirectory for each year of data. The rasters are named with the year and day of year and have a .img file suffix:

1998
    sst_1998_001.img
    sst_1998_002.img
    ...
    sst_1998_365.img
1999
    sst_1999_001.img
    sst_1999_002.img
    ...
    sst_1999_365.img
...

Here, you need two expressions, one for the year subdirectory and one for the raster name:

(?P<Year>\d\d\d\d)
sst_(?P<Year>\d\d\d\d)_(?P<DayOfYear>\d\d\d).img

Example 3: Daily SST rasters with month and day of month

This is the same as the example above, but the rasters are named with month and day of the month instead of the day of the year:

1998
    sst_1998_01_01.img
    sst_1998_01_02.img
    ...
    sst_1998_01_31.img
    sst_1998_02_01.img
    ...
    sst_1998_12_31.img
1999
    sst_1999_01_01.img
    sst_1999_01_02.img
    ...
    sst_1999_12_31.img
...

Suitable expressions are:

(?P<Year>\d\d\d\d)
sst_(?P<Year>\d\d\d\d)_(?P<Month>\d\d)_(?P<Day>\d\d).img

Minimum length꞉ 1.

tCornerCoordType (str) –
Type of time coordinate that is parsed from the raster name:
- min - The time coordinate represents the beginning of the window of time for which the raster is valid. Most data providers publish their images using this convention. For example, the monthly files from the NOAA AVHRR Pathfinder SST version 5.0/5.1 dataset include the four-digit year and two-digit month, but no day of the month. These images represent the mean SST over the focal month. Since the file name does not include a day of the month, hour, minute, or second, the tool assumes the parsed time coordinate is for day 1 of the month, at time 00:00:00. This is the beginning of the one-month window to which the image applies, so “min” is the appropriate type of time coordinate.
- center - The time coordinate represents the center of the window of time for which the raster is valid. This is the next-most-popular type of time coordinate used by data providers. One example of this are the sea surface height (SSH) images published by Aviso in the 2010s (prior to Aviso releasing their data through Copernicus Marine Service). These files were published with a 7-day time step, but each image incorporated satellite altimeter observations before and after the focal date. Thus, the focal date occurred at the center of these observations.
- max - The time coordinate represents the end of the window of time for which the raster is valid. So far, the MGET development team has not encountered a data provider that uses this convention, but we have included it for completeness, in case such data do exist.
Allowed values꞉ 'min', 'center', 'max'.
tIncrement (float) –
Time step of the rasters, in the units of specified by the tIncrementUnit parameter.

Some examples:

For Rasters Occurring

Time Step

Time Step Unit

Every day

1

day

Every week

7

day

Every 8 days

8

day

Every month

1

month

Every year

1

year

Must be greater than 0.0.
tIncrementUnit (str) – Unit of the tIncrement parameter. Allowed values꞉ 'year', 'month', 'day', 'hour', 'minute', 'second'.
tSemiRegularity (str, optional) –
Use this parameter when your rasters always start on January 1, advance at a constant time step that does not add up to a full year, and the last raster covers only part of the normal time step.

For example, NASA and NOAA frequently publish rasters that have 8-day time steps but always start on January 1 of each year. The first 45 rasters of each year cover the full 8 days but the 46th raster only covers 5 or 6 days (depending on whether it is a leap year). For these datasets, you should set tSemiregularity to annual and tCountPerSemiRegularPeriod to 46.

Please consult the MGET development team for more help with this parameter. Allowed values꞉ 'annual'.
tCountPerSemiRegularPeriod (int, optional) – Number of rasters per semiregular period. This parameter is ignored if tSemiRegularity is omitted. Please see the documentation for that parameter for more information. Minimum value꞉ 1.
method (str, optional) –
Interpolation method to use, one of:
- Automatic - the tool will automatically select the interpolation method based on the raster’s data type: for integer rasters, nearest neighbor interpolation; for floating-point rasters, linear interpolation. This is the default.
- Nearest - nearest neighbor interpolation. The interpolated value will simply be the value of the cell that contains the point.
- Linear - linear interpolation (also known as trilinear interpolation). This method averages the values of the eight nearest cells in the x, y, and time dimensions, weighting the contribution of each cell by the area of it that would be covered by a hypothetical cell centered on the point being interpolated. If the cell containing the point contains NoData, the result is NoData. If any of the other seven cells contain NoData, they are omitted from the average, and the result is based on the weighted average of the cells that do contain data. This is the same algorithm implemented in 2D by the ArcGIS Spatial Analyst’s Extract Values to Points tool.
Allowed values꞉ 'Automatic', 'Nearest', 'Linear'.
where (str, optional) –
SQL WHERE clause expression that specifies the subset of points to process. If not provided, all of the points will be processed. If provided but the underlying storage format does not support WHERE clauses, an exception will be raised.

The exact syntax of this expression depends on the underlying storage format. If the underlying data store will be accessed through ArcGIS, this article may document some of the possible syntax, but not all of it may be supported through ArcGIS’s underlying Python API.

Minimum length꞉ 1.
noDataValue (float, optional) – Value to use when the interpolated value is NoData. If a value is not provided for this parameter, a database NULL value will be stored in the field when the interpolated value is NoData. If the field cannot store NULL values, as is the case with shapefiles, the value -9999 will be used.
rastersWrap (bool, optional) – Indicates whether or not the left and right edges of the rasters should be treated as connected. Enable this option when you have rasters that span 360 degrees of longitude and you wish the interpolator to consider cells on the opposite side of the raster when interpolating values for points very close to the left or right edge. This option has no effect if nearest neighbor interpolation is used, because the interpolated value will be based on the value of the single nearest cell.
orderByFields (list of str, optional) –
Fields for defining the order in which the points are processed. The points may be processed faster if they are ordered temporally and geographically, such that points that are close in time and space are processed sequentially. Ordering the points this way increases the probability that the value of a given point can be interpolated from data that is cached in memory, rather than from data that must be read from the disk or network, which is much slower. Choose fields that facilitate this. For example, if your points represent the locations of animals tracked by satellite telemetry, order the processing first by the animal ID and then by the transmission date or number.

By default, if you do not specify anything for this parameter, the points will be ordered by the points’ Date Field. Minimum length꞉ 1.
numBlocksToCacheInMemory (int, optional) –
Maximum number of blocks of raster data to cache in memory.

To minimize the number of times that the disk or network must be accessed, this tool employs a simple caching strategy. When it processes the first point, it reads a square block of cells centered on that point and caches it in memory. When it processes the second and subsequent points, it first checks whether the cells needed for that point are contained by the block cached in memory. If so, it processes that point using the in-memory block, rather than reading from disk or the network again. If not, it reads another square block centered on that point and adds it to the cache.

The tool processes the remaining points, adding additional blocks to the cache, as needed. To prevent the cache from exhausting all memory, it is only permitted to grow to the size specified by this parameter. When the cache is full but a new block is needed, the oldest block is discarded to make room for the newest block.

The maximum size of the cache in bytes may be calculated by multiplying this parameter by the block size parameters and the data type of the rasters. For example, if this parameter is 256 and the blocks are 32 by 32 and the raster uses the 32-bit floating point data type (32-bits is 4 bytes), the maximum size of the cache is 1048576 bytes (1 MB).

If this parameter is 0, no blocks will be cached in memory. Minimum value꞉ 0.
xBlockSize (int, optional) – Size of the blocks of raster data to cache in memory, in the x direction. The size is given as the number of cells. If this parameter is 0, no blocks will be cached in memory. Minimum value꞉ 0.
yBlockSize (int, optional) – Size of the blocks of raster data to cache in memory, in the y direction. The size is given as the number of cells. If this parameter is 0, no blocks will be cached in memory. Minimum value꞉ 0.
tBlockSize (int, optional) – Size of the blocks of data to cache in memory, in the t direction (time). The size is given as the number of cells. If this parameter is 0, no blocks will be cached in memory. Minimum value꞉ 0.

Returns:

Updated points.

Return type:

str

For Rasters Occurring	Time Step	Time Step Unit
Every day	1	day
Every week	7	day
Every 8 days	8	day
Every month	1	month
Every year	1	year