numdaplot 0.1.0__py3-none-any.whl

numdaplot/tables/files/sas_file.py

@@ -0,0 +1,94 @@
+"""
+Reading SAS data and SAS transport (XPT) files.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+from typing import Literal
+
+import pandas
+
+from numdaplot.tables.files.encoding import Encoding
+from numdaplot.tables.files.sas_read_options import SasReadOptions
+from numdaplot.tables.files.xpt_read_options import XptReadOptions
+
+SAS_DATA_FORMAT = "sas7bdat"
+SAS_TRANSPORT_FORMAT = "xport"
+
+type SasFormat = Literal["sas7bdat", "xport"]
+"""The names pandas gives to the SAS data and SAS transport formats.
+
+.. versionadded:: 0.1.0
+"""
+
+
+def read_sas_file(path: Path, options: SasReadOptions) -> pandas.DataFrame:
+	"""
+	Return the columns of a SAS data file (``.sas7bdat``).
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing SAS data file.
+	options
+		The encoding of the texts of the file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them. SAS stores every number as a decimal.
+	"""
+	frame = read_sas_format(path, SAS_DATA_FORMAT, options.encoding)
+
+	return frame
+
+
+def read_xpt_file(path: Path, options: XptReadOptions) -> pandas.DataFrame:
+	"""
+	Return the columns of a SAS transport file (``.xpt``).
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing SAS transport file.
+	options
+		The encoding of the texts of the file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them. SAS stores every number as a decimal.
+	"""
+	frame = read_sas_format(path, SAS_TRANSPORT_FORMAT, options.encoding)
+
+	return frame
+
+
+def read_sas_format(path: Path, sas_format: SasFormat, encoding: Encoding) -> pandas.DataFrame:
+	"""
+	Return the columns of a SAS file of a given format.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing SAS file.
+	sas_format
+		``sas7bdat`` for SAS data, ``xport`` for SAS transport.
+	encoding
+		The encoding of the texts of the file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them.
+	"""
+	frame = pandas.read_sas(path, format=sas_format, encoding=encoding.value)
+
+	return frame

numdaplot/tables/files/sas_read_options.py

@@ -0,0 +1,67 @@
+"""
+Settings of the SAS data files a Table reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.files.column_names import ColumnNames
+from numdaplot.tables.files.encoding import Encoding
+
+
+@dataclass(frozen=True)
+class SasReadOptions:
+	"""
+	Settings of a SAS data file (``.sas7bdat``) read by ``Table.from_sas``.
+
+	These files are read only.
+
+	The example reads
+	[airline.sas7bdat](https://github.com/Ryieru/numdaplot/blob/main/tests/data/airline.sas7bdat),
+	a SAS data file of 32 rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	encoding
+		The text encoding of the texts stored in the file, UTF-8 by default.
+	column_names
+		Whether the column names are cleaned, ``ColumnNames.CLEANED`` by default: the spaces, tabs and line breaks at
+		the start and the end of each name are removed. ``ColumnNames.KEPT`` keeps the names as written.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> latin_1 = ndp.SasReadOptions(encoding=ndp.Encoding.LATIN_1)
+	>>> airline = ndp.Table.from_sas("airline.sas7bdat", latin_1)
+	>>> airline.preview(ndp.Preview(count=3))
+	     YEAR       Y       W       R       L       K
+	  FLOAT64 FLOAT64 FLOAT64 FLOAT64 FLOAT64 FLOAT64
+	0  1948.0   1.214   0.243  0.1454   1.415   0.612
+	1  1949.0   1.354   0.260  0.2181   1.384   0.559
+	2  1950.0   1.569   0.278  0.3157   1.388   0.573
+	"""
+
+	encoding: Encoding = Encoding.UTF_8
+	column_names: ColumnNames = ColumnNames.CLEANED
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/tables/files/stata_file.py

