numdaplot 0.1.0__py3-none-any.whl

numdaplot/arrays/creation/list_conversion.py

@@ -0,0 +1,311 @@
+"""
+Conversion of Python values to numpy values of a numdaplot type.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.creation.list_shape import find_list_shape, flatten_list
+from numdaplot.arrays.operations.time_bounds import require_stored_times_fit
+from numdaplot.data_types.numpy_mapping import to_numpy_dtype
+from numdaplot.data_types.time_of_day import MISSING_TIME, store_times
+from numdaplot.data_types.type import Type
+from numdaplot.data_types.value_type import find_common_type, find_value_type
+from numdaplot.errors.missing_type_error import MissingTypeError
+from numdaplot.errors.unsupported_missing_error import UnsupportedMissingError
+from numdaplot.errors.value_conversion_error import ValueConversionError
+
+FROM_LIST_OPERATION = "from_list"
+SAFE_CASTING = "same_kind"
+WHOLE_NUMBER_KINDS = frozenset({"i", "u"})
+NOT_A_TIME = "NaT"
+NANOSECOND_UNIT = "ns"
+MISSING_MARKERS = {
+	Type.FLOAT32: numpy.nan,
+	Type.FLOAT64: numpy.nan,
+	Type.TEXT: numpy.nan,
+	Type.DATE: numpy.datetime64(NOT_A_TIME, NANOSECOND_UNIT),
+	Type.DATETIME: numpy.datetime64(NOT_A_TIME, NANOSECOND_UNIT),
+	Type.DURATION: numpy.timedelta64(NOT_A_TIME, NANOSECOND_UNIT),
+	Type.TIME: MISSING_TIME,
+}
+
+
+def convert_list(values: list[object], dtype: Type | None) -> NDArray[Any]:
+	"""
+	Return the numpy values of nested Python lists, stored as a numdaplot type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A list of single values or of nested lists. ``None`` is a missing value.
+	dtype
+		The type to store the values as, guessed from the values when ``None``.
+
+	Returns
+	-------
+	NDArray
+		The values, with one dimension per nesting level.
+
+	Raises
+	------
+	IrregularListError
+		When nested lists do not form a regular block.
+	IncompatibleTypesError
+		When the values mix several families of types, such as numbers and texts.
+	MissingTypeError
+		When ``dtype`` is ``None`` and there is no present value to guess the type from.
+	UnsupportedMissingError
+		When a value is missing and the type cannot hold missing values.
+	ValueConversionError
+		When the values cannot be stored as ``dtype`` without losing information.
+	TimeOverflowError
+		When a value stored as ``DATETIME`` or ``DURATION`` is outside the range of nanoseconds.
+
+	Examples
+	--------
+	>>> from numdaplot.arrays.creation.list_conversion import convert_list
+	>>> convert_list([[1, 2], [3, 4.5]], None)
+	array([[1. , 2. ],
+	       [3. , 4.5]])
+	"""
+	dimensions = find_list_shape(values)
+	single_values = flatten_list(values)
+	guessed_type = guess_list_type(single_values)
+	stored_type = choose_stored_type(guessed_type, dtype)
+	require_stored_times_fit(single_values, stored_type, FROM_LIST_OPERATION)
+	marked_values = mark_missing_values(single_values, stored_type)
+	stored_values = store_values(marked_values, guessed_type, stored_type)
+	shaped_values = stored_values.reshape(dimensions)
+
+	return shaped_values
+
+
+def guess_list_type(single_values: list[object]) -> Type | None:
+	"""
+	Return the type holding every present value of a flat list.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	single_values
+		Single values, ``None`` being a missing value.
+
+	Returns
+	-------
+	Type or None
+		The common type of the present values, or ``None`` when no value is present.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the values mix several families of types.
+
+	Examples
+	--------
+	>>> from numdaplot.arrays.creation.list_conversion import guess_list_type
+	>>> guess_list_type([1, None, 2.5])
+	<Type.FLOAT64: 10>
+	"""
+	value_types = [find_value_type(value) for value in single_values if value is not None]
+	type_count = len(value_types)
+	if type_count == 0:
+		return None
+
+	common_type = find_common_type(value_types, FROM_LIST_OPERATION)
+
+	return common_type
+
+
+def choose_stored_type(guessed_type: Type | None, dtype: Type | None) -> Type:
+	"""
+	Return the type the values are stored as: the given one, or else the guessed one.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	guessed_type
+		The type guessed from the present values, ``None`` when no value is present.
+	dtype
+		The type given by the user, ``None`` when omitted.
+
+	Returns
+	-------
+	Type
+		``dtype`` when given, otherwise ``guessed_type``.
+
+	Raises
+	------
+	MissingTypeError
+		When both types are ``None``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.list_conversion import choose_stored_type
+	>>> choose_stored_type(ndp.Type.INT64, ndp.Type.FLOAT32)
+	<Type.FLOAT32: 9>
+	"""
+	if dtype is not None:
+		return dtype
+
+	if guessed_type is None:
+		raise MissingTypeError()
+
+	return guessed_type
+
+
+def mark_missing_values(single_values: list[object], stored_type: Type) -> list[object]:
+	"""
+	Replace each ``None`` with the missing value marker of a type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	single_values
+		Single values, ``None`` being a missing value.
+	stored_type
+		The type the values are stored as.
+
+	Returns
+	-------
+	list[object]
+		The values, with NaN for decimals and NaT for dates and durations instead of ``None``.
+
+	Raises
+	------
+	UnsupportedMissingError
+		When a value is missing and the type has no missing value marker.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.list_conversion import mark_missing_values
+	>>> mark_missing_values([1.5, None], ndp.Type.FLOAT64)
+	[1.5, nan]
+	"""
+	has_missing_value = None in single_values
+	if not has_missing_value:
+		return single_values
+
+	if stored_type not in MISSING_MARKERS:
+		raise UnsupportedMissingError(stored_type.name)
+
+	missing_marker = MISSING_MARKERS[stored_type]
+	marked_values = [missing_marker if value is None else value for value in single_values]
+
+	return marked_values
+
+
+def store_values(marked_values: list[object], guessed_type: Type | None, stored_type: Type) -> NDArray[Any]:
+	"""
+	Return the values as a flat numpy array of the stored type.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	marked_values
+		Single values whose missing values are already replaced with markers.
+	guessed_type
+		The type guessed from the present values, ``None`` when no value is present.
+	stored_type
+		The type the values are stored as.
+
+	Returns
+	-------
+	NDArray
+		A one-dimensional array of the stored type.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When the stored type has no numpy equivalent, which is the case of ``CATEGORY``.
+	ValueConversionError
+		When the guessed type cannot be stored as the stored type without losing information,
+		or when a value exceeds the range of the stored type, such as -1 stored as ``UINT8``.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.list_conversion import store_values
+	>>> store_values([1, 2], ndp.Type.INT64, ndp.Type.FLOAT64)
+	array([1., 2.])
+	>>> store_values([1, 2], ndp.Type.INT64, ndp.Type.UINT8)
+	array([1, 2], dtype=uint8)
+	"""
+	if Type.TIME in (guessed_type, stored_type):
+		time_values = store_time_values(marked_values, guessed_type, stored_type)
+		return time_values
+
+	stored_dtype = to_numpy_dtype(stored_type)
+	if guessed_type is None:
+		values_without_present_value = numpy.array(marked_values, dtype=stored_dtype)
+		return values_without_present_value
+
+	guessed_dtype = to_numpy_dtype(guessed_type)
+	is_safe = numpy.can_cast(guessed_dtype, stored_dtype, casting=SAFE_CASTING)
+	# Integers may be stored as unsigned integers: numpy then rejects each value out of range.
+	is_whole_number_storage = guessed_dtype.kind in WHOLE_NUMBER_KINDS and stored_dtype.kind in WHOLE_NUMBER_KINDS
+	is_storable = is_safe or is_whole_number_storage
+	if not is_storable:
+		raise ValueConversionError(guessed_type.name, stored_type.name)
+
+	try:
+		stored_values = numpy.array(marked_values, dtype=stored_dtype)
+	except OverflowError as error:
+		raise ValueConversionError(guessed_type.name, stored_type.name) from error
+
+	return stored_values
+
+
+def store_time_values(marked_values: list[object], guessed_type: Type | None, stored_type: Type) -> NDArray[Any]:
+	"""
+	Return times of day stored as ``TIME``, refusing to store them as another type or other values as ``TIME``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	marked_values
+		The values, missing ones already replaced by NaT.
+	guessed_type
+		The type of the present values, ``None`` when no value is present.
+	stored_type
+		The type to store the values as.
+
+	Returns
+	-------
+	NDArray
+		The times since midnight in ``timedelta64[us]``.
+
+	Raises
+	------
+	ValueConversionError
+		When times of day are stored as another type, or other values as ``TIME``.
+
+	Examples
+	--------
+	>>> from datetime import time
+	>>> import numdaplot as ndp
+	>>> from numdaplot.arrays.creation.list_conversion import store_time_values
+	>>> store_time_values([time(0, 1)], ndp.Type.TIME, ndp.Type.TIME)
+	array([60000000], dtype='timedelta64[us]')
+	"""
+	is_time_storage = stored_type == Type.TIME and guessed_type in (Type.TIME, None)
+	if not is_time_storage:
+		guessed_name = stored_type.name if guessed_type is None else guessed_type.name
+		raise ValueConversionError(guessed_name, stored_type.name)
+
+	time_values = store_times(marked_values)
+
+	return time_values

numdaplot/arrays/creation/list_shape.py

@@ -0,0 +1,97 @@
+"""
+Shape and values of nested Python lists.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import cast
+
+from numdaplot.errors.irregular_list_error import IrregularListError
+
+EMPTY_LIST_DIMENSIONS = (0,)
+
+
+def find_list_shape(values: list[object]) -> tuple[int, ...]:
+	"""
+	Return the dimensions of nested lists forming a regular block.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A list of single values, or a list of lists nested to any depth.
+
+	Returns
+	-------
+	tuple[int, ...]
+		The number of elements at each nesting level.
+
+	Raises
+	------
+	IrregularListError
+		When the lists at one level have different lengths, or mix lists and single values.
+
+	Examples
+	--------
+	>>> from numdaplot.arrays.creation.list_shape import find_list_shape
+	>>> find_list_shape([[1, 2, 3], [4, 5, 6]])
+	(2, 3)
+	"""
+	value_count = len(values)
+	if value_count == 0:
+		return EMPTY_LIST_DIMENSIONS
+
+	nested_lists = [cast(list[object], value) for value in values if isinstance(value, list)]
+	nested_list_count = len(nested_lists)
+	if nested_list_count == 0:
+		return (value_count,)
+
+	if nested_list_count != value_count:
+		raise IrregularListError()
+
+	nested_shapes = {find_list_shape(nested_list) for nested_list in nested_lists}
+	shape_count = len(nested_shapes)
+	if shape_count != 1:
+		raise IrregularListError()
+
+	nested_shape = nested_shapes.pop()
+	dimensions = (value_count, *nested_shape)
+
+	return dimensions
+
+
+def flatten_list(values: list[object]) -> list[object]:
+	"""
+	Return the single values of nested lists, row after row.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A list of single values, or a list of lists nested to any depth.
+
+	Returns
+	-------
+	list[object]
+		Every single value, in reading order.
+
+	Examples
+	--------
+	>>> from numdaplot.arrays.creation.list_shape import flatten_list
+	>>> flatten_list([[1, 2], [3, 4]])
+	[1, 2, 3, 4]
+	"""
+	single_values = list[object]()
+
+	for value in values:
+		if isinstance(value, list):
+			nested_list = cast(list[object], value)
+			nested_values = flatten_list(nested_list)
+			single_values.extend(nested_values)
+			continue
+
+		single_values.append(value)
+
+	return single_values

