API¶

Generators¶

For generating grids of floats.

class floater.generators.FloatSet(xlim=None, ylim=None, dx=1.0, dy=1.0, model_grid=None, load_path=None, zvect=None)¶

Represents a set of initial float positions on a regular grid.

Methods

`from_pickle`([filename])	Sets attributes equal to saved FloatSet object in pickled format
`get_hexmesh`()	Get the coordinates of the float positions in a hexagonal mesh.
`get_rectmesh`()	Get the coordinates of the float positions in a rectangualr mesh.
`npart_index_to_ndarray`(data, npart)	Grid the data according to its npart (particle id)
`npart_to_2D_array`(ds1d)	Constructs 2D Dataset from 1D DataArray/Dataset of single or multi-variable.
`parcel_area`([latlon])	Get the area of each parcel.
`subset_floats_from_mask`(xx, yy, zz)	Eliminate float positions that are on land land mask.
`to_mitgcm_format`(filename[, tstart, iup, …])	Output floatset data in MITgcm format
`to_pickle`([filename])	Write out floatset data in pickled format

from_pickle(filename='./floatset.pkl')¶

Sets attributes equal to saved FloatSet object in pickled format

Parameters:	filename : str The filename to load in the saved floatset data from (e.g. ‘floatset.pkl’)

get_hexmesh()¶

Get the coordinates of the float positions in a hexagonal mesh.

Returns:	x : np.ndarray 1D array of float x coordinates y : np.ndarray 1D array of float y coordinates z : np.ndarray 1D array of float z coordinates

get_rectmesh()¶

Get the coordinates of the float positions in a rectangualr mesh.

Returns:	x : np.ndarray 1D array of float x coordinates y : np.ndarray 1D array of float y coordinates z : np.ndarray 1D array of float z coordinates

npart_index_to_ndarray(data, npart)¶

Grid the data according to its npart (particle id)

Parameters:	data : 1D array The data to be gridded npart : 1D array The particle ids

npart_to_2D_array(ds1d)¶

Constructs 2D Dataset from 1D DataArray/Dataset of single or multi-variable.

Parameters:	ds1d : 1D DataArray/Dataset One-dimensional dataarray/dataset of physical variable(s) with dimension ‘npart’
Returns:	ds2d : 2D Dataset Two-dimensional dataset of physical variable(s) with dimensions ‘y0’ and ‘x0’

parcel_area(latlon=True)¶: Get the area of each parcel.

subset_floats_from_mask(xx, yy, zz)¶

Eliminate float positions that are on land land mask.

Parameters:

xx : arraylike

float longitudes

yy : arraylike

float latitudes

zz : arraylike

float depths

model_grid : dictionary

the following key value pairs are expected

‘land_mask’: np.ndarray of bools: 2d array of dimensions in C order: shape==(len(lat), len(lon)) An element is True iff the corresponding tracer cell grid point is unmasked (ocean) OR 3d array

‘lon’: 1d array of the mask grid longitudes ‘lat’: 1d array of the mask grid latitudes ‘rc’: 1d array of mask grid depths

RETURNS

——-

xx_masked, yy_masked, zz_masked: np.ndarray

1D arrays of float coordinates subarrays:

to_mitgcm_format(filename, tstart=0, iup=0, mesh='rect', read_binary_prec=64)¶

Output floatset data in MITgcm format

Parameters:

filename : str

The filename to save the floatset data in (e.g.float.ini.pos.hex.bin)

tstart : float

time for float initialisation (default = 0)

iup : int

flag if the float

should profile ( > 0 = return cycle (in s) to surface)
remain at depth ( = 0 )
is a 3D float ( = -1 )
should be advected WITHOUT additional noise (= -2 );

(this implies that the float is non-profiling)
is a mooring ( = -3 ); i.e. the float is not advected

mesh : {‘rect’, ‘hex’}

‘rect’ : rectangular cartesian
‘hex’ : hexagonal

read_binary_prec : {32, 64}

data precision for binary file (should match MITgcm data file)

to_pickle(filename='./floatset.pkl')¶

Write out floatset data in pickled format

Parameters:	filename : str The filename to save the floatset data in (e.g. ‘floatset.pkl’)

Input¶

Input formats for different types of float data.

class floater.input.MITgcmFloatData(data_path, file_prefix='float_trajectories', buf_dim=14, file_dtype=dtype('>f4'), cast_to_dtype=dtype('float32'), keep_fields=None)¶

Everything we need to interact with MITgcm float output data.

Methods

generator([read_blocksize_mb, …]) Returns a generator which will loop through every record in the dataset.

generator(read_blocksize_mb=64, return_full_block=False, progress=True)¶

Returns a generator which will loop through every record in the dataset.

Parameters:	read_blocksize_mb : int The number of mb to read in at a time return_full_block : bool If `True`, returns the whole block on each yield. Otherwise one record at a time progress : bool Report on progress to stdout

RCLV¶

floater.rclv.contour_area(con)¶

Calculate the area, convex hull area, and convexity deficiency of a polygon contour.

Parameters:	con : arraylike A 2D array of vertices with shape (N,2) that follows the scikit image conventions (con[:,0] are j indices)
Returns:	region_area : float hull_area : float convexity_deficiency : float

floater.rclv.contour_ji_to_geo(contour_ji, lon, lat)¶

converts a contour in ij pixel coordinates to lat/lon

