API

Calculates area information, j and i displacement, new and old latitude/longitude, v, u, and velocity of the wind.

pywinds.wind_functions.area(lat_ts, lat_0, long_0, displacement_data=None, projection=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None)

Dynamically computes area of projection.

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that pixels are describing (stere, laea, merc, etc)

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • area_extent (list, optional) – Area extent in projection units (lower_left_y, lower_left_x, upper_right_y, upper_right_x)

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) –

    ellipsoid of projection (WGS84, sphere, etc)

    returns

    area – projection, lat_0 (degrees), long_0 (degrees), equatorial radius (meters), eccentricity, inverse_flattening, shape, area_extent (degrees), pixel_size (projection meters), center (degrees)

    rtype

    dict

pywinds.wind_functions.displacements(lat_ts=None, lat_0=None, long_0=None, displacement_data=None, projection=None, j=None, i=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None)

Dynamically computes displacements.

Parameters

  • lat_ts (float, optional) – Latitude of true scale

  • lat_0 (float, optional) – Latitude of origin

  • long_0 (float, optional) – Central meridian

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str, optional) – Name of projection that pixels are describing (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • j (float or None, optional) – Row to run calculations on

  • i (float or None, optional) – Column to run calculations on

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) –

    ellipsoid of projection (WGS84, sphere, etc)

    returns

    (j_displacements, i_displacements) – j_displacements and i_displacements found in displacement file or list in row-major format

    rtype

    numpy.array or list

pywinds.wind_functions.geodesic_bck(old_lat, old_long, new_lat, new_long, earth_ellipsoid=None, units=None)

Computes the shortest distance, initial bearing and back bearing given a starting and ending position.

Parameters

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • new_lat (float) – Ending point latitude

  • new_long (float) – Ending point longitude

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units

    3. meters

Returns

(distance, forward bearing, back bearing) – distance, forward bearing, and back bearing from initial position to final position

Return type

numpy.array or list

pywinds.wind_functions.geodesic_fwd(old_lat, old_long, distance, initial_bearing, earth_ellipsoid=None, units=None)

Computes the new lat, new long, and back bearing given a starting position, distance, and forward bearing.

Parameters

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • distance (float) – Distance from old position to new position

  • initial_bearing (float) – Initial bearing from old position to new position

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units

    3. meters

Returns

(new lat, new long, back bearing) – new latitude, new longitude, and back bearing from initial position

Return type

numpy.array or list

pywinds.wind_functions.lat_long(lat_ts, lat_0, long_0, displacement_data=None, projection=None, j=None, i=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None)