numdaplot/arrays/creation/normal.py

@@ -0,0 +1,65 @@
+"""
+Normal distribution of decimals.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.arrays.creation.distribution import Distribution
+from numdaplot.errors.invalid_deviation_error import InvalidDeviationError
+from numdaplot.settings.field_types import require_field_types
+
+LOWEST_DEVIATION = 0
+
+
+@dataclass(frozen=True)
+class Normal(Distribution):
+	"""
+	Decimals drawn around a mean, following a bell curve.
+
+	About 68 % of the values fall within one standard deviation of the mean.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	mean
+		Center of the bell curve.
+	deviation
+		Standard deviation, how far the values spread around the mean, at least 0.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	InvalidDeviationError
+		When ``deviation`` is lower than 0.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> ndp.Array.random(ndp.Normal(mean=170, deviation=10), shape=ndp.Shape([3]), seed=0)
+	Array([171.25730221, 168.67895137, 176.4042265 ], dtype=FLOAT64)
+	"""
+
+	mean: float
+	deviation: float
+
+	def __post_init__(self) -> None:
+		"""
+		Check that the standard deviation is not negative.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		InvalidDeviationError
+			When ``deviation`` is lower than 0.
+		"""
+		require_field_types(self)
+
+		if self.deviation < LOWEST_DEVIATION:
+			raise InvalidDeviationError(self.deviation)

numdaplot/arrays/creation/numpy_conversion.py

@@ -0,0 +1,149 @@
+"""
+Conversion of numpy arrays to the values stored by an Array.
+
+.. versionadded:: 0.1.0
+"""
+
+from typing import Any
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.data_types.numpy_mapping import from_numpy_dtype, to_numpy_dtype
+from numdaplot.data_types.time_of_day import TIME_DTYPE, holds_only_times, store_time_objects
+from numdaplot.data_types.type import Type
+from numdaplot.errors.time_overflow_error import TimeOverflowError
+
+TEXT_KINDS = frozenset({"U", "T"})
+NANOSECOND_DURATION_DTYPE = numpy.dtype("timedelta64[ns]")
+FROM_NUMPY_OPERATION = "from_numpy"
+
+
+def copy_numpy_values(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return a copy of a numpy array that an Array can store.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A numpy array of a type numdaplot supports.
+
+	Returns
+	-------
+	NDArray
+		An independent copy, with texts stored as variable-length texts with NaN as missing value. An object
+		array of Python times of day gives times of day, and durations in microseconds give nanoseconds, as
+		microseconds store the times of day.
+
+	Raises
+	------
+	UnsupportedTypeError
+		When numdaplot has no equivalent type, for example complex numbers or other Python objects.
+	TimeOverflowError
+		When a duration in microseconds is beyond about 292 years, which nanoseconds cannot hold.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.creation.numpy_conversion import copy_numpy_values
+	>>> copy_numpy_values(numpy.array(["a", "bc"])).dtype
+	StringDType(na_object=nan)
+	"""
+	if holds_only_times(values):
+		time_values = store_time_objects(values)
+		return time_values
+
+	from_numpy_dtype(values.dtype)
+	copied_values = values.copy()
+	duration_values = normalize_durations(copied_values)
+	normalized_values = normalize_text(duration_values)
+
+	return normalized_values
+
+
+def normalize_text(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return values whose texts are stored with the numpy type of every ``TEXT`` Array.
+
+	Fixed-length texts become variable-length texts, and any other marker of a missing text becomes NaN.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A numpy array of any type.
+
+	Returns
+	-------
+	NDArray
+		The same array when it holds no text or already has this type, otherwise a converted copy.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.creation.numpy_conversion import normalize_text
+	>>> normalize_text(numpy.array(["a"])).dtype
+	StringDType(na_object=nan)
+	>>> marked_with_none = numpy.dtypes.StringDType(na_object=None)
+	>>> normalize_text(numpy.array(["a", None], dtype=marked_with_none))
+	array(['a', nan], dtype=StringDType(na_object=nan))
+	"""
+	if values.dtype.kind not in TEXT_KINDS:
+		return values
+
+	text_dtype = to_numpy_dtype(Type.TEXT)
+	if values.dtype == text_dtype:
+		return values
+
+	text_values = values.astype(text_dtype)
+
+	return text_values
+
+
+def normalize_durations(values: NDArray[Any]) -> NDArray[Any]:
+	"""
+	Return durations in microseconds as nanoseconds, since microseconds store the times of day.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	values
+		A numpy array of any type.
+
+	Returns
+	-------
+	NDArray
+		The same array unless it holds durations in microseconds, which become nanoseconds.
+
+	Raises
+	------
+	TimeOverflowError
+		When a duration is beyond about 292 years, which nanoseconds cannot hold.
+
+	Examples
+	--------
+	>>> import numpy
+	>>> from numdaplot.arrays.creation.numpy_conversion import normalize_durations
+	>>> normalize_durations(numpy.array([1, "NaT"], dtype="timedelta64[us]"))
+	array([ 1000, 'NaT'], dtype='timedelta64[ns]')
+	"""
+	if values.dtype != TIME_DTYPE:
+		return values
+
+	try:
+		nanosecond_values = values.astype(NANOSECOND_DURATION_DTYPE)
+	except OverflowError as error:
+		raise TimeOverflowError(FROM_NUMPY_OPERATION, Type.DURATION.name) from error
+
+	# Some versions of numpy wrap a value beyond the range of nanoseconds instead of raising.
+	microsecond_values = nanosecond_values.astype(TIME_DTYPE)
+	is_kept = (microsecond_values == values) | numpy.isnat(values)
+	is_exact = bool(is_kept.all())
+	if not is_exact:
+		raise TimeOverflowError(FROM_NUMPY_OPERATION, Type.DURATION.name)
+
+	return nanosecond_values