@@ -0,0 +1,83 @@
+"""
+Reading and writing Stata files.
+
+.. versionadded:: 0.1.0
+"""
+
+from pathlib import Path
+
+import pandas
+
+from numdaplot.tables.frames.time_zones import require_no_time_zone
+
+STATA_OPERATION = "A Stata file"
+
+
+def read_stata_file(path: Path) -> pandas.DataFrame:
+	"""
+	Return the columns of a Stata file (``.dta``).
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	path
+		The path of an existing Stata file.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The columns as pandas reads them.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> from numdaplot.tables.files.stata_file import read_stata_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.dta"
+	>>> pandas.DataFrame({"price": [1.5]}).to_stata(path, write_index=False)
+	>>> read_stata_file(path)
+	   price
+	0    1.5
+	"""
+	frame = pandas.read_stata(path)
+
+	return frame
+
+
+def write_stata_file(frame: pandas.DataFrame, path: Path) -> None:
+	"""
+	Write the columns of a Table in a Stata file (``.dta``).
+
+	Stata stores integers and booleans holding missing values as decimals, and a missing text
+	as an empty text. Column names that Stata refuses, such as names with spaces, are changed
+	by pandas with a warning.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	path
+		The path of the file, replaced when it exists.
+
+	Raises
+	------
+	TimeZoneMismatchError
+		When a column holds datetimes with a time zone, which Stata files cannot store.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import pandas
+	>>> from numdaplot.tables.files.stata_file import write_stata_file
+	>>> path = Path(tempfile.mkdtemp()) / "sales.dta"
+	>>> write_stata_file(pandas.DataFrame({"price": [1.5]}), path)
+	>>> path.exists()
+	True
+	"""
+	require_no_time_zone(frame, STATA_OPERATION)
+	frame.to_stata(path, write_index=False)

numdaplot/tables/files/stata_read_options.py

@@ -0,0 +1,56 @@
+r"""
+Settings of the Stata files a Table reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.files.column_names import ColumnNames
+
+
+@dataclass(frozen=True)
+class StataReadOptions:
+	r"""
+	Settings of a Stata file (``.dta``) read by ``Table.from_stata``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column_names
+		Whether the column names are cleaned, ``ColumnNames.CLEANED`` by default: the spaces, tabs and line breaks at
+		the start and the end of each name are removed. ``ColumnNames.KEPT`` keeps the names as written.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import tempfile
+	>>> from pathlib import Path
+	>>> import numdaplot as ndp
+	>>> path = Path(tempfile.mkdtemp()) / "sales.dta"
+	>>> ndp.Table.from_arrays({"price": ndp.Array.from_list([1.5])}).to_stata(path)
+	>>> options = ndp.StataReadOptions(column_names=ndp.ColumnNames.KEPT)
+	>>> ndp.Table.from_stata(path, options).column_names
+	['price']
+	"""
+
+	column_names: ColumnNames = ColumnNames.CLEANED
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/tables/files/xpt_read_options.py

@@ -0,0 +1,65 @@
+"""
+Settings of the SAS transport (XPT) files a Table reads.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.files.column_names import ColumnNames
+from numdaplot.tables.files.encoding import Encoding
+
+
+@dataclass(frozen=True)
+class XptReadOptions:
+	"""
+	Settings of a SAS transport (XPT) file (``.xpt``) read by ``Table.from_xpt``.
+
+	These files are read only.
+
+	The example reads
+	[paxraw_d_short.xpt](https://github.com/Ryieru/numdaplot/blob/main/tests/data/paxraw_d_short.xpt),
+	a SAS transport file of 100 rows.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	encoding
+		The text encoding of the texts stored in the file, UTF-8 by default.
+	column_names
+		Whether the column names are cleaned, ``ColumnNames.CLEANED`` by default: the spaces, tabs and line breaks at
+		the start and the end of each name are removed. ``ColumnNames.KEPT`` keeps the names as written.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> latin_1 = ndp.XptReadOptions(encoding=ndp.Encoding.LATIN_1)
+	>>> activity = ndp.Table.from_xpt("paxraw_d_short.xpt", latin_1)
+	>>> activity.row_count
+	100
+	>>> activity.column_names
+	['SEQN', 'PAXSTAT', 'PAXCAL', 'PAXDAY', 'PAXN', 'PAXHOUR', 'PAXMINUT', 'PAXINTEN', 'PAXSTEP']
+	"""
+
+	encoding: Encoding = Encoding.UTF_8
+	column_names: ColumnNames = ColumnNames.CLEANED
+
+	def __post_init__(self) -> None:
+		"""
+		Check the type of every setting.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		"""
+		require_field_types(self)

numdaplot/tables/filtering/__init__.py

@@ -0,0 +1,5 @@
+"""
+Filters keeping the rows of a Table that satisfy conditions.
+
+.. versionadded:: 0.1.0
+"""

numdaplot/tables/filtering/checked_frame.py