Computes the latitude and longitude given an area and pixel-displacement.

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that pixels are describing (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • j (float or None, optional) – Row to run calculations on

  • i (float or None, optional) – Column to run calculations on

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of projection (WGS84, sphere, etc)

Returns

(latitude, longitude) – latitude and longitude calculated from area and pixel-displacement in row-major format

Return type

numpy.array or list

pywinds.wind_functions.loxodrome_bck(old_lat, old_long, new_lat, new_long, earth_ellipsoid=None, units=None)

Computes the distance, forward bearing and back bearing given a starting and ending position.

Credit: https://search-proquest-com.ezproxy.library.wisc.edu/docview/2130848771?rfr_id=info%3Axri%2Fsid%3Aprimo

Parameters

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • new_lat (float) – Ending point latitude

  • new_long (float) – Ending point longitude

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units

    3. meters

Returns

(distance, forward bearing, back bearing) – distance, forward bearing, and back bearing from initial position to final position

Return type

numpy.array or list

pywinds.wind_functions.loxodrome_fwd(old_lat, old_long, distance, forward_bearing, earth_ellipsoid=None, units=None)

Computes the new lat, new long, and back bearing given a starting position, distance, and forward bearing.

Credit: https://search-proquest-com.ezproxy.library.wisc.edu/docview/2130848771?rfr_id=info%3Axri%2Fsid%3Aprimo

Parameters

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • distance (float) – Distance from old position to new position

  • forward_bearing (float) – Forward bearing from old position to new position

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units

    3. meters

Returns

(new lat, new long, back bearing) – new latitude, new longitude, and back bearing from initial position

Return type

numpy.array or list

pywinds.wind_functions.position_to_pixel(lat_ts, lat_0, long_0, lat, long, projection=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, projection_ellipsoid=None, units=None, displacement_data=None)

Calculates the pixel given a position

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • lat (float or None, optional) – Latitude to run calculations on

  • long (float or None, optional) – Longitude to run calculations on

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that pixels are describing (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of projection (WGS84, sphere, etc)

Returns

(j, i) – j and i pixel that the provided latitude and longitude represent on the given area.

Return type

numpy.array or list

pywinds.wind_functions.velocity(lat_ts, lat_0, long_0, delta_time, displacement_data=None, projection=None, j=None, i=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None, earth_ellipsoid=None)

Computes the speed and angle of the wind given an area and pixel-displacement.

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • delta_time (int) – Amount of time that separates both files in minutes.

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that the image is in (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • j (float or None, optional) – Row to run calculations on

  • i (float or None, optional) – Column to run calculations on

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of projection (WGS84, sphere, etc)

  • earth_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of Earth (WGS84, sphere, etc)

Returns

(speed, angle) – speed and angle (measured clockwise from north) of the wind calculated from area and pixel-displacement in row-major format

Return type

numpy.array or list

pywinds.wind_functions.velocity_fll(delta_time, old_lat, old_long, new_lat, new_long, earth_ellipsoid=None)

Computes the speed and angle of the wind given two latitudes and longitudes.

Parameters

  • delta_time (int) – Amount of time that separates both files in minutes.

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • new_lat (float) – Ending point latitude

  • new_long (float) – Ending point longitude

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

Returns

(speed, angle) – speed and angle (measured clockwise from north) of the wind calculated from area and pixel-displacement in row-major format

Return type

numpy.array or list

pywinds.wind_functions.vu(lat_ts, lat_0, long_0, delta_time, displacement_data=None, projection=None, j=None, i=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None, earth_ellipsoid=None)

Computes the v and u components of the wind given an area and pixel-displacement.

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • delta_time (int) – Amount of time that separates both files in minutes.

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that pixels are describing (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • j (float or None, optional) – Row to run calculations on

  • i (float or None, optional) – Column to run calculations on

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of projection (WGS84, sphere, etc)

  • earth_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of Earth (WGS84, sphere, etc)

Returns

(v, u) – v and u components of wind calculated from area and pixel-displacement in row-major format

Return type

numpy.array or list

pywinds.wind_functions.vu_fll(delta_time, old_lat, old_long, new_lat, new_long, earth_ellipsoid=None)

Computes the v and u components of the wind given two latitudes and longitudes.

Parameters

  • delta_time (int) – Amount of time that separates both files in minutes.

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • new_lat (float) – Ending point latitude

  • new_long (float) – Ending point longitude

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

Returns

(v, u) – v and u components of wind calculated from area and pixel-displacement in row-major format

Return type

numpy.array or list

pywinds.wind_functions.wind_info(lat_ts, lat_0, long_0, delta_time, displacement_data=None, projection=None, j=None, i=None, area_extent=None, shape=None, center=None, pixel_size=None, upper_left_extent=None, radius=None, units=None, projection_ellipsoid=None, earth_ellipsoid=None, no_save=False, save_directory=None, timestamp=None)

Computes the latitude, longitude, velocity, angle, v, and u of the wind given an area and pixel-displacement.

Parameters

  • lat_ts (float) – Latitude of true scale

  • lat_0 (float) – Latitude of origin

  • long_0 (float) – Central meridian

  • delta_time (int) – Amount of time that separates both files in minutes.

  • displacement_data (str or list, optional) – Filename or list containing displacements: [tag, width, height, i_11, j_11, i_12, j_12, …, i_nm, j_nm] or [[j_displacement], [i_displacement]] respectively

  • projection (str) – Name of projection that pixels are describing (stere, laea, merc, etc).

  • units (str, optional) –

    Units that length arguments should be interpreted as. This can be one of ‘deg’, ‘degrees’, ‘rad’, ‘radians’, ‘meters’, ‘metres’, and any parameter supported by the cs2cs -lu command. Units are determined in the following priority:

    1. units expressed with variables via xarray attributes

    2. units passed to units (exluding center)

    3. meters (exluding center, which is degrees)

  • j (float or None, optional) – Row to run calculations on

  • i (float or None, optional) – Column to run calculations on

  • area_extent (list, optional) – Area extent in projection units [lower_left_y, lower_left_x, upper_right_y, upper_right_x]

  • shape (list, optional) – Number of pixels in the y and x direction following row-major format (height, width). Note that shape can be found from the displacement file or the area provided.

  • center (list, optional) – Center of projection (lat, long)

  • pixel_size (list or float, optional) – Size of pixels: (dy, dx)

  • upper_left_extent (list, optional) – Projection y and x coordinates of the upper left corner of the upper left pixel (y, x)

  • radius (list or float, optional) – Projection length from the center to the left/right and top/bottom outer edges (dy, dx)

  • projection_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of projection (WGS84, sphere, etc)

  • earth_ellipsoid (str, dict, or pyproj.Geod, optional) – ellipsoid of Earth (WGS84, sphere, etc)

  • no_save (bool, optional) – When False, saves wind_info to name_of_projection.txt, j_displacement.txt, i_displacement.txt, new_latitude.txt, new_longitude.txt, old_latitude.txt, old_longitude.txt, v.txt, u.txt, speed.txt, angle.txt, and wind_info.txt in that order (name_of_projection varies depending on the type of projection). Each of these variables are saved to wind_info.nc by the same name as their .txt counterparts in a new directory provided by the save_directory argument.

  • save_directory (str, optional) – Directory in which to save the file containing data (also a directory) to. If the directory provided does not exist, then it is created. Defaults to a new directory by the name of the displacement file read appended with “_output_YYYYmmdd_HHMMSS” (the date and time when the script was ran), created where the script is ran

  • timestamp (str, optional) – The time at which the script was ran. Defaults to the current time in not provided.

Returns

(latitude, longitude, velocity, angle, v, and u at each pixel) – [latitude, longitude, velocity, angle, v, u] at each pixel in row-major format

Return type

numpy.array or list

pywinds.wind_functions.wind_info_fll(delta_time, old_lat, old_long, new_lat, new_long, earth_ellipsoid=None)

Computes the latitude, longitude, velocity, angle, v, and u of the wind given two latitudes and longitudes.

Parameters

  • delta_time (int) – Amount of time that separates both files in minutes.

  • old_lat (float) – Starting point latitude

  • old_long (float) – Starting point longitude

  • new_lat (float) – Ending point latitude

  • new_long (float) – Ending point longitude

  • earth_ellipsoid (str, optional) – ellipsoid of Earth (WGS84, sphere, etc)

Returns

(latitude, longitude, velocity, angle, v, and u at each pixel) – [latitude, longitude, velocity, angle, v, u] at each pixel in row-major format

Return type

numpy.array or list