numdaplot 0.1.0__py3-none-any.whl

numdaplot/data_types/numpy_mapping.py

@@ -0,0 +1,207 @@
+"""
+Conversion between ``ndp.Type`` and numpy dtypes, used by Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any, cast
+
+import numpy
+
+from numdaplot.data_types.library import Library
+from numdaplot.data_types.type import Type
+from numdaplot.errors.unsupported_type_error import UnsupportedTypeError
+
+# Some versions of the numpy stubs leave out the missing value marker of StringDType.
+STRING_DTYPE_CLASS = cast(Any, numpy.dtypes.StringDType)
+TEXT_DTYPE = STRING_DTYPE_CLASS(na_object=numpy.nan)
+NUMPY_DTYPE_CODES = {
+	Type.INT8: "int8",
+	Type.INT16: "int16",
+	Type.INT32: "int32",
+	Type.INT64: "int64",
+	Type.UINT8: "uint8",
+	Type.UINT16: "uint16",
+	Type.UINT32: "uint32",
+	Type.UINT64: "uint64",
+	Type.FLOAT32: "float32",
+	Type.FLOAT64: "float64",
+	Type.BOOL: "bool",
+	Type.DATE: "datetime64[D]",
+	Type.DATETIME: "datetime64[ns]",
+	Type.DURATION: "timedelta64[ns]",
+	Type.TIME: "timedelta64[us]",
+}
+NAMED_NUMPY_TYPES = (
+	Type.INT8,
+	Type.INT16,
+	Type.INT32,
+	Type.INT64,
+	Type.UINT8,
+	Type.UINT16,
+	Type.UINT32,
+	Type.UINT64,
+	Type.FLOAT32,
+	Type.FLOAT64,
+	Type.BOOL,
+)
+TYPES_BY_DTYPE_NAME = {NUMPY_DTYPE_CODES[data_type]: data_type for data_type in NAMED_NUMPY_TYPES}
+TEXT_KINDS = frozenset({"U", "T"})
+DATETIME_KIND = "M"
+DURATION_KIND = "m"
+DAY_UNIT = "D"
+TIME_UNIT = "us"
+
+
+def to_numpy_dtype(data_type: Type) -> numpy.dtype[Any]:
+	"""
+	Return the numpy dtype that stores the values of a numdaplot type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data_type
+		The numdaplot type to convert.
+
+	Returns
+	-------
+	numpy.dtype
+		The matching numpy dtype. ``TEXT`` gives the variable-length ``StringDType`` with NaN as missing value,
+		``DATE`` gives ``datetime64[D]`` and ``DATETIME`` gives ``datetime64[ns]``.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When the type has no numpy equivalent, which is the case of ``CATEGORY``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.numpy_mapping import to_numpy_dtype
+	>>> to_numpy_dtype(ndp.Type.INT32)
+	dtype('int32')
+	"""
+	if data_type == Type.TEXT:
+		return TEXT_DTYPE
+
+	if data_type not in NUMPY_DTYPE_CODES:
+		raise UnsupportedTypeError(data_type.name, Library.NUMPY)
+
+	dtype_code = NUMPY_DTYPE_CODES[data_type]
+	numpy_dtype = numpy.dtype(dtype_code)
+
+	return numpy_dtype
+
+
+def from_numpy_dtype(numpy_dtype: numpy.dtype[Any]) -> Type:
+	"""
+	Return the numdaplot type that matches a numpy dtype.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numpy_dtype
+		The numpy dtype to convert. Fixed-length (``<U5``) and variable-length strings both give ``TEXT``.
+		``timedelta64[us]`` gives ``TIME``, the time since midnight, and every other ``timedelta64`` unit gives
+		``DURATION``.
+
+	Returns
+	-------
+	Type
+		The matching numdaplot type.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When numdaplot has no equivalent type, for example complex numbers or Python objects.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.data_types.numpy_mapping import from_numpy_dtype
+	>>> from_numpy_dtype(numpy.dtype("datetime64[D]"))
+	<Type.DATE: 14>
+	"""
+	dtype_name = numpy_dtype.name
+	if dtype_name in TYPES_BY_DTYPE_NAME:
+		named_type = TYPES_BY_DTYPE_NAME[dtype_name]
+		return named_type
+
+	dtype_kind = numpy_dtype.kind
+	if dtype_kind in TEXT_KINDS:
+		return Type.TEXT
+
+	if dtype_kind == DURATION_KIND:
+		duration_type = find_duration_type(numpy_dtype)
+		return duration_type
+
+	if dtype_kind == DATETIME_KIND:
+		datetime_type = find_datetime_type(numpy_dtype)
+		return datetime_type
+
+	type_name = str(numpy_dtype)
+	raise UnsupportedTypeError(type_name, Library.NUMPY)
+
+
+def find_duration_type(numpy_dtype: numpy.dtype[Any]) -> Type:
+	"""
+	Return the numdaplot type of a ``timedelta64`` dtype.
+
+	numdaplot stores a time of day as the time since midnight in microseconds, and every duration in another unit.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numpy_dtype
+		A ``timedelta64`` dtype.
+
+	Returns
+	-------
+	Type
+		``TIME`` for microseconds, ``DURATION`` otherwise.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.data_types.numpy_mapping import find_duration_type
+	>>> find_duration_type(numpy.dtype("timedelta64[us]")), find_duration_type(numpy.dtype("timedelta64[s]"))
+	(<Type.TIME: 17>, <Type.DURATION: 16>)
+	"""
+	unit, _ = numpy.datetime_data(numpy_dtype)
+	if unit == TIME_UNIT:
+		return Type.TIME
+
+	return Type.DURATION
+
+
+def find_datetime_type(numpy_dtype: numpy.dtype[Any]) -> Type:
+	"""
+	Return the numdaplot type of a ``datetime64`` dtype, according to its unit.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	numpy_dtype
+		A ``datetime64`` dtype.
+
+	Returns
+	-------
+	Type
+		``DATE`` when the unit is the day, ``DATETIME`` for any other unit.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.data_types.numpy_mapping import find_datetime_type
+	>>> find_datetime_type(numpy.dtype("datetime64[s]"))
+	<Type.DATETIME: 15>
+	"""
+	datetime_unit, _ = numpy.datetime_data(numpy_dtype)
+	if datetime_unit == DAY_UNIT:
+		return Type.DATE
+
+	return Type.DATETIME

numdaplot/data_types/pandas_mapping.py

@@ -0,0 +1,114 @@
+"""
+Conversion between ``ndp.Type`` and the pandas dtypes that store Table columns.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from pandas import DatetimeTZDtype
+from pandas.api.extensions import ExtensionDtype
+from pandas.api.types import pandas_dtype
+
+from numdaplot.data_types.library import Library
+from numdaplot.data_types.type import Type
+from numdaplot.errors.unsupported_type_error import UnsupportedTypeError
+
+PANDAS_DTYPE_CODES = {
+	Type.INT8: "Int8",
+	Type.INT16: "Int16",
+	Type.INT32: "Int32",
+	Type.INT64: "Int64",
+	Type.UINT8: "UInt8",
+	Type.UINT16: "UInt16",
+	Type.UINT32: "UInt32",
+	Type.UINT64: "UInt64",
+	Type.FLOAT32: "float32",
+	Type.FLOAT64: "float64",
+	Type.BOOL: "boolean",
+	Type.TEXT: "string",
+	Type.CATEGORY: "category",
+	Type.DATE: "datetime64[s]",
+	Type.DATETIME: "datetime64[ns]",
+	Type.DURATION: "timedelta64[ns]",
+	Type.TIME: "timedelta64[us]",
+}
+NANOSECOND_UNIT = "ns"
+TYPES_BY_PANDAS_NAME = {dtype_code: data_type for data_type, dtype_code in PANDAS_DTYPE_CODES.items()}
+
+
+def to_pandas_dtype(data_type: Type) -> numpy.dtype[Any] | ExtensionDtype:
+	"""
+	Return the pandas dtype that stores a Table column of a numdaplot type.
+
+	Integers, booleans and text use the pandas types that accept missing values (``pd.NA``),
+	so a column keeps its type when it has holes. Decimals keep NaN as missing value.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	data_type
+		The numdaplot type to convert.
+
+	Returns
+	-------
+	numpy.dtype or ExtensionDtype
+		The matching pandas dtype. ``DATE`` is stored as ``datetime64[s]``,
+		since pandas has no dtype for a day without time.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.data_types.pandas_mapping import to_pandas_dtype
+	>>> to_pandas_dtype(ndp.Type.INT64)
+	Int64Dtype()
+	"""
+	dtype_code = PANDAS_DTYPE_CODES[data_type]
+	matching_dtype = pandas_dtype(dtype_code)
+
+	return matching_dtype
+
+
+def from_pandas_dtype(pandas_type: object) -> Type:
+	"""
+	Return the numdaplot type of a Table column stored with a pandas dtype.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	pandas_type
+		The dtype of a Table column, one of the dtypes given by ``to_pandas_dtype``.
+
+	Returns
+	-------
+	Type
+		The matching numdaplot type. Datetimes with a time zone, counted in nanoseconds, give ``DATETIME``.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When the dtype is not one that stores a Table column, such as ``object`` or ``complex128``.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> from numdaplot.data_types.pandas_mapping import from_pandas_dtype
+	>>> from_pandas_dtype(pandas.Int64Dtype())
+	<Type.INT64: 4>
+	>>> from_pandas_dtype(pandas.DatetimeTZDtype("ns", "Europe/Paris"))
+	<Type.DATETIME: 15>
+	"""
+	is_nanosecond_zone = isinstance(pandas_type, DatetimeTZDtype) and pandas_type.unit == NANOSECOND_UNIT
+	if is_nanosecond_zone:
+		return Type.DATETIME
+
+	dtype_name = str(pandas_type)
+	if dtype_name not in TYPES_BY_PANDAS_NAME:
+		raise UnsupportedTypeError(dtype_name, Library.PANDAS)
+
+	matching_type = TYPES_BY_PANDAS_NAME[dtype_name]
+
+	return matching_type

