GeoEco.Connectivity.LarvalDispersal.LarvalDispersal.LoadCMEMSCurrentsIntoSimulation

classmethod LarvalDispersal.LoadCMEMSCurrentsIntoSimulation(simulationDirectory, startDate, endDate, username, password, datasetID='cmems_mod_glo_phy_my_0.083deg_P1D-m', depth=0.49402499198913574, rotationOffset=None, resamplingTechnique='CUBIC', interpolationMethod=None)

Downloads ocean currents from Copernicus Marine Service (CMEMS) into a larval dispersal simulation for a range of dates.

Requires: ArcGIS Pro 3.6.0 or later or ArcGIS Server equivalent to ArcGIS Pro 3.6.0 or later, ArcGIS ‘spatial’ extension, Python numpy module, Python matplotlib module.

Parameters:

  • simulationDirectory (str) –

    Existing larval dispersal simulation directory that should receive the currents.

    The directory must have been created using the Create Larval Dispersal Simulation tool.

    If you have already loaded currents into the simulation, you can use this tool to add data for an additional range of dates. If you try to load currents for a range of dates that have been already loaded into the simulation, the downloads for those dates will be skipped.

    Minimum length꞉ 1. Must exist.

  • startDate (datetime) – Start date for the currents to load into the simulation. Currents that occurred on or after the start date and on or before the end date will be loaded into the simulation.

  • endDate (datetime) – End date for the currents to load into the simulation. Currents that occurred on or after the start date and on or before the end date will be loaded into the simulation.

  • username (str) – Copernicus Marine Service user name. Minimum length꞉ 1.

  • password (str) – Copernicus Marine Service password. Minimum length꞉ 1.

  • datasetID (str, optional) –

    CMEMS Dataset ID to access. You can find the Dataset ID by going to the Copernicus Marine Data Store, viewing your product of interest, clicking on Data Access, and scrolling to the Dataset ID table. The dataset must have 4 dimensions: longitude, latitude, depth, and time (in any order).

    The default cmems_mod_glo_phy_my_0.083deg_P1D-m, the Global Ocean Physics Reanalysis at daily resolution, is a good choice when you don’t know of something better for your area of interest.

    Minimum length꞉ 1.

  • depth (float, optional) –

    Depth layer to download.

    You must specify the exact depth of the layer, at full precision without rounding. The default value is the shallowest layer of the default dataset cmems_mod_glo_phy_my_0.083deg_P1D-m. For your convenience, when this tool runs it will log a list of depth layers for the dataset you specify. If your first attempt fails because the depth does not exist, copy one of the values from the log message and try again.

    This tool was designed primarily to study larvae that float at or near the surface. If you are studying larvae that stay submerged, you can choose a deeper depth, but be aware of two important points:

    • This tool assumes the larvae remain at that depth for the entire simulation. It does not implement vertical migration or other behaviors that might be appropriate for your species.

    • The spatial extent of available currents data will shrink as depth increases. For example, if you choose a deep depth such as 250 m, there will be no data available for regions close to shore because the ocean is typically shallower than 250 m in those regions. Data for very deep depths may only be available many kilometers from shore. If your species remains suspended just above the seafloor regardless of the seafloor’s depth, you can use the depth value 20000 to represent this, and the tool will download whatever layer is the deepest at each latitude and longitude.

    Minimum value꞉ 0.0.

  • rotationOffset (float, optional) – Degrees to rotate the outputs about the polar axis. This parameter may only be used for global products. The outputs can only be rotated in whole cells. The value you provide will be rounded off to the closest cell. The value may be positive or negative.

  • resamplingTechnique (str, optional) –

    Resampling algorithm to be used when projecting the ocean currents data to the coordinate system and cell size of the simulation. One of:

    The projection is accomplished with the ArcGIS ProjectRaster() tool. Please see the documentation for that tool for more information.

    Allowed values꞉ 'NEAREST', 'BILINEAR', 'CUBIC'.

  • interpolationMethod (str, optional) –

    Method to use to guess ocean current values for cells marked as water by the simulation’s water mask but for which no estimate is available in the currents data.

    By default, this option is disabled and cells marked as water that do not have any currents data are assumed to have a current velocity of zero. Larvae within these cells cannot exit by advection, only by diffusion. Because diffusion typically disperses larvae much more slowly than advection, these zero-velocity cells will act as larvae sinks that appear to trap most larvae that enter them.

    That situation is usually unrealistic and undesirable, and when it happens the simulator will issue a warning describing the problem. If you experience this problem you can instruct the tool to guess current values using one of the following algorithms:

    • Del2a - Laplacian interpolation and linear extrapolation. We recommend you use this method unless you have a specific reason to select one of the others.

    • Del2b - Same as Del2a but does not build as large a linear system of equations. May be faster than Del2a at the cost of some accuracy.

    • Del2c - Same as Del2a but solves a direct linear system of equations for the NoData values. Faster than both Del2a and Del2b but is the least robust to noise on the boundaries of NoData cells and least able to interpolate accurately for smooth surfaces.

    • Del4 - Same as Del2a but instead of the Laplace operator (also called the ∇2 operator) it uses the biharmonic operator (also called the ∇4 operator). May result in more accurate interpolations, at some cost in speed.

    • Spring - Uses a spring metaphor. Assumes springs (with a nominal length of zero) connect each cell with every neighbor (horizontally, vertically and diagonally). Since each cell tries to be like its neighbors, extrapolation is as a constant function where this is consistent with the neighboring nodes.

    Be advised that this option should be considered a last resort. When ocean current values are missing for a region, it is because the original data provider does not know how to estimate or model the currents in that region. If it was simply a matter of using one of the methods above, they would have already done so. These methods produce estimates that are likely to be inaccurate and should only be used when you are willing to accept those inaccuracies because there is no other way to proceed.

    Although this option can fill NoData clusters of any size, you should apply common sense when using it. The larger the cluster, the less accurate the guessed values will be.

    If you receive and OUT OF MEMORY error when utilizing this parameter, try switching to the Del2b or Del2c algorithm. If you still receive OUT OF MEMORY when using Del2c, the analysis resolution is too fine for the spatial extent you wish to simulate. You must recreate the simulation with either a coarser resolution or a smaller spatial extent. You are welcome to contact the MGET development team for advice. In general, we recommend the simulation rasters span no more than 1000x1000 cells, ideally less than 500x500.

    Thanks to John D’Errico for providing the code that implements the mathematical algorithms described here (click here for more information).

    Allowed values꞉ 'Del2a', 'Del2b', 'Del2c', 'Del4', 'Spring'.

Returns:

Updated simulation directory.

Return type:

str