Parameters:	contour_ij: the list of vertices in (the LAVD image’s) ij pixel coordinates lon: 1-D array of grid longitudes lat: 1-D array of gird latitudes
Returns:	contour_geo: the list of vertices in lat/lon coordinates

floater.rclv.convex_contour_around_maximum(data, ji, init_contour_step_frac=0.1, border=5, convex_def=0.01, convex_def_tol=0.001, max_footprint=None, proj_kwargs=None, periodic=(False, False), max_iters=1000, min_limit_diff=1e-10)¶

Find the largest convex contour around a maximum.

Parameters:

data : array_like: The 2D data to contour
ji : tuple: The index of the maximum in (j, i) order
init_contour_step_frac : float: the value with which to increment the initial contour level (multiplied by the local maximum value)
border: int: the initial window around the maximum
convex_def : float, optional: The target convexity deficiency allowed for the contour.
convex_def_tol : float, optional: The tolerance for which the convexity deficiency will be sought
verbose : bool, optional: Whether to print out diagnostic information
proj_kwargs : dict, optional: Information for projecting the contour into spatial coordinates. Should contain entries lon0, lat0, dlon, and dlat.
periodic : tuple: Tuple of bools which specificies the periodicity of each axis (j, i) of the data

Returns:

contour : array_like: 2D array of contour vertices with shape (N,2) that follows the scikit image conventions (contour[:,0] are j indices)
area : float: The area enclosed by the contour
cd : float: The actual convexity deficiency of the identified contour

floater.rclv.find_convex_contours(data, min_distance=5, min_area=100.0, use_threadpool=False, lon=None, lat=None, progress=False, **contour_kwargs)¶

Find the outermost convex contours around the maxima of data with specified convexity deficiency.

Parameters:

data : array_like: The 2D data to contour
min_distance : int, optional: The minimum distance around maxima (pixel units)
min_area : float, optional: The minimum area of the regions (pixels or projected if lon and lat are specified)
lon, lat : arraylike: Longitude and latitude of data points. Should be 1D arrays such that len(lon) == data.shape[1] and len(lat) == data.shape[0]
init_contour_step_frac : float: the value with which to increment the initial contour level (multiplied by the local maximum value)
border: int: the initial window around the maximum
convex_def : float, optional: The target convexity deficiency allowed for the contour.
convex_def_tol : float, optional: The tolerance for which the convexity deficiency will be sought
verbose : bool, optional: Whether to print out diagnostic information
proj_kwargs : dict, optional: Information for projecting the contour into spatial coordinates. Should contain entries lon0, lat0, dlon, and dlat.
periodic : tuple: Tuple of bools which specificies the periodicity of each axis (j, i) of the data

Yields:

contour : array_like: 2D array of contour vertices with shape (N,2) that follows the scikit image conventions (contour[:,0] are j indices)
area : float: The area enclosed by the contour (in pixels or projected if lon and lat are specified)
cd : float: The actual convexity deficiency of the identified contour

floater.rclv.label_points_in_contours(shape, contours)¶

Label the points inside each contour.

Parameters:	shape : tuple Shape of the original domain from which the contours were detected (e.g. LAVD field) contours : list of vertices The contours to label (e.g. result of RCLV detection)
Returns:	labels : array_like Array with contour labels assigned. Zero means not inside a contour

floater.rclv.polygon_area(verts)¶

Compute the area of a polygon.

Parameters:	verts : array_like 2D shape (N,2) array of vertices. Uses scikit image convetions (j,i indexing) Returns area : float Area of polygon enclolsed by verts. Sign is determined by vertex order (cc vs ccw)

floater.rclv.project_vertices(verts, lon0, lat0, dlon, dlat)¶

Project the logical coordinates of vertices into physical map coordiantes.

Parameters:	verts : arraylike A 2D array of vertices with shape (N,2) that follows the scikit image conventions (con[:,0] are j indices) lon0, lat0 : float center lon and lat for the projection dlon, dlat : float spacing of points in longitude dlat : float spacing of points in latitude
Returns:	verts_proj : arraylike A 2D array of projected vertices with shape (N,2) that follows the scikit image conventions (con[:,0] are j indices)

Utils¶

floater.utils.floats_to_bcolz(input_dir, output_dir, progress=False, **kwargs)¶: Convert MITgcm float data to bcolz format.

floater.utils.floats_to_castra(input_dir, output_fname, progress=False, **kwargs)¶: Convert MITgcm float data to pands hdf format.

floater.utils.floats_to_netcdf(input_dir, output_fname, float_file_prefix='float_trajectories', ref_time=None, output_dir='./', output_prefix='float_trajectories', pkl_path=None)¶

Convert MITgcm float data to NetCDF format.

Parameters:	input_dir : path Where to find the MITgcm output data output_fname : path Filename of the NetCDF data store float_file_prefix : str Prefix of MITgcm output files ref_time : str Reference time, format: YYYY-MM-DD output_dir : path Where to store the transcoded NetCDF files output_prefix : str Prefix of the transcoded NetCDF files

floater.utils.floats_to_pandas(input_dir, output_fname, progress=False, **kwargs)¶: Convert MITgcm float data to pands hdf format.

floater.utils.floats_to_tables(float_dir, output_fname, float_file_prefix='float_trajectories', fltBufDim=14, float_dtype=dtype('>f4'), use_memmap=True, progress=False, write_blocksize_mb=64, read_blocksize_mb=64, max_write_blocks=inf)¶: Translate an MITgcm float output file into pytables HDF format.