edmt.conversion

Submodules

Package Contents

edmt.conversion.sdf_to_gdf(sdf, crs=None)

Converts a spatial DataFrame to a GeoDataFrame with optional CRS assignment.

Parameters:

  • sdf (pd.DataFrame) -- Input spatial DataFrame containing geometry column.

  • crs (str or int, optional) -- Coordinate Reference System. Defaults to EPSG:4326.

Returns:

A cleaned GeoDataFrame with valid geometries.

Return type:

gpd.GeoDataFrame

Raises:

ValueError -- If input is not a DataFrame or is empty.

edmt.conversion.generate_uuid(df: pandas.DataFrame, *, force: bool = False, index: bool = False, uuid_col: str = 'uuid', detect_uuid_cols: bool = True, detect_contains: tuple[str, Ellipsis] = ('uuid',)) → pandas.DataFrame

Ensure a pandas DataFrame contains a column of valid UUIDs, creating or repairing as needed.

This function adds a new UUID column or validates/repairs an existing one. It can optionally detect existing UUID-like columns to avoid duplication and control column placement.

Parameters:

  • df (pd.DataFrame) -- Input DataFrame to process.

  • force (bool, optional) -- If True, always generate new UUIDs—even if a valid UUID column already exists (default: False).

  • index (bool, optional) -- If True, place the UUID column at the beginning of the DataFrame; otherwise, place it at the end (default: False).

  • uuid_col (str, optional) -- Name of the target UUID column (default: "uuid").

  • detect_uuid_cols (bool, optional) -- If True and force=False, scan for existing columns that appear to contain UUIDs (based on name and content) to avoid redundant generation (default: True).

  • detect_contains (tuple of str, optional) -- Substrings used to identify potential UUID columns by name when detect_uuid_cols=True (default: ("uuid",)).

Returns:

A copy of the input DataFrame with a valid UUID column named uuid_col.

Return type:

pd.DataFrame

Raises:

ValueError -- If input is not a DataFrame or if the DataFrame is empty.

Notes

  • A value is considered a valid UUID if it is a string matching the standard UUID format (e.g., "f47ac10b-58cc-4372-a567-0e02b2c3d479").

  • When force=False and a UUID-like column is detected (by name and content), the function reuses it but repairs any invalid entries by replacing them with new UUIDs.

  • The output DataFrame is always a copy; the original is not modified.

  • Column ordering is explicitly controlled: UUID column is moved to front if index=True, otherwise to the back.

Examples

>>> df = pd.DataFrame({"name": ["Alice", "Bob"]})
>>> df_with_uuid = generate_uuid(df)
>>> "uuid" in df_with_uuid.columns
True

>>> df_existing = pd.DataFrame({"uuid": ["invalid", "7af3ea7c-5a14-48c2-a3c2-b014488c0216"], "val": [1, 2]})
>>> fixed = generate_uuid(df_existing)
# First entry replaced with valid UUID; second preserved
edmt.conversion.generate_cmap(data: ArrayLike, num_divisions: int, cmap: str = 'viridis') → Tuple[List[str], List[str]]

Generate range labels and corresponding hex colors from a colormap.

Parameters:

  • data (array-like) -- Numeric data used to determine the value range.

  • num_divisions (int) -- Number of intervals to divide the data range into.

  • cmap (str, default="viridis") -- Name of the matplotlib colormap.

Returns:

labels :

Range labels formatted as "min - max".

colors :

Hexadecimal color codes corresponding to each range.

Return type:

tuple[list[str], list[str]]

Raises:

ValueError -- If num_divisions is less than 1 or data is empty.

edmt.conversion.get_utm_epsg(longitude=None)

Generates UTM EPSG code based on longitude.

Parameters:

longitude (float) -- Longitude value to determine UTM zone.

Returns:

EPSG code as a string.

Return type:

str

Raises:

KeyError -- If longitude is not provided.

edmt.conversion.convert_time(value: float, unit_from: str, unit_to: str) → float

Converts a given time value between different units.

Parameters:

  • time_value (float) -- The numerical value of the time.

  • unit_from (str) -- The original unit of time.

  • unit_to (str) -- The target unit to convert to.

Returns:

The converted time value rounded to 3 decimal places.

Return type:

float

Raises:

ValueError -- If units are unsupported or value is invalid.

edmt.conversion.convert_speed(speed: float, unit_from: str, unit_to: str) → float

Converts speed between different units.

Parameters:

  • speed (float) -- Input speed value.

  • unit_from (str) -- Original unit.

  • unit_to (str) -- Target unit.

Returns:

Converted speed value.

Return type:

float

Raises:

ValueError -- If unit is unsupported.

edmt.conversion.convert_distance(value: float, unit_from: str, unit_to: str) → float

Converts distance values between metric and imperial units.

Parameters:

  • value (float) -- Input distance value.

  • from_type (str) -- Original unit.

  • to_type (str) -- Target unit.

Returns:

Converted distance value.

Return type:

float

Raises:

ValueError -- If unit is unsupported.

edmt.conversion.convert_temperature(value: float, unit_from: str, unit_to: str) → float

Converts temperature between different scales.

Parameters:

  • value (float) -- Input temperature value.

  • unit_from (str) -- Original unit. Supported: C, F, K (also °C, °F, °K).

  • unit_to (str) -- Target unit. Supported: C, F, K (also °C, °F, °K).

Returns:

Converted temperature value (rounded to 3 decimals).

Return type:

float

Raises:

ValueError -- If unit is unsupported or Kelvin is invalid (< 0).

edmt.conversion.format_temperature(value: float, unit: str, symbol: bool = True) → str

Formats a temperature value with unit, e.g. '23.5 °C' or '296.6 K'.

Parameters:

  • value (float) -- Temperature value.

  • unit (str) -- Unit to display (C, F, K).

  • symbol (bool) -- If True, uses °C/°F, and K without degree symbol.

Returns:

Formatted temperature string.

Return type:

str