numdaplot/data_types/time_of_day.py

@@ -0,0 +1,292 @@
+"""
+Conversion between Python times of day and the time since midnight that stores them.
+
+.. versionadded:: 0.1.0
+"""
+
+from collections.abc import Sequence
+from datetime import time, timedelta
+from typing import Any, cast
+
+import numpy
+from numpy.typing import NDArray
+
+TIME_DTYPE = numpy.dtype("timedelta64[us]")
+PYTHON_OBJECT_DTYPE = numpy.dtype(object)
+MISSING_TIME = numpy.timedelta64("NaT", "us")
+MICROSECONDS_PER_SECOND = 1_000_000
+SECONDS_PER_MINUTE = 60
+MINUTES_PER_HOUR = 60
+
+
+def to_time_since_midnight(time_of_day: time) -> timedelta:
+	"""
+	Return the time elapsed since midnight at a time of day.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	time_of_day
+		A time without time zone.
+
+	Returns
+	-------
+	timedelta
+		The duration from midnight to the time.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> from numdaplot.data_types.time_of_day import to_time_since_midnight
+	>>> to_time_since_midnight(time(15, 35, 0, 250000))
+	datetime.timedelta(seconds=56100, microseconds=250000)
+	"""
+	since_midnight = timedelta(
+		hours=time_of_day.hour,
+		minutes=time_of_day.minute,
+		seconds=time_of_day.second,
+		microseconds=time_of_day.microsecond,
+	)
+
+	return since_midnight
+
+
+def to_time_of_day(microseconds: int) -> time:
+	"""
+	Return the time of day reached a number of microseconds after midnight.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	microseconds
+		The microseconds since midnight, less than one day.
+
+	Returns
+	-------
+	time
+		The time of day.
+
+	Examples
+	--------
+	>>> from numdaplot.data_types.time_of_day import to_time_of_day
+	>>> to_time_of_day(56100250000)
+	datetime.time(15, 35, 0, 250000)
+	"""
+	total_seconds, microsecond = divmod(microseconds, MICROSECONDS_PER_SECOND)
+	total_minutes, second = divmod(total_seconds, SECONDS_PER_MINUTE)
+	hour, minute = divmod(total_minutes, MINUTES_PER_HOUR)
+	time_of_day = time(hour, minute, second, microsecond)
+
+	return time_of_day
+
+
+def store_times(times: Sequence[object]) -> NDArray[numpy.timedelta64]:
+	"""
+	Return times of day as the time since midnight in microseconds, NaT where missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	times
+		Python times of day, and None or NaT for a missing value.
+
+	Returns
+	-------
+	NDArray[numpy.timedelta64]
+		The values in ``timedelta64[us]``.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> from numdaplot.data_types.time_of_day import store_times
+	>>> store_times([time(0, 0, 1), None])
+	array([1000000,     'NaT'], dtype='timedelta64[us]')
+	"""
+	durations = list[object]()
+	for value in times:
+		duration: object = MISSING_TIME
+		if isinstance(value, time):
+			duration = to_time_since_midnight(value)
+
+		durations.append(duration)
+
+	stored_times = numpy.array(durations, dtype=TIME_DTYPE)
+
+	return stored_times
+
+
+def read_times(values: NDArray[Any]) -> list[time | None]:
+	"""
+	Return the Python times of day of values stored as the time since midnight, None where missing.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		Values in ``timedelta64[us]``, in one dimension.
+
+	Returns
+	-------
+	list[time | None]
+		One time of day per value.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.data_types.time_of_day import read_times
+	>>> read_times(numpy.array([56100000000, "NaT"], dtype="timedelta64[us]"))
+	[datetime.time(15, 35), None]
+	"""
+	missing = numpy.isnat(values)
+	missing_flags = cast(list[bool], missing.tolist())
+	whole_values = values.astype(numpy.int64)
+	microsecond_list = cast(list[int], whole_values.tolist())
+	times = list[time | None]()
+	for microseconds, is_missing in zip(microsecond_list, missing_flags, strict=True):
+		if is_missing:
+			times.append(None)
+			continue
+
+		time_of_day = to_time_of_day(microseconds)
+		times.append(time_of_day)
+
+	return times
+
+
+def write_time(time_of_day: time) -> str:
+	"""
+	Return a time of day as a text, with its microseconds only when it has some.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	time_of_day
+		A time of day.
+
+	Returns
+	-------
+	str
+		``15:35:00``, or ``15:35:00.250000`` with microseconds.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> from numdaplot.data_types.time_of_day import write_time
+	>>> write_time(time(15, 35)), write_time(time(15, 35, 0, 250000))
+	('15:35:00', '15:35:00.250000')
+	"""
+	time_text = time_of_day.isoformat()
+
+	return time_text
+
+
+def read_time_objects(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return values stored as the time since midnight as Python times of day, in the same shape.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		Values in ``timedelta64[us]``, of any shape.
+
+	Returns
+	-------
+	NDArray
+		An object array of ``datetime.time``, None where missing.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.data_types.time_of_day import read_time_objects
+	>>> read_time_objects(numpy.array([[60000000]], dtype="timedelta64[us]"))
+	array([[datetime.time(0, 1)]], dtype=object)
+	"""
+	flat_values = values.ravel()
+	times = read_times(flat_values)
+	time_count = len(times)
+	# Some versions of the numpy stubs refuse Python objects as the values of an object array.
+	time_objects = cast(Any, numpy.empty(time_count, dtype=PYTHON_OBJECT_DTYPE))
+	time_objects[:] = times
+	shaped_objects = time_objects.reshape(values.shape)
+
+	return shaped_objects
+
+
+def holds_only_times(values: NDArray[Any]) -> bool:
+	"""
+	Return whether an object array holds Python times of day and missing values only, with at least one time.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A numpy array of any type.
+
+	Returns
+	-------
+	bool
+		True for an object array of ``datetime.time`` without time zone and None.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numpy
+	>>> from numdaplot.data_types.time_of_day import holds_only_times
+	>>> holds_only_times(numpy.array([time(8), None], dtype=object)), holds_only_times(numpy.array([1, 2]))
+	(True, False)
+	"""
+	if values.dtype != PYTHON_OBJECT_DTYPE:
+		return False
+
+	has_time = False
+	for value in values.ravel():
+		if value is None:
+			continue
+
+		is_naive_time = isinstance(value, time) and value.tzinfo is None
+		if not is_naive_time:
+			return False
+
+		has_time = True
+
+	return has_time
+
+
+def store_time_objects(values: NDArray[Any]) -> NDArray[numpy.timedelta64]:
+	"""
+	Return an object array of Python times of day as the time since midnight, in the same shape.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		An object array of ``datetime.time`` and None.
+
+	Returns
+	-------
+	NDArray[numpy.timedelta64]
+		The values in ``timedelta64[us]``, NaT where missing.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numpy
+	>>> from numdaplot.data_types.time_of_day import store_time_objects
+	>>> store_time_objects(numpy.array([time(0, 0, 1), None], dtype=object))
+	array([1000000,     'NaT'], dtype='timedelta64[us]')
+	"""
+	flat_values = values.ravel()
+	value_list = flat_values.tolist()
+	stored_times = store_times(value_list)
+	shaped_times = stored_times.reshape(values.shape)
+
+	return shaped_times