@@ -0,0 +1,60 @@
+"""
+Values of a Table satisfying a rule.
+
+.. versionadded:: 0.1.0
+"""
+
+import pandas
+
+from numdaplot.rules.rule import Rule
+from numdaplot.tables.filtering.column_mask import build_column_mask
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import build_column
+
+
+def check_frame(frame: pandas.DataFrame, rule: Rule) -> pandas.DataFrame:
+	"""
+	Return which values of every column of a Table satisfy a rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	frame
+		The columns of a Table.
+	rule
+		Any rule of numdaplot. A missing value only satisfies ``IsMissing``.
+
+	Returns
+	-------
+	pandas.DataFrame
+		The same column names and rows, each value replaced by True or False.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the rule does not apply to the type of one of the columns.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.checked_frame import check_frame
+	>>> check_frame(pandas.DataFrame({"price": [1.5, None]}), ndp.IsMissing())
+	   price
+	0  False
+	1   True
+	"""
+	checked_columns = dict[str, Column]()
+
+	for column_name in frame.columns:
+		column = frame[column_name]
+		column_mask = build_column_mask(column, rule)
+		checked_name = str(column_name)
+		checked_columns[checked_name] = build_column(column_mask)
+
+	row_count = len(frame)
+	row_numbers = pandas.RangeIndex(row_count)
+	checked = pandas.DataFrame(checked_columns, index=row_numbers)
+
+	return checked

numdaplot/tables/filtering/column_mask.py

@@ -0,0 +1,71 @@
+"""
+Rows of a Table column satisfying a rule.
+
+.. versionadded:: 0.1.0
+"""
+
+import numpy
+from numpy.typing import NDArray
+
+from numdaplot.arrays.selection.rule_mask import build_rule_mask
+from numdaplot.rules.is_missing import IsMissing
+from numdaplot.rules.is_present import IsPresent
+from numdaplot.rules.rule import Rule
+from numdaplot.tables.filtering.rule_moments import match_rule_time_zone
+from numdaplot.tables.frames.column import Column
+from numdaplot.tables.frames.column_values import find_column_missing, read_present_values
+from numdaplot.tables.frames.named_column_errors import NamedColumnErrors
+from numdaplot.tables.frames.time_zones import find_column_time_zone
+
+
+def build_column_mask(column: Column, rule: Rule) -> NDArray[numpy.bool_]:
+	"""
+	Return which values of a Table column satisfy a rule.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	column
+		A Table column.
+	rule
+		Any rule of numdaplot. A missing value only satisfies ``IsMissing``.
+
+	Returns
+	-------
+	NDArray[numpy.bool_]
+		True at each row whose value satisfies the rule.
+
+	Raises
+	------
+	IncompatibleTypesError
+		When the rule does not apply to the type of the column.
+	TimeZoneMismatchError
+		When a datetime of the rule has a time zone and the column has none, or the reverse.
+
+	Examples
+	--------
+	>>> import pandas
+	>>> import numdaplot as ndp
+	>>> from numdaplot.tables.filtering.column_mask import build_column_mask
+	>>> build_column_mask(pandas.Series([5, None, 12], dtype="Int64"), ndp.Greater(10))
+	array([False, False,  True])
+	"""
+	missing = find_column_missing(column)
+	if isinstance(rule, IsMissing):
+		return missing
+
+	present = ~missing
+	if isinstance(rule, IsPresent):
+		return present
+
+	time_zone = find_column_time_zone(column)
+	matched_rule = match_rule_time_zone(rule, time_zone)
+	present_values = read_present_values(column)
+	with NamedColumnErrors(column):
+		present_mask = build_rule_mask(present_values, matched_rule)
+
+	mask = numpy.zeros(missing.shape, dtype=numpy.bool_)
+	mask[present] = present_mask
+
+	return mask

numdaplot/tables/filtering/column_match.py

@@ -0,0 +1,62 @@
+"""
+How the columns of a Condition combine.
+
+.. versionadded:: 0.1.0
+"""
+
+from enum import Enum, auto
+
+
+class ColumnMatch(Enum):
+	"""
+	How the columns of a ``Condition`` combine to satisfy it.
+
+	.. versionadded:: 0.1.0
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> low = ndp.Array.from_list([1.0, 5.0, 20.0])
+	>>> high = ndp.Array.from_list([2.0, 30.0, 40.0])
+	>>> ranges = ndp.Table.from_arrays({"low": low, "high": high})
+	>>> above_ten = ndp.Condition(rule=ndp.Greater(10), mode=ndp.ColumnMatch.ALL)
+	>>> ranges.filter(ndp.Filter(conditions=[above_ten]))
+	      low    high
+	  FLOAT64 FLOAT64
+	0    20.0    40.0
+	"""
+
+	ANY = auto()
+	"""
+	A row satisfies the condition when at least one of the columns satisfies the rule. Default value.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> low = ndp.Array.from_list([1.0, 5.0, 20.0])
+	>>> high = ndp.Array.from_list([2.0, 30.0, 40.0])
+	>>> ranges = ndp.Table.from_arrays({"low": low, "high": high})
+	>>> above_ten = ndp.Condition(rule=ndp.Greater(10), mode=ndp.ColumnMatch.ANY)
+	>>> ranges.filter(ndp.Filter(conditions=[above_ten]))
+	      low    high
+	  FLOAT64 FLOAT64
+	0     5.0    30.0
+	1    20.0    40.0
+	"""
+
+	ALL = auto()
+	"""
+	A row satisfies the condition when every column satisfies the rule.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> low = ndp.Array.from_list([1.0, 5.0, 20.0])
+	>>> high = ndp.Array.from_list([2.0, 30.0, 40.0])
+	>>> ranges = ndp.Table.from_arrays({"low": low, "high": high})
+	>>> above_ten = ndp.Condition(rule=ndp.Greater(10), mode=ndp.ColumnMatch.ALL)
+	>>> ranges.filter(ndp.Filter(conditions=[above_ten]))
+	      low    high
+	  FLOAT64 FLOAT64
+	0    20.0    40.0
+	"""

numdaplot/tables/filtering/condition.py

@@ -0,0 +1,94 @@
+"""
+A rule applied to one or several columns of a Table.
+
+.. versionadded:: 0.1.0
+"""
+
+from dataclasses import dataclass
+
+from numdaplot.errors.empty_list_error import EmptyListError
+from numdaplot.rules.rule import Rule
+from numdaplot.settings.field_types import require_field_types
+from numdaplot.tables.columns.column_names import require_column_names
+from numdaplot.tables.filtering.column_match import ColumnMatch
+
+COLUMN_ITEM_NAME = "column"
+
+
+@dataclass(frozen=True)
+class Condition:
+	"""
+	A rule applied to one or several columns of a Table, used by ``Filter``.
+
+	A missing value only satisfies ``IsMissing``.
+
+	.. versionadded:: 0.1.0
+
+	Parameters
+	----------
+	rule
+		A ``Rule``, such as ``ndp.Greater(100)`` or ``ndp.IsIn(["Paris"])``: see ``Rule`` for every rule.
+	columns
+		The names of the columns the rule applies to, every column when omitted.
+		The condition keeps its own copy of the list.
+	mode
+		Whether one column satisfying the rule is enough, ``ColumnMatch.ANY`` by default, or every column must,
+		``ColumnMatch.ALL``.
+
+	Raises
+	------
+	InvalidTypeError
+		When a setting is not of the type its annotation names.
+	EmptyListError
+		When ``columns`` is an empty list.
+	InvalidColumnNameError
+		When a column name is an empty text.
+	DuplicateColumnError
+		When a column name appears twice.
+
+	Examples
+	--------
+	>>> import numdaplot as ndp
+	>>> prices = ndp.Array.from_list([120.0, 80.0, 90.0])
+	>>> costs = ndp.Array.from_list([70.0, 60.0, 110.0])
+	>>> sales = ndp.Table.from_arrays({"price": prices, "cost": costs})
+	>>> above_hundred = ndp.Condition(rule=ndp.Greater(100), columns=["price", "cost"])
+	>>> sales.filter(ndp.Filter(conditions=[above_hundred]))
+	    price    cost
+	  FLOAT64 FLOAT64
+	0   120.0    70.0
+	1    90.0   110.0
+	"""
+
+	rule: Rule
+	columns: list[str] | None = None
+	mode: ColumnMatch = ColumnMatch.ANY
+
+	def __post_init__(self) -> None:
+		"""
+		Check the columns and replace them with a copy that only the condition holds.
+
+		.. versionadded:: 0.1.0
+
+		Raises
+		------
+		InvalidTypeError
+			When a setting is not of the type its annotation names.
+		EmptyListError
+			When ``columns`` is an empty list.
+		InvalidColumnNameError
+			When a column name is an empty text.
+		DuplicateColumnError
+			When a column name appears twice.
+		"""
+		require_field_types(self)
+
+		if self.columns is None:
+			return
+
+		if self.columns == []:
+			raise EmptyListError(COLUMN_ITEM_NAME)
+
+		require_column_names(self.columns)
+		columns_copy = list(self.columns)
+		object.__setattr__(self, "columns", columns_copy)