Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified
📁 ..	-	2026-03-21 15:45
📄 __init__.py """ Note: almost all functions in the ``numpy.lib`` namespace are also present in the main ``numpy`` namespace. Please use the functions as ``np.<funcname>`` where possible. ``numpy.lib`` is mostly a space for implementing functions that don't belong in core or in another NumPy submodule with a clear purpose (e.g. ``random``, ``fft``, ``linalg``, ``ma``). Most contains basic functions that are used by several submodules and are useful to have in the main name-space. """ from numpy.version import version as __version__ # Public submodules # Note: recfunctions and (maybe) format are public too, but not imported from . import mixins from . import scimath as emath # Private submodules # load module names. See https://github.com/networkx/networkx/issues/5838 from . import type_check from . import index_tricks from . import function_base from . import nanfunctions from . import shape_base from . import stride_tricks from . import twodim_base from . import ufunclike from . import histograms from . import polynomial from . import utils from . import arraysetops from . import npyio from . import arrayterator from . import arraypad from . import _version from .type_check import * from .index_tricks import * from .function_base import * from .nanfunctions import * from .shape_base import * from .stride_tricks import * from .twodim_base import * from .ufunclike import * from .histograms import * from .polynomial import * from .utils import * from .arraysetops import * from .npyio import * from .arrayterator import Arrayterator from .arraypad import * from ._version import * from numpy.core._multiarray_umath import tracemalloc_domain __all__ = ['emath', 'tracemalloc_domain', 'Arrayterator'] __all__ += type_check.__all__ __all__ += index_tricks.__all__ __all__ += function_base.__all__ __all__ += shape_base.__all__ __all__ += stride_tricks.__all__ __all__ += twodim_base.__all__ __all__ += ufunclike.__all__ __all__ += arraypad.__all__ __all__ += polynomial.__all__ __all__ += utils.__all__ __all__ += arraysetops.__all__ __all__ += npyio.__all__ __all__ += nanfunctions.__all__ __all__ += histograms.__all__ from numpy._pytesttester import PytestTester test = PytestTester(__name__) del PytestTester def __getattr__(attr): # Warn for reprecated attributes import math import warnings if attr == 'math': warnings.warn( "`np.lib.math` is a deprecated alias for the standard library " "`math` module (Deprecated Numpy 1.25). Replace usages of " "`numpy.lib.math` with `math`", DeprecationWarning, stacklevel=2) return math else: raise AttributeError("module {!r} has no attribute " "{!r}".format(__name__, attr))	2.7 KB	2026-01-20 12:58
📄 __init__.pyi import math as math from typing import Any from numpy._pytesttester import PytestTester from numpy import ( ndenumerate as ndenumerate, ndindex as ndindex, ) from numpy.version import version from numpy.lib import ( format as format, mixins as mixins, scimath as scimath, stride_tricks as stride_tricks, ) from numpy.lib._version import ( NumpyVersion as NumpyVersion, ) from numpy.lib.arraypad import ( pad as pad, ) from numpy.lib.arraysetops import ( ediff1d as ediff1d, intersect1d as intersect1d, setxor1d as setxor1d, union1d as union1d, setdiff1d as setdiff1d, unique as unique, in1d as in1d, isin as isin, ) from numpy.lib.arrayterator import ( Arrayterator as Arrayterator, ) from numpy.lib.function_base import ( select as select, piecewise as piecewise, trim_zeros as trim_zeros, copy as copy, iterable as iterable, percentile as percentile, diff as diff, gradient as gradient, angle as angle, unwrap as unwrap, sort_complex as sort_complex, disp as disp, flip as flip, rot90 as rot90, extract as extract, place as place, vectorize as vectorize, asarray_chkfinite as asarray_chkfinite, average as average, bincount as bincount, digitize as digitize, cov as cov, corrcoef as corrcoef, median as median, sinc as sinc, hamming as hamming, hanning as hanning, bartlett as bartlett, blackman as blackman, kaiser as kaiser, trapz as trapz, i0 as i0, add_newdoc as add_newdoc, add_docstring as add_docstring, meshgrid as meshgrid, delete as delete, insert as insert, append as append, interp as interp, add_newdoc_ufunc as add_newdoc_ufunc, quantile as quantile, ) from numpy.lib.histograms import ( histogram_bin_edges as histogram_bin_edges, histogram as histogram, histogramdd as histogramdd, ) from numpy.lib.index_tricks import ( ravel_multi_index as ravel_multi_index, unravel_index as unravel_index, mgrid as mgrid, ogrid as ogrid, r_ as r_, c_ as c_, s_ as s_, index_exp as index_exp, ix_ as ix_, fill_diagonal as fill_diagonal, diag_indices as diag_indices, diag_indices_from as diag_indices_from, ) from numpy.lib.nanfunctions import ( nansum as nansum, nanmax as nanmax, nanmin as nanmin, nanargmax as nanargmax, nanargmin as nanargmin, nanmean as nanmean, nanmedian as nanmedian, nanpercentile as nanpercentile, nanvar as nanvar, nanstd as nanstd, nanprod as nanprod, nancumsum as nancumsum, nancumprod as nancumprod, nanquantile as nanquantile, ) from numpy.lib.npyio import ( savetxt as savetxt, loadtxt as loadtxt, genfromtxt as genfromtxt, recfromtxt as recfromtxt, recfromcsv as recfromcsv, load as load, save as save, savez as savez, savez_compressed as savez_compressed, packbits as packbits, unpackbits as unpackbits, fromregex as fromregex, DataSource as DataSource, ) from numpy.lib.polynomial import ( poly as poly, roots as roots, polyint as polyint, polyder as polyder, polyadd as polyadd, polysub as polysub, polymul as polymul, polydiv as polydiv, polyval as polyval, polyfit as polyfit, RankWarning as RankWarning, poly1d as poly1d, ) from numpy.lib.shape_base import ( column_stack as column_stack, row_stack as row_stack, dstack as dstack, array_split as array_split, split as split, hsplit as hsplit, vsplit as vsplit, dsplit as dsplit, apply_over_axes as apply_over_axes, expand_dims as expand_dims, apply_along_axis as apply_along_axis, kron as kron, tile as tile, get_array_wrap as get_array_wrap, take_along_axis as take_along_axis, put_along_axis as put_along_axis, ) from numpy.lib.stride_tricks import ( broadcast_to as broadcast_to, broadcast_arrays as broadcast_arrays, broadcast_shapes as broadcast_shapes, ) from numpy.lib.twodim_base import ( diag as diag, diagflat as diagflat, eye as eye, fliplr as fliplr, flipud as flipud, tri as tri, triu as triu, tril as tril, vander as vander, histogram2d as histogram2d, mask_indices as mask_indices, tril_indices as tril_indices, tril_indices_from as tril_indices_from, triu_indices as triu_indices, triu_indices_from as triu_indices_from, ) from numpy.lib.type_check import ( mintypecode as mintypecode, asfarray as asfarray, real as real, imag as imag, iscomplex as iscomplex, isreal as isreal, iscomplexobj as iscomplexobj, isrealobj as isrealobj, nan_to_num as nan_to_num, real_if_close as real_if_close, typename as typename, common_type as common_type, ) from numpy.lib.ufunclike import ( fix as fix, isposinf as isposinf, isneginf as isneginf, ) from numpy.lib.utils import ( issubclass_ as issubclass_, issubsctype as issubsctype, issubdtype as issubdtype, deprecate as deprecate, deprecate_with_doc as deprecate_with_doc, get_include as get_include, info as info, source as source, who as who, lookfor as lookfor, byte_bounds as byte_bounds, safe_eval as safe_eval, show_runtime as show_runtime, ) from numpy.core.multiarray import ( tracemalloc_domain as tracemalloc_domain, ) __all__: list[str] __path__: list[str] test: PytestTester __version__ = version emath = scimath	5.46 KB	2026-01-20 12:58
📁 __pycache__	-	2026-03-21 15:45
📄 _datasource.py """A file interface for handling local and remote data files. The goal of datasource is to abstract some of the file system operations when dealing with data files so the researcher doesn't have to know all the low-level details. Through datasource, a researcher can obtain and use a file with one function call, regardless of location of the file. DataSource is meant to augment standard python libraries, not replace them. It should work seamlessly with standard file IO operations and the os module. DataSource files can originate locally or remotely: - local files : '/home/guido/src/local/data.txt' - URLs (http, ftp, ...) : 'http://www.scipy.org/not/real/data.txt' DataSource files can also be compressed or uncompressed. Currently only gzip, bz2 and xz are supported. Example:: >>> # Create a DataSource, use os.curdir (default) for local storage. >>> from numpy import DataSource >>> ds = DataSource() >>> >>> # Open a remote file. >>> # DataSource downloads the file, stores it locally in: >>> # './www.google.com/index.html' >>> # opens the file and returns a file object. >>> fp = ds.open('http://www.google.com/') # doctest: +SKIP >>> >>> # Use the file as you normally would >>> fp.read() # doctest: +SKIP >>> fp.close() # doctest: +SKIP """ import os import io from .._utils import set_module _open = open def _check_mode(mode, encoding, newline): """Check mode and that encoding and newline are compatible. Parameters ---------- mode : str File open mode. encoding : str File encoding. newline : str Newline for text files. """ if "t" in mode: if "b" in mode: raise ValueError("Invalid mode: %r" % (mode,)) else: if encoding is not None: raise ValueError("Argument 'encoding' not supported in binary mode") if newline is not None: raise ValueError("Argument 'newline' not supported in binary mode") # Using a class instead of a module-level dictionary # to reduce the initial 'import numpy' overhead by # deferring the import of lzma, bz2 and gzip until needed # TODO: .zip support, .tar support? class _FileOpeners: """ Container for different methods to open (un-)compressed files. `_FileOpeners` contains a dictionary that holds one method for each supported file format. Attribute lookup is implemented in such a way that an instance of `_FileOpeners` itself can be indexed with the keys of that dictionary. Currently uncompressed files as well as files compressed with ``gzip``, ``bz2`` or ``xz`` compression are supported. Notes ----- `_file_openers`, an instance of `_FileOpeners`, is made available for use in the `_datasource` module. Examples -------- >>> import gzip >>> np.lib._datasource._file_openers.keys() [None, '.bz2', '.gz', '.xz', '.lzma'] >>> np.lib._datasource._file_openers['.gz'] is gzip.open True """ def __init__(self): self._loaded = False self._file_openers = {None: io.open} def _load(self): if self._loaded: return try: import bz2 self._file_openers[".bz2"] = bz2.open except ImportError: pass try: import gzip self._file_openers[".gz"] = gzip.open except ImportError: pass try: import lzma self._file_openers[".xz"] = lzma.open self._file_openers[".lzma"] = lzma.open except (ImportError, AttributeError): # There are incompatible backports of lzma that do not have the # lzma.open attribute, so catch that as well as ImportError. pass self._loaded = True def keys(self): """ Return the keys of currently supported file openers. Parameters ---------- None Returns ------- keys : list The keys are None for uncompressed files and the file extension strings (i.e. ``'.gz'``, ``'.xz'``) for supported compression methods. """ self._load() return list(self._file_openers.keys()) def __getitem__(self, key): self._load() return self._file_openers[key] _file_openers = _FileOpeners() def open(path, mode='r', destpath=os.curdir, encoding=None, newline=None): """ Open `path` with `mode` and return the file object. If ``path`` is an URL, it will be downloaded, stored in the `DataSource` `destpath` directory and opened from there. Parameters ---------- path : str Local file path or URL to open. mode : str, optional Mode to open `path`. Mode 'r' for reading, 'w' for writing, 'a' to append. Available modes depend on the type of object specified by path. Default is 'r'. destpath : str, optional Path to the directory where the source file gets downloaded to for use. If `destpath` is None, a temporary directory will be created. The default path is the current directory. encoding : {None, str}, optional Open text file with given encoding. The default encoding will be what `io.open` uses. newline : {None, str}, optional Newline to use when reading text file. Returns ------- out : file object The opened file. Notes ----- This is a convenience function that instantiates a `DataSource` and returns the file object from ``DataSource.open(path)``. """ ds = DataSource(destpath) return ds.open(path, mode, encoding=encoding, newline=newline) @set_module('numpy') class DataSource: """ DataSource(destpath='.') A generic data source file (file, http, ftp, ...). DataSources can be local files or remote files/URLs. The files may also be compressed or uncompressed. DataSource hides some of the low-level details of downloading the file, allowing you to simply pass in a valid file path (or URL) and obtain a file object. Parameters ---------- destpath : str or None, optional Path to the directory where the source file gets downloaded to for use. If `destpath` is None, a temporary directory will be created. The default path is the current directory. Notes ----- URLs require a scheme string (``http://``) to be used, without it they will fail:: >>> repos = np.DataSource() >>> repos.exists('www.google.com/index.html') False >>> repos.exists('http://www.google.com/index.html') True Temporary directories are deleted when the DataSource is deleted. Examples -------- :: >>> ds = np.DataSource('/home/guido') >>> urlname = 'http://www.google.com/' >>> gfile = ds.open('http://www.google.com/') >>> ds.abspath(urlname) '/home/guido/www.google.com/index.html' >>> ds = np.DataSource(None) # use with temporary file >>> ds.open('/home/guido/foobar.txt') <open file '/home/guido.foobar.txt', mode 'r' at 0x91d4430> >>> ds.abspath('/home/guido/foobar.txt') '/tmp/.../home/guido/foobar.txt' """ def __init__(self, destpath=os.curdir): """Create a DataSource with a local path at destpath.""" if destpath: self._destpath = os.path.abspath(destpath) self._istmpdest = False else: import tempfile # deferring import to improve startup time self._destpath = tempfile.mkdtemp() self._istmpdest = True def __del__(self): # Remove temp directories if hasattr(self, '_istmpdest') and self._istmpdest: import shutil shutil.rmtree(self._destpath) def _iszip(self, filename): """Test if the filename is a zip file by looking at the file extension. """ fname, ext = os.path.splitext(filename) return ext in _file_openers.keys() def _iswritemode(self, mode): """Test if the given mode will open a file for writing.""" # Currently only used to test the bz2 files. _writemodes = ("w", "+") for c in mode: if c in _writemodes: return True return False def _splitzipext(self, filename): """Split zip extension from filename and return filename. Returns ------- base, zip_ext : {tuple} """ if self._iszip(filename): return os.path.splitext(filename) else: return filename, None def _possible_names(self, filename): """Return a tuple containing compressed filename variations.""" names = [filename] if not self._iszip(filename): for zipext in _file_openers.keys(): if zipext: names.append(filename+zipext) return names def _isurl(self, path): """Test if path is a net location. Tests the scheme and netloc.""" # We do this here to reduce the 'import numpy' initial import time. from urllib.parse import urlparse # BUG : URLs require a scheme string ('http://') to be used. # www.google.com will fail. # Should we prepend the scheme for those that don't have it and # test that also? Similar to the way we append .gz and test for # for compressed versions of files. scheme, netloc, upath, uparams, uquery, ufrag = urlparse(path) return bool(scheme and netloc) def _cache(self, path): """Cache the file specified by path. Creates a copy of the file in the datasource cache. """ # We import these here because importing them is slow and # a significant fraction of numpy's total import time. import shutil from urllib.request import urlopen upath = self.abspath(path) # ensure directory exists if not os.path.exists(os.path.dirname(upath)): os.makedirs(os.path.dirname(upath)) # TODO: Doesn't handle compressed files! if self._isurl(path): with urlopen(path) as openedurl: with _open(upath, 'wb') as f: shutil.copyfileobj(openedurl, f) else: shutil.copyfile(path, upath) return upath def _findfile(self, path): """Searches for ``path`` and returns full path if found. If path is an URL, _findfile will cache a local copy and return the path to the cached file. If path is a local file, _findfile will return a path to that local file. The search will include possible compressed versions of the file and return the first occurrence found. """ # Build list of possible local file paths if not self._isurl(path): # Valid local paths filelist = self._possible_names(path) # Paths in self._destpath filelist += self._possible_names(self.abspath(path)) else: # Cached URLs in self._destpath filelist = self._possible_names(self.abspath(path)) # Remote URLs filelist = filelist + self._possible_names(path) for name in filelist: if self.exists(name): if self._isurl(name): name = self._cache(name) return name return None def abspath(self, path): """ Return absolute path of file in the DataSource directory. If `path` is an URL, then `abspath` will return either the location the file exists locally or the location it would exist when opened using the `open` method. Parameters ---------- path : str Can be a local file or a remote URL. Returns ------- out : str Complete path, including the `DataSource` destination directory. Notes ----- The functionality is based on `os.path.abspath`. """ # We do this here to reduce the 'import numpy' initial import time. from urllib.parse import urlparse # TODO: This should be more robust. Handles case where path includes # the destpath, but not other sub-paths. Failing case: # path = /home/guido/datafile.txt # destpath = /home/alex/ # upath = self.abspath(path) # upath == '/home/alex/home/guido/datafile.txt' # handle case where path includes self._destpath splitpath = path.split(self._destpath, 2) if len(splitpath) > 1: path = splitpath[1] scheme, netloc, upath, uparams, uquery, ufrag = urlparse(path) netloc = self._sanitize_relative_path(netloc) upath = self._sanitize_relative_path(upath) return os.path.join(self._destpath, netloc, upath) def _sanitize_relative_path(self, path): """Return a sanitised relative path for which os.path.abspath(os.path.join(base, path)).startswith(base) """ last = None path = os.path.normpath(path) while path != last: last = path # Note: os.path.join treats '/' as os.sep on Windows path = path.lstrip(os.sep).lstrip('/') path = path.lstrip(os.pardir).lstrip('..') drive, path = os.path.splitdrive(path) # for Windows return path def exists(self, path): """ Test if path exists. Test if `path` exists as (and in this order): - a local file. - a remote URL that has been downloaded and stored locally in the `DataSource` directory. - a remote URL that has not been downloaded, but is valid and accessible. Parameters ---------- path : str Can be a local file or a remote URL. Returns ------- out : bool True if `path` exists. Notes ----- When `path` is an URL, `exists` will return True if it's either stored locally in the `DataSource` directory, or is a valid remote URL. `DataSource` does not discriminate between the two, the file is accessible if it exists in either location. """ # First test for local path if os.path.exists(path): return True # We import this here because importing urllib is slow and # a significant fraction of numpy's total import time. from urllib.request import urlopen from urllib.error import URLError # Test cached url upath = self.abspath(path) if os.path.exists(upath): return True # Test remote url if self._isurl(path): try: netfile = urlopen(path) netfile.close() del(netfile) return True except URLError: return False return False def open(self, path, mode='r', encoding=None, newline=None): """ Open and return file-like object. If `path` is an URL, it will be downloaded, stored in the `DataSource` directory and opened from there. Parameters ---------- path : str Local file path or URL to open. mode : {'r', 'w', 'a'}, optional Mode to open `path`. Mode 'r' for reading, 'w' for writing, 'a' to append. Available modes depend on the type of object specified by `path`. Default is 'r'. encoding : {None, str}, optional Open text file with given encoding. The default encoding will be what `io.open` uses. newline : {None, str}, optional Newline to use when reading text file. Returns ------- out : file object File object. """ # TODO: There is no support for opening a file for writing which # doesn't exist yet (creating a file). Should there be? # TODO: Add a ``subdir`` parameter for specifying the subdirectory # used to store URLs in self._destpath. if self._isurl(path) and self._iswritemode(mode): raise ValueError("URLs are not writeable") # NOTE: _findfile will fail on a new file opened for writing. found = self._findfile(path) if found: _fname, ext = self._splitzipext(found) if ext == 'bz2': mode.replace("+", "") return _file_openers[ext](found, mode=mode, encoding=encoding, newline=newline) else: raise FileNotFoundError(f"{path} not found.") class Repository (DataSource): """ Repository(baseurl, destpath='.') A data repository where multiple DataSource's share a base URL/directory. `Repository` extends `DataSource` by prepending a base URL (or directory) to all the files it handles. Use `Repository` when you will be working with multiple files from one base URL. Initialize `Repository` with the base URL, then refer to each file by its filename only. Parameters ---------- baseurl : str Path to the local directory or remote location that contains the data files. destpath : str or None, optional Path to the directory where the source file gets downloaded to for use. If `destpath` is None, a temporary directory will be created. The default path is the current directory. Examples -------- To analyze all files in the repository, do something like this (note: this is not self-contained code):: >>> repos = np.lib._datasource.Repository('/home/user/data/dir/') >>> for filename in filelist: ... fp = repos.open(filename) ... fp.analyze() ... fp.close() Similarly you could use a URL for a repository:: >>> repos = np.lib._datasource.Repository('http://www.xyz.edu/data') """ def __init__(self, baseurl, destpath=os.curdir): """Create a Repository with a shared url or directory of baseurl.""" DataSource.__init__(self, destpath=destpath) self._baseurl = baseurl def __del__(self): DataSource.__del__(self) def _fullpath(self, path): """Return complete path for path. Prepends baseurl if necessary.""" splitpath = path.split(self._baseurl, 2) if len(splitpath) == 1: result = os.path.join(self._baseurl, path) else: result = path # path contains baseurl already return result def _findfile(self, path): """Extend DataSource method to prepend baseurl to ``path``.""" return DataSource._findfile(self, self._fullpath(path)) def abspath(self, path): """ Return absolute path of file in the Repository directory. If `path` is an URL, then `abspath` will return either the location the file exists locally or the location it would exist when opened using the `open` method. Parameters ---------- path : str Can be a local file or a remote URL. This may, but does not have to, include the `baseurl` with which the `Repository` was initialized. Returns ------- out : str Complete path, including the `DataSource` destination directory. """ return DataSource.abspath(self, self._fullpath(path)) def exists(self, path): """ Test if path exists prepending Repository base URL to path. Test if `path` exists as (and in this order): - a local file. - a remote URL that has been downloaded and stored locally in the `DataSource` directory. - a remote URL that has not been downloaded, but is valid and accessible. Parameters ---------- path : str Can be a local file or a remote URL. This may, but does not have to, include the `baseurl` with which the `Repository` was initialized. Returns ------- out : bool True if `path` exists. Notes ----- When `path` is an URL, `exists` will return True if it's either stored locally in the `DataSource` directory, or is a valid remote URL. `DataSource` does not discriminate between the two, the file is accessible if it exists in either location. """ return DataSource.exists(self, self._fullpath(path)) def open(self, path, mode='r', encoding=None, newline=None): """ Open and return file-like object prepending Repository base URL. If `path` is an URL, it will be downloaded, stored in the DataSource directory and opened from there. Parameters ---------- path : str Local file path or URL to open. This may, but does not have to, include the `baseurl` with which the `Repository` was initialized. mode : {'r', 'w', 'a'}, optional Mode to open `path`. Mode 'r' for reading, 'w' for writing, 'a' to append. Available modes depend on the type of object specified by `path`. Default is 'r'. encoding : {None, str}, optional Open text file with given encoding. The default encoding will be what `io.open` uses. newline : {None, str}, optional Newline to use when reading text file. Returns ------- out : file object File object. """ return DataSource.open(self, self._fullpath(path), mode, encoding=encoding, newline=newline) def listdir(self): """ List files in the source Repository. Returns ------- files : list of str List of file names (not containing a directory part). Notes ----- Does not currently work for remote repositories. """ if self._isurl(self._baseurl): raise NotImplementedError( "Directory listing of URLs, not supported yet.") else: return os.listdir(self._baseurl)	22.1 KB	2026-01-20 12:58
📄 _iotools.py """A collection of functions designed to help I/O with ascii files. """ __docformat__ = "restructuredtext en" import numpy as np import numpy.core.numeric as nx from numpy.compat import asbytes, asunicode def _decode_line(line, encoding=None): """Decode bytes from binary input streams. Defaults to decoding from 'latin1'. That differs from the behavior of np.compat.asunicode that decodes from 'ascii'. Parameters ---------- line : str or bytes Line to be decoded. encoding : str Encoding used to decode `line`. Returns ------- decoded_line : str """ if type(line) is bytes: if encoding is None: encoding = "latin1" line = line.decode(encoding) return line def _is_string_like(obj): """ Check whether obj behaves like a string. """ try: obj + '' except (TypeError, ValueError): return False return True def _is_bytes_like(obj): """ Check whether obj behaves like a bytes object. """ try: obj + b'' except (TypeError, ValueError): return False return True def has_nested_fields(ndtype): """ Returns whether one or several fields of a dtype are nested. Parameters ---------- ndtype : dtype Data-type of a structured array. Raises ------ AttributeError If `ndtype` does not have a `names` attribute. Examples -------- >>> dt = np.dtype([('name', 'S4'), ('x', float), ('y', float)]) >>> np.lib._iotools.has_nested_fields(dt) False """ for name in ndtype.names or (): if ndtype[name].names is not None: return True return False def flatten_dtype(ndtype, flatten_base=False): """ Unpack a structured data-type by collapsing nested fields and/or fields with a shape. Note that the field names are lost. Parameters ---------- ndtype : dtype The datatype to collapse flatten_base : bool, optional If True, transform a field with a shape into several fields. Default is False. Examples -------- >>> dt = np.dtype([('name', 'S4'), ('x', float), ('y', float), ... ('block', int, (2, 3))]) >>> np.lib._iotools.flatten_dtype(dt) [dtype('S4'), dtype('float64'), dtype('float64'), dtype('int64')] >>> np.lib._iotools.flatten_dtype(dt, flatten_base=True) [dtype('S4'), dtype('float64'), dtype('float64'), dtype('int64'), dtype('int64'), dtype('int64'), dtype('int64'), dtype('int64'), dtype('int64')] """ names = ndtype.names if names is None: if flatten_base: return [ndtype.base] * int(np.prod(ndtype.shape)) return [ndtype.base] else: types = [] for field in names: info = ndtype.fields[field] flat_dt = flatten_dtype(info[0], flatten_base) types.extend(flat_dt) return types class LineSplitter: """ Object to split a string at a given delimiter or at given places. Parameters ---------- delimiter : str, int, or sequence of ints, optional If a string, character used to delimit consecutive fields. If an integer or a sequence of integers, width(s) of each field. comments : str, optional Character used to mark the beginning of a comment. Default is '#'. autostrip : bool, optional Whether to strip each individual field. Default is True. """ def autostrip(self, method): """ Wrapper to strip each member of the output of `method`. Parameters ---------- method : function Function that takes a single argument and returns a sequence of strings. Returns ------- wrapped : function The result of wrapping `method`. `wrapped` takes a single input argument and returns a list of strings that are stripped of white-space. """ return lambda input: [_.strip() for _ in method(input)] def __init__(self, delimiter=None, comments='#', autostrip=True, encoding=None): delimiter = _decode_line(delimiter) comments = _decode_line(comments) self.comments = comments # Delimiter is a character if (delimiter is None) or isinstance(delimiter, str): delimiter = delimiter or None _handyman = self._delimited_splitter # Delimiter is a list of field widths elif hasattr(delimiter, '__iter__'): _handyman = self._variablewidth_splitter idx = np.cumsum([0] + list(delimiter)) delimiter = [slice(i, j) for (i, j) in zip(idx[:-1], idx[1:])] # Delimiter is a single integer elif int(delimiter): (_handyman, delimiter) = ( self._fixedwidth_splitter, int(delimiter)) else: (_handyman, delimiter) = (self._delimited_splitter, None) self.delimiter = delimiter if autostrip: self._handyman = self.autostrip(_handyman) else: self._handyman = _handyman self.encoding = encoding def _delimited_splitter(self, line): """Chop off comments, strip, and split at delimiter. """ if self.comments is not None: line = line.split(self.comments)[0] line = line.strip(" \r\n") if not line: return [] return line.split(self.delimiter) def _fixedwidth_splitter(self, line): if self.comments is not None: line = line.split(self.comments)[0] line = line.strip("\r\n") if not line: return [] fixed = self.delimiter slices = [slice(i, i + fixed) for i in range(0, len(line), fixed)] return [line[s] for s in slices] def _variablewidth_splitter(self, line): if self.comments is not None: line = line.split(self.comments)[0] if not line: return [] slices = self.delimiter return [line[s] for s in slices] def __call__(self, line): return self._handyman(_decode_line(line, self.encoding)) class NameValidator: """ Object to validate a list of strings to use as field names. The strings are stripped of any non alphanumeric character, and spaces are replaced by '_'. During instantiation, the user can define a list of names to exclude, as well as a list of invalid characters. Names in the exclusion list are appended a '_' character. Once an instance has been created, it can be called with a list of names, and a list of valid names will be created. The `__call__` method accepts an optional keyword "default" that sets the default name in case of ambiguity. By default this is 'f', so that names will default to `f0`, `f1`, etc. Parameters ---------- excludelist : sequence, optional A list of names to exclude. This list is appended to the default list ['return', 'file', 'print']. Excluded names are appended an underscore: for example, `file` becomes `file_` if supplied. deletechars : str, optional A string combining invalid characters that must be deleted from the names. case_sensitive : {True, False, 'upper', 'lower'}, optional * If True, field names are case-sensitive. * If False or 'upper', field names are converted to upper case. * If 'lower', field names are converted to lower case. The default value is True. replace_space : '_', optional Character(s) used in replacement of white spaces. Notes ----- Calling an instance of `NameValidator` is the same as calling its method `validate`. Examples -------- >>> validator = np.lib._iotools.NameValidator() >>> validator(['file', 'field2', 'with space', 'CaSe']) ('file_', 'field2', 'with_space', 'CaSe') >>> validator = np.lib._iotools.NameValidator(excludelist=['excl'], ... deletechars='q', ... case_sensitive=False) >>> validator(['excl', 'field2', 'no_q', 'with space', 'CaSe']) ('EXCL', 'FIELD2', 'NO_Q', 'WITH_SPACE', 'CASE') """ defaultexcludelist = ['return', 'file', 'print'] defaultdeletechars = set(r"""~!@#$%^&()-=+~\\|]}[{';: /?.>,<""") def __init__(self, excludelist=None, deletechars=None, case_sensitive=None, replace_space='_'): # Process the exclusion list .. if excludelist is None: excludelist = [] excludelist.extend(self.defaultexcludelist) self.excludelist = excludelist # Process the list of characters to delete if deletechars is None: delete = self.defaultdeletechars else: delete = set(deletechars) delete.add('"') self.deletechars = delete # Process the case option ..... if (case_sensitive is None) or (case_sensitive is True): self.case_converter = lambda x: x elif (case_sensitive is False) or case_sensitive.startswith('u'): self.case_converter = lambda x: x.upper() elif case_sensitive.startswith('l'): self.case_converter = lambda x: x.lower() else: msg = 'unrecognized case_sensitive value %s.' % case_sensitive raise ValueError(msg) self.replace_space = replace_space def validate(self, names, defaultfmt="f%i", nbfields=None): """ Validate a list of strings as field names for a structured array. Parameters ---------- names : sequence of str Strings to be validated. defaultfmt : str, optional Default format string, used if validating a given string reduces its length to zero. nbfields : integer, optional Final number of validated names, used to expand or shrink the initial list of names. Returns ------- validatednames : list of str The list of validated field names. Notes ----- A `NameValidator` instance can be called directly, which is the same as calling `validate`. For examples, see `NameValidator`. """ # Initial checks .............. if (names is None): if (nbfields is None): return None names = [] if isinstance(names, str): names = [names, ] if nbfields is not None: nbnames = len(names) if (nbnames < nbfields): names = list(names) + [''] (nbfields - nbnames) elif (nbnames > nbfields): names = names[:nbfields] # Set some shortcuts ........... deletechars = self.deletechars excludelist = self.excludelist case_converter = self.case_converter replace_space = self.replace_space # Initializes some variables ... validatednames = [] seen = dict() nbempty = 0 for item in names: item = case_converter(item).strip() if replace_space: item = item.replace(' ', replace_space) item = ''.join([c for c in item if c not in deletechars]) if item == '': item = defaultfmt % nbempty while item in names: nbempty += 1 item = defaultfmt % nbempty nbempty += 1 elif item in excludelist: item += '_' cnt = seen.get(item, 0) if cnt > 0: validatednames.append(item + '_%d' % cnt) else: validatednames.append(item) seen[item] = cnt + 1 return tuple(validatednames) def __call__(self, names, defaultfmt="f%i", nbfields=None): return self.validate(names, defaultfmt=defaultfmt, nbfields=nbfields) def str2bool(value): """ Tries to transform a string supposed to represent a boolean to a boolean. Parameters ---------- value : str The string that is transformed to a boolean. Returns ------- boolval : bool The boolean representation of `value`. Raises ------ ValueError If the string is not 'True' or 'False' (case independent) Examples -------- >>> np.lib._iotools.str2bool('TRUE') True >>> np.lib._iotools.str2bool('false') False """ value = value.upper() if value == 'TRUE': return True elif value == 'FALSE': return False else: raise ValueError("Invalid boolean") class ConverterError(Exception): """ Exception raised when an error occurs in a converter for string values. """ pass class ConverterLockError(ConverterError): """ Exception raised when an attempt is made to upgrade a locked converter. """ pass class ConversionWarning(UserWarning): """ Warning issued when a string converter has a problem. Notes ----- In `genfromtxt` a `ConversionWarning` is issued if raising exceptions is explicitly suppressed with the "invalid_raise" keyword. """ pass class StringConverter: """ Factory class for function transforming a string into another object (int, float). After initialization, an instance can be called to transform a string into another object. If the string is recognized as representing a missing value, a default value is returned. Attributes ---------- func : function Function used for the conversion. default : any Default value to return when the input corresponds to a missing value. type : type Type of the output. _status : int Integer representing the order of the conversion. _mapper : sequence of tuples Sequence of tuples (dtype, function, default value) to evaluate in order. _locked : bool Holds `locked` parameter. Parameters ---------- dtype_or_func : {None, dtype, function}, optional If a `dtype`, specifies the input data type, used to define a basic function and a default value for missing data. For example, when `dtype` is float, the `func` attribute is set to `float` and the default value to `np.nan`. If a function, this function is used to convert a string to another object. In this case, it is recommended to give an associated default value as input. default : any, optional Value to return by default, that is, when the string to be converted is flagged as missing. If not given, `StringConverter` tries to supply a reasonable default value. missing_values : {None, sequence of str}, optional ``None`` or sequence of strings indicating a missing value. If ``None`` then missing values are indicated by empty entries. The default is ``None``. locked : bool, optional Whether the StringConverter should be locked to prevent automatic upgrade or not. Default is False. """ _mapper = [(nx.bool_, str2bool, False), (nx.int_, int, -1),] # On 32-bit systems, we need to make sure that we explicitly include # nx.int64 since ns.int_ is nx.int32. if nx.dtype(nx.int_).itemsize < nx.dtype(nx.int64).itemsize: _mapper.append((nx.int64, int, -1)) _mapper.extend([(nx.float64, float, nx.nan), (nx.complex128, complex, nx.nan + 0j), (nx.longdouble, nx.longdouble, nx.nan), # If a non-default dtype is passed, fall back to generic # ones (should only be used for the converter) (nx.integer, int, -1), (nx.floating, float, nx.nan), (nx.complexfloating, complex, nx.nan + 0j), # Last, try with the string types (must be last, because # `_mapper[-1]` is used as default in some cases) (nx.str_, asunicode, '???'), (nx.bytes_, asbytes, '???'), ]) @classmethod def _getdtype(cls, val): """Returns the dtype of the input variable.""" return np.array(val).dtype @classmethod def _getsubdtype(cls, val): """Returns the type of the dtype of the input variable.""" return np.array(val).dtype.type @classmethod def _dtypeortype(cls, dtype): """Returns dtype for datetime64 and type of dtype otherwise.""" # This is a bit annoying. We want to return the "general" type in most # cases (ie. "string" rather than "S10"), but we want to return the # specific type for datetime64 (ie. "datetime64[us]" rather than # "datetime64"). if dtype.type == np.datetime64: return dtype return dtype.type @classmethod def upgrade_mapper(cls, func, default=None): """ Upgrade the mapper of a StringConverter by adding a new function and its corresponding default. The input function (or sequence of functions) and its associated default value (if any) is inserted in penultimate position of the mapper. The corresponding type is estimated from the dtype of the default value. Parameters ---------- func : var Function, or sequence of functions Examples -------- >>> import dateutil.parser >>> import datetime >>> dateparser = dateutil.parser.parse >>> defaultdate = datetime.date(2000, 1, 1) >>> StringConverter.upgrade_mapper(dateparser, default=defaultdate) """ # Func is a single functions if hasattr(func, '__call__'): cls._mapper.insert(-1, (cls._getsubdtype(default), func, default)) return elif hasattr(func, '__iter__'): if isinstance(func[0], (tuple, list)): for _ in func: cls._mapper.insert(-1, _) return if default is None: default = [None] * len(func) else: default = list(default) default.append([None] * (len(func) - len(default))) for fct, dft in zip(func, default): cls._mapper.insert(-1, (cls._getsubdtype(dft), fct, dft)) @classmethod def _find_map_entry(cls, dtype): # if a converter for the specific dtype is available use that for i, (deftype, func, default_def) in enumerate(cls._mapper): if dtype.type == deftype: return i, (deftype, func, default_def) # otherwise find an inexact match for i, (deftype, func, default_def) in enumerate(cls._mapper): if np.issubdtype(dtype.type, deftype): return i, (deftype, func, default_def) raise LookupError def __init__(self, dtype_or_func=None, default=None, missing_values=None, locked=False): # Defines a lock for upgrade self._locked = bool(locked) # No input dtype: minimal initialization if dtype_or_func is None: self.func = str2bool self._status = 0 self.default = default or False dtype = np.dtype('bool') else: # Is the input a np.dtype ? try: self.func = None dtype = np.dtype(dtype_or_func) except TypeError: # dtype_or_func must be a function, then if not hasattr(dtype_or_func, '__call__'): errmsg = ("The input argument `dtype` is neither a" " function nor a dtype (got '%s' instead)") raise TypeError(errmsg % type(dtype_or_func)) # Set the function self.func = dtype_or_func # If we don't have a default, try to guess it or set it to # None if default is None: try: default = self.func('0') except ValueError: default = None dtype = self._getdtype(default) # find the best match in our mapper try: self._status, (_, func, default_def) = self._find_map_entry(dtype) except LookupError: # no match self.default = default _, func, _ = self._mapper[-1] self._status = 0 else: # use the found default only if we did not already have one if default is None: self.default = default_def else: self.default = default # If the input was a dtype, set the function to the last we saw if self.func is None: self.func = func # If the status is 1 (int), change the function to # something more robust. if self.func == self._mapper[1][1]: if issubclass(dtype.type, np.uint64): self.func = np.uint64 elif issubclass(dtype.type, np.int64): self.func = np.int64 else: self.func = lambda x: int(float(x)) # Store the list of strings corresponding to missing values. if missing_values is None: self.missing_values = {''} else: if isinstance(missing_values, str): missing_values = missing_values.split(",") self.missing_values = set(list(missing_values) + ['']) self._callingfunction = self._strict_call self.type = self._dtypeortype(dtype) self._checked = False self._initial_default = default def _loose_call(self, value): try: return self.func(value) except ValueError: return self.default def _strict_call(self, value): try: # We check if we can convert the value using the current function new_value = self.func(value) # In addition to having to check whether func can convert the # value, we also have to make sure that we don't get overflow # errors for integers. if self.func is int: try: np.array(value, dtype=self.type) except OverflowError: raise ValueError # We're still here so we can now return the new value return new_value except ValueError: if value.strip() in self.missing_values: if not self._status: self._checked = False return self.default raise ValueError("Cannot convert string '%s'" % value) def __call__(self, value): return self._callingfunction(value) def _do_upgrade(self): # Raise an exception if we locked the converter... if self._locked: errmsg = "Converter is locked and cannot be upgraded" raise ConverterLockError(errmsg) _statusmax = len(self._mapper) # Complains if we try to upgrade by the maximum _status = self._status if _status == _statusmax: errmsg = "Could not find a valid conversion function" raise ConverterError(errmsg) elif _status < _statusmax - 1: _status += 1 self.type, self.func, default = self._mapper[_status] self._status = _status if self._initial_default is not None: self.default = self._initial_default else: self.default = default def upgrade(self, value): """ Find the best converter for a given string, and return the result. The supplied string `value` is converted by testing different converters in order. First the `func` method of the `StringConverter` instance is tried, if this fails other available converters are tried. The order in which these other converters are tried is determined by the `_status` attribute of the instance. Parameters ---------- value : str The string to convert. Returns ------- out : any The result of converting `value` with the appropriate converter. """ self._checked = True try: return self._strict_call(value) except ValueError: self._do_upgrade() return self.upgrade(value) def iterupgrade(self, value): self._checked = True if not hasattr(value, '__iter__'): value = (value,) _strict_call = self._strict_call try: for _m in value: _strict_call(_m) except ValueError: self._do_upgrade() self.iterupgrade(value) def update(self, func, default=None, testing_value=None, missing_values='', locked=False): """ Set StringConverter attributes directly. Parameters ---------- func : function Conversion function. default : any, optional Value to return by default, that is, when the string to be converted is flagged as missing. If not given, `StringConverter` tries to supply a reasonable default value. testing_value : str, optional A string representing a standard input value of the converter. This string is used to help defining a reasonable default value. missing_values : {sequence of str, None}, optional Sequence of strings indicating a missing value. If ``None``, then the existing `missing_values` are cleared. The default is `''`. locked : bool, optional Whether the StringConverter should be locked to prevent automatic upgrade or not. Default is False. Notes ----- `update` takes the same parameters as the constructor of `StringConverter`, except that `func` does not accept a `dtype` whereas `dtype_or_func` in the constructor does. """ self.func = func self._locked = locked # Don't reset the default to None if we can avoid it if default is not None: self.default = default self.type = self._dtypeortype(self._getdtype(default)) else: try: tester = func(testing_value or '1') except (TypeError, ValueError): tester = None self.type = self._dtypeortype(self._getdtype(tester)) # Add the missing values to the existing set or clear it. if missing_values is None: # Clear all missing values even though the ctor initializes it to # set(['']) when the argument is None. self.missing_values = set() else: if not np.iterable(missing_values): missing_values = [missing_values] if not all(isinstance(v, str) for v in missing_values): raise TypeError("missing_values must be strings or unicode") self.missing_values.update(missing_values) def easy_dtype(ndtype, names=None, defaultfmt="f%i", validationargs): """ Convenience function to create a `np.dtype` object. The function processes the input `dtype` and matches it with the given names. Parameters ---------- ndtype : var Definition of the dtype. Can be any string or dictionary recognized by the `np.dtype` function, or a sequence of types. names : str or sequence, optional Sequence of strings to use as field names for a structured dtype. For convenience, `names` can be a string of a comma-separated list of names. defaultfmt : str, optional Format string used to define missing names, such as ``"f%i"`` (default) or ``"fields_%02i"``. validationargs : optional A series of optional arguments used to initialize a `NameValidator`. Examples -------- >>> np.lib._iotools.easy_dtype(float) dtype('float64') >>> np.lib._iotools.easy_dtype("i4, f8") dtype([('f0', '<i4'), ('f1', '<f8')]) >>> np.lib._iotools.easy_dtype("i4, f8", defaultfmt="field_%03i") dtype([('field_000', '<i4'), ('field_001', '<f8')]) >>> np.lib._iotools.easy_dtype((int, float, float), names="a,b,c") dtype([('a', '<i8'), ('b', '<f8'), ('c', '<f8')]) >>> np.lib._iotools.easy_dtype(float, names="a,b,c") dtype([('a', '<f8'), ('b', '<f8'), ('c', '<f8')]) """ try: ndtype = np.dtype(ndtype) except TypeError: validate = NameValidator(validationargs) nbfields = len(ndtype) if names is None: names = [''] * len(ndtype) elif isinstance(names, str): names = names.split(",") names = validate(names, nbfields=nbfields, defaultfmt=defaultfmt) ndtype = np.dtype(dict(formats=ndtype, names=names)) else: # Explicit names if names is not None: validate = NameValidator(*validationargs) if isinstance(names, str): names = names.split(",") # Simple dtype: repeat to match the nb of names if ndtype.names is None: formats = tuple([ndtype.type] len(names)) names = validate(names, defaultfmt=defaultfmt) ndtype = np.dtype(list(zip(names, formats))) # Structured dtype: just validate the names as needed else: ndtype.names = validate(names, nbfields=len(ndtype.names), defaultfmt=defaultfmt) # No implicit names elif ndtype.names is not None: validate = NameValidator(*validationargs) # Default initial names : should we change the format ? numbered_names = tuple("f%i" % i for i in range(len(ndtype.names))) if ((ndtype.names == numbered_names) and (defaultfmt != "f%i")): ndtype.names = validate([''] len(ndtype.names), defaultfmt=defaultfmt) # Explicit initial names : just validate else: ndtype.names = validate(ndtype.names, defaultfmt=defaultfmt) return ndtype	30.14 KB	2026-01-20 12:58
📄 _version.py """Utility to compare (NumPy) version strings. The NumpyVersion class allows properly comparing numpy version strings. The LooseVersion and StrictVersion classes that distutils provides don't work; they don't recognize anything like alpha/beta/rc/dev versions. """ import re __all__ = ['NumpyVersion'] class NumpyVersion(): """Parse and compare numpy version strings. NumPy has the following versioning scheme (numbers given are examples; they can be > 9 in principle): - Released version: '1.8.0', '1.8.1', etc. - Alpha: '1.8.0a1', '1.8.0a2', etc. - Beta: '1.8.0b1', '1.8.0b2', etc. - Release candidates: '1.8.0rc1', '1.8.0rc2', etc. - Development versions: '1.8.0.dev-f1234afa' (git commit hash appended) - Development versions after a1: '1.8.0a1.dev-f1234afa', '1.8.0b2.dev-f1234afa', '1.8.1rc1.dev-f1234afa', etc. - Development versions (no git hash available): '1.8.0.dev-Unknown' Comparing needs to be done against a valid version string or other `NumpyVersion` instance. Note that all development versions of the same (pre-)release compare equal. .. versionadded:: 1.9.0 Parameters ---------- vstring : str NumPy version string (``np.__version__``). Examples -------- >>> from numpy.lib import NumpyVersion >>> if NumpyVersion(np.__version__) < '1.7.0': ... print('skip') >>> # skip >>> NumpyVersion('1.7') # raises ValueError, add ".0" Traceback (most recent call last): ... ValueError: Not a valid numpy version string """ def __init__(self, vstring): self.vstring = vstring ver_main = re.match(r'\d+\.\d+\.\d+', vstring) if not ver_main: raise ValueError("Not a valid numpy version string") self.version = ver_main.group() self.major, self.minor, self.bugfix = [int(x) for x in self.version.split('.')] if len(vstring) == ver_main.end(): self.pre_release = 'final' else: alpha = re.match(r'a\d', vstring[ver_main.end():]) beta = re.match(r'b\d', vstring[ver_main.end():]) rc = re.match(r'rc\d', vstring[ver_main.end():]) pre_rel = [m for m in [alpha, beta, rc] if m is not None] if pre_rel: self.pre_release = pre_rel[0].group() else: self.pre_release = '' self.is_devversion = bool(re.search(r'.dev', vstring)) def _compare_version(self, other): """Compare major.minor.bugfix""" if self.major == other.major: if self.minor == other.minor: if self.bugfix == other.bugfix: vercmp = 0 elif self.bugfix > other.bugfix: vercmp = 1 else: vercmp = -1 elif self.minor > other.minor: vercmp = 1 else: vercmp = -1 elif self.major > other.major: vercmp = 1 else: vercmp = -1 return vercmp def _compare_pre_release(self, other): """Compare alpha/beta/rc/final.""" if self.pre_release == other.pre_release: vercmp = 0 elif self.pre_release == 'final': vercmp = 1 elif other.pre_release == 'final': vercmp = -1 elif self.pre_release > other.pre_release: vercmp = 1 else: vercmp = -1 return vercmp def _compare(self, other): if not isinstance(other, (str, NumpyVersion)): raise ValueError("Invalid object to compare with NumpyVersion.") if isinstance(other, str): other = NumpyVersion(other) vercmp = self._compare_version(other) if vercmp == 0: # Same x.y.z version, check for alpha/beta/rc vercmp = self._compare_pre_release(other) if vercmp == 0: # Same version and same pre-release, check if dev version if self.is_devversion is other.is_devversion: vercmp = 0 elif self.is_devversion: vercmp = -1 else: vercmp = 1 return vercmp def __lt__(self, other): return self._compare(other) < 0 def __le__(self, other): return self._compare(other) <= 0 def __eq__(self, other): return self._compare(other) == 0 def __ne__(self, other): return self._compare(other) != 0 def __gt__(self, other): return self._compare(other) > 0 def __ge__(self, other): return self._compare(other) >= 0 def __repr__(self): return "NumpyVersion(%s)" % self.vstring	4.74 KB	2026-01-20 12:58
📄 _version.pyi __all__: list[str] class NumpyVersion: vstring: str version: str major: int minor: int bugfix: int pre_release: str is_devversion: bool def __init__(self, vstring: str) -> None: ... def __lt__(self, other: str \| NumpyVersion) -> bool: ... def __le__(self, other: str \| NumpyVersion) -> bool: ... def __eq__(self, other: str \| NumpyVersion) -> bool: ... # type: ignore[override] def __ne__(self, other: str \| NumpyVersion) -> bool: ... # type: ignore[override] def __gt__(self, other: str \| NumpyVersion) -> bool: ... def __ge__(self, other: str \| NumpyVersion) -> bool: ...	633 B	2026-01-20 12:58
📄 arraypad.py """ The arraypad module contains a group of functions to pad values onto the edges of an n-dimensional array. """ import numpy as np from numpy.core.overrides import array_function_dispatch from numpy.lib.index_tricks import ndindex __all__ = ['pad'] ############################################################################### # Private utility functions. def _round_if_needed(arr, dtype): """ Rounds arr inplace if destination dtype is integer. Parameters ---------- arr : ndarray Input array. dtype : dtype The dtype of the destination array. """ if np.issubdtype(dtype, np.integer): arr.round(out=arr) def _slice_at_axis(sl, axis): """ Construct tuple of slices to slice an array in the given dimension. Parameters ---------- sl : slice The slice for the given dimension. axis : int The axis to which `sl` is applied. All other dimensions are left "unsliced". Returns ------- sl : tuple of slices A tuple with slices matching `shape` in length. Examples -------- >>> _slice_at_axis(slice(None, 3, -1), 1) (slice(None, None, None), slice(None, 3, -1), (...,)) """ return (slice(None),) * axis + (sl,) + (...,) def _view_roi(array, original_area_slice, axis): """ Get a view of the current region of interest during iterative padding. When padding multiple dimensions iteratively corner values are unnecessarily overwritten multiple times. This function reduces the working area for the first dimensions so that corners are excluded. Parameters ---------- array : ndarray The array with the region of interest. original_area_slice : tuple of slices Denotes the area with original values of the unpadded array. axis : int The currently padded dimension assuming that `axis` is padded before `axis` + 1. Returns ------- roi : ndarray The region of interest of the original `array`. """ axis += 1 sl = (slice(None),) * axis + original_area_slice[axis:] return array[sl] def _pad_simple(array, pad_width, fill_value=None): """ Pad array on all sides with either a single value or undefined values. Parameters ---------- array : ndarray Array to grow. pad_width : sequence of tuple[int, int] Pad width on both sides for each dimension in `arr`. fill_value : scalar, optional If provided the padded area is filled with this value, otherwise the pad area left undefined. Returns ------- padded : ndarray The padded array with the same dtype as`array`. Its order will default to C-style if `array` is not F-contiguous. original_area_slice : tuple A tuple of slices pointing to the area of the original array. """ # Allocate grown array new_shape = tuple( left + size + right for size, (left, right) in zip(array.shape, pad_width) ) order = 'F' if array.flags.fnc else 'C' # Fortran and not also C-order padded = np.empty(new_shape, dtype=array.dtype, order=order) if fill_value is not None: padded.fill(fill_value) # Copy old array into correct space original_area_slice = tuple( slice(left, left + size) for size, (left, right) in zip(array.shape, pad_width) ) padded[original_area_slice] = array return padded, original_area_slice def _set_pad_area(padded, axis, width_pair, value_pair): """ Set empty-padded area in given dimension. Parameters ---------- padded : ndarray Array with the pad area which is modified inplace. axis : int Dimension with the pad area to set. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. value_pair : tuple of scalars or ndarrays Values inserted into the pad area on each side. It must match or be broadcastable to the shape of `arr`. """ left_slice = _slice_at_axis(slice(None, width_pair[0]), axis) padded[left_slice] = value_pair[0] right_slice = _slice_at_axis( slice(padded.shape[axis] - width_pair[1], None), axis) padded[right_slice] = value_pair[1] def _get_edges(padded, axis, width_pair): """ Retrieve edge values from empty-padded array in given dimension. Parameters ---------- padded : ndarray Empty-padded array. axis : int Dimension in which the edges are considered. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. Returns ------- left_edge, right_edge : ndarray Edge values of the valid area in `padded` in the given dimension. Its shape will always match `padded` except for the dimension given by `axis` which will have a length of 1. """ left_index = width_pair[0] left_slice = _slice_at_axis(slice(left_index, left_index + 1), axis) left_edge = padded[left_slice] right_index = padded.shape[axis] - width_pair[1] right_slice = _slice_at_axis(slice(right_index - 1, right_index), axis) right_edge = padded[right_slice] return left_edge, right_edge def _get_linear_ramps(padded, axis, width_pair, end_value_pair): """ Construct linear ramps for empty-padded array in given dimension. Parameters ---------- padded : ndarray Empty-padded array. axis : int Dimension in which the ramps are constructed. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. end_value_pair : (scalar, scalar) End values for the linear ramps which form the edge of the fully padded array. These values are included in the linear ramps. Returns ------- left_ramp, right_ramp : ndarray Linear ramps to set on both sides of `padded`. """ edge_pair = _get_edges(padded, axis, width_pair) left_ramp, right_ramp = ( np.linspace( start=end_value, stop=edge.squeeze(axis), # Dimension is replaced by linspace num=width, endpoint=False, dtype=padded.dtype, axis=axis ) for end_value, edge, width in zip( end_value_pair, edge_pair, width_pair ) ) # Reverse linear space in appropriate dimension right_ramp = right_ramp[_slice_at_axis(slice(None, None, -1), axis)] return left_ramp, right_ramp def _get_stats(padded, axis, width_pair, length_pair, stat_func): """ Calculate statistic for the empty-padded array in given dimension. Parameters ---------- padded : ndarray Empty-padded array. axis : int Dimension in which the statistic is calculated. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. length_pair : 2-element sequence of None or int Gives the number of values in valid area from each side that is taken into account when calculating the statistic. If None the entire valid area in `padded` is considered. stat_func : function Function to compute statistic. The expected signature is ``stat_func(x: ndarray, axis: int, keepdims: bool) -> ndarray``. Returns ------- left_stat, right_stat : ndarray Calculated statistic for both sides of `padded`. """ # Calculate indices of the edges of the area with original values left_index = width_pair[0] right_index = padded.shape[axis] - width_pair[1] # as well as its length max_length = right_index - left_index # Limit stat_lengths to max_length left_length, right_length = length_pair if left_length is None or max_length < left_length: left_length = max_length if right_length is None or max_length < right_length: right_length = max_length if (left_length == 0 or right_length == 0) \ and stat_func in {np.amax, np.amin}: # amax and amin can't operate on an empty array, # raise a more descriptive warning here instead of the default one raise ValueError("stat_length of 0 yields no value for padding") # Calculate statistic for the left side left_slice = _slice_at_axis( slice(left_index, left_index + left_length), axis) left_chunk = padded[left_slice] left_stat = stat_func(left_chunk, axis=axis, keepdims=True) _round_if_needed(left_stat, padded.dtype) if left_length == right_length == max_length: # return early as right_stat must be identical to left_stat return left_stat, left_stat # Calculate statistic for the right side right_slice = _slice_at_axis( slice(right_index - right_length, right_index), axis) right_chunk = padded[right_slice] right_stat = stat_func(right_chunk, axis=axis, keepdims=True) _round_if_needed(right_stat, padded.dtype) return left_stat, right_stat def _set_reflect_both(padded, axis, width_pair, method, include_edge=False): """ Pad `axis` of `arr` with reflection. Parameters ---------- padded : ndarray Input array of arbitrary shape. axis : int Axis along which to pad `arr`. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. method : str Controls method of reflection; options are 'even' or 'odd'. include_edge : bool If true, edge value is included in reflection, otherwise the edge value forms the symmetric axis to the reflection. Returns ------- pad_amt : tuple of ints, length 2 New index positions of padding to do along the `axis`. If these are both 0, padding is done in this dimension. """ left_pad, right_pad = width_pair old_length = padded.shape[axis] - right_pad - left_pad if include_edge: # Edge is included, we need to offset the pad amount by 1 edge_offset = 1 else: edge_offset = 0 # Edge is not included, no need to offset pad amount old_length -= 1 # but must be omitted from the chunk if left_pad > 0: # Pad with reflected values on left side: # First limit chunk size which can't be larger than pad area chunk_length = min(old_length, left_pad) # Slice right to left, stop on or next to edge, start relative to stop stop = left_pad - edge_offset start = stop + chunk_length left_slice = _slice_at_axis(slice(start, stop, -1), axis) left_chunk = padded[left_slice] if method == "odd": # Negate chunk and align with edge edge_slice = _slice_at_axis(slice(left_pad, left_pad + 1), axis) left_chunk = 2 * padded[edge_slice] - left_chunk # Insert chunk into padded area start = left_pad - chunk_length stop = left_pad pad_area = _slice_at_axis(slice(start, stop), axis) padded[pad_area] = left_chunk # Adjust pointer to left edge for next iteration left_pad -= chunk_length if right_pad > 0: # Pad with reflected values on right side: # First limit chunk size which can't be larger than pad area chunk_length = min(old_length, right_pad) # Slice right to left, start on or next to edge, stop relative to start start = -right_pad + edge_offset - 2 stop = start - chunk_length right_slice = _slice_at_axis(slice(start, stop, -1), axis) right_chunk = padded[right_slice] if method == "odd": # Negate chunk and align with edge edge_slice = _slice_at_axis( slice(-right_pad - 1, -right_pad), axis) right_chunk = 2 * padded[edge_slice] - right_chunk # Insert chunk into padded area start = padded.shape[axis] - right_pad stop = start + chunk_length pad_area = _slice_at_axis(slice(start, stop), axis) padded[pad_area] = right_chunk # Adjust pointer to right edge for next iteration right_pad -= chunk_length return left_pad, right_pad def _set_wrap_both(padded, axis, width_pair, original_period): """ Pad `axis` of `arr` with wrapped values. Parameters ---------- padded : ndarray Input array of arbitrary shape. axis : int Axis along which to pad `arr`. width_pair : (int, int) Pair of widths that mark the pad area on both sides in the given dimension. original_period : int Original length of data on `axis` of `arr`. Returns ------- pad_amt : tuple of ints, length 2 New index positions of padding to do along the `axis`. If these are both 0, padding is done in this dimension. """ left_pad, right_pad = width_pair period = padded.shape[axis] - right_pad - left_pad # Avoid wrapping with only a subset of the original area by ensuring period # can only be a multiple of the original area's length. period = period // original_period * original_period # If the current dimension of `arr` doesn't contain enough valid values # (not part of the undefined pad area) we need to pad multiple times. # Each time the pad area shrinks on both sides which is communicated with # these variables. new_left_pad = 0 new_right_pad = 0 if left_pad > 0: # Pad with wrapped values on left side # First slice chunk from left side of the non-pad area. # Use min(period, left_pad) to ensure that chunk is not larger than # pad area. slice_end = left_pad + period slice_start = slice_end - min(period, left_pad) right_slice = _slice_at_axis(slice(slice_start, slice_end), axis) right_chunk = padded[right_slice] if left_pad > period: # Chunk is smaller than pad area pad_area = _slice_at_axis(slice(left_pad - period, left_pad), axis) new_left_pad = left_pad - period else: # Chunk matches pad area pad_area = _slice_at_axis(slice(None, left_pad), axis) padded[pad_area] = right_chunk if right_pad > 0: # Pad with wrapped values on right side # First slice chunk from right side of the non-pad area. # Use min(period, right_pad) to ensure that chunk is not larger than # pad area. slice_start = -right_pad - period slice_end = slice_start + min(period, right_pad) left_slice = _slice_at_axis(slice(slice_start, slice_end), axis) left_chunk = padded[left_slice] if right_pad > period: # Chunk is smaller than pad area pad_area = _slice_at_axis( slice(-right_pad, -right_pad + period), axis) new_right_pad = right_pad - period else: # Chunk matches pad area pad_area = _slice_at_axis(slice(-right_pad, None), axis) padded[pad_area] = left_chunk return new_left_pad, new_right_pad def _as_pairs(x, ndim, as_index=False): """ Broadcast `x` to an array with the shape (`ndim`, 2). A helper function for `pad` that prepares and validates arguments like `pad_width` for iteration in pairs. Parameters ---------- x : {None, scalar, array-like} The object to broadcast to the shape (`ndim`, 2). ndim : int Number of pairs the broadcasted `x` will have. as_index : bool, optional If `x` is not None, try to round each element of `x` to an integer (dtype `np.intp`) and ensure every element is positive. Returns ------- pairs : nested iterables, shape (`ndim`, 2) The broadcasted version of `x`. Raises ------ ValueError If `as_index` is True and `x` contains negative elements. Or if `x` is not broadcastable to the shape (`ndim`, 2). """ if x is None: # Pass through None as a special case, otherwise np.round(x) fails # with an AttributeError return ((None, None),) * ndim x = np.array(x) if as_index: x = np.round(x).astype(np.intp, copy=False) if x.ndim < 3: # Optimization: Possibly use faster paths for cases where `x` has # only 1 or 2 elements. `np.broadcast_to` could handle these as well # but is currently slower if x.size == 1: # x was supplied as a single value x = x.ravel() # Ensure x[0] works for x.ndim == 0, 1, 2 if as_index and x < 0: raise ValueError("index can't contain negative values") return ((x[0], x[0]),) * ndim if x.size == 2 and x.shape != (2, 1): # x was supplied with a single value for each side # but except case when each dimension has a single value # which should be broadcasted to a pair, # e.g. [[1], [2]] -> [[1, 1], [2, 2]] not [[1, 2], [1, 2]] x = x.ravel() # Ensure x[0], x[1] works if as_index and (x[0] < 0 or x[1] < 0): raise ValueError("index can't contain negative values") return ((x[0], x[1]),) * ndim if as_index and x.min() < 0: raise ValueError("index can't contain negative values") # Converting the array with `tolist` seems to improve performance # when iterating and indexing the result (see usage in `pad`) return np.broadcast_to(x, (ndim, 2)).tolist() def _pad_dispatcher(array, pad_width, mode=None, kwargs): return (array,) ############################################################################### # Public functions @array_function_dispatch(_pad_dispatcher, module='numpy') def pad(array, pad_width, mode='constant', kwargs): """ Pad an array. Parameters ---------- array : array_like of rank N The array to pad. pad_width : {sequence, array_like, int} Number of values padded to the edges of each axis. ``((before_1, after_1), ... (before_N, after_N))`` unique pad widths for each axis. ``(before, after)`` or ``((before, after),)`` yields same before and after pad for each axis. ``(pad,)`` or ``int`` is a shortcut for before = after = pad width for all axes. mode : str or function, optional One of the following string values or a user supplied function. 'constant' (default) Pads with a constant value. 'edge' Pads with the edge values of array. 'linear_ramp' Pads with the linear ramp between end_value and the array edge value. 'maximum' Pads with the maximum value of all or part of the vector along each axis. 'mean' Pads with the mean value of all or part of the vector along each axis. 'median' Pads with the median value of all or part of the vector along each axis. 'minimum' Pads with the minimum value of all or part of the vector along each axis. 'reflect' Pads with the reflection of the vector mirrored on the first and last values of the vector along each axis. 'symmetric' Pads with the reflection of the vector mirrored along the edge of the array. 'wrap' Pads with the wrap of the vector along the axis. The first values are used to pad the end and the end values are used to pad the beginning. 'empty' Pads with undefined values. .. versionadded:: 1.17 <function> Padding function, see Notes. stat_length : sequence or int, optional Used in 'maximum', 'mean', 'median', and 'minimum'. Number of values at edge of each axis used to calculate the statistic value. ``((before_1, after_1), ... (before_N, after_N))`` unique statistic lengths for each axis. ``(before, after)`` or ``((before, after),)`` yields same before and after statistic lengths for each axis. ``(stat_length,)`` or ``int`` is a shortcut for ``before = after = statistic`` length for all axes. Default is ``None``, to use the entire axis. constant_values : sequence or scalar, optional Used in 'constant'. The values to set the padded values for each axis. ``((before_1, after_1), ... (before_N, after_N))`` unique pad constants for each axis. ``(before, after)`` or ``((before, after),)`` yields same before and after constants for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. Default is 0. end_values : sequence or scalar, optional Used in 'linear_ramp'. The values used for the ending value of the linear_ramp and that will form the edge of the padded array. ``((before_1, after_1), ... (before_N, after_N))`` unique end values for each axis. ``(before, after)`` or ``((before, after),)`` yields same before and after end values for each axis. ``(constant,)`` or ``constant`` is a shortcut for ``before = after = constant`` for all axes. Default is 0. reflect_type : {'even', 'odd'}, optional Used in 'reflect', and 'symmetric'. The 'even' style is the default with an unaltered reflection around the edge value. For the 'odd' style, the extended part of the array is created by subtracting the reflected values from two times the edge value. Returns ------- pad : ndarray Padded array of rank equal to `array` with shape increased according to `pad_width`. Notes ----- .. versionadded:: 1.7.0 For an array with rank greater than 1, some of the padding of later axes is calculated from padding of previous axes. This is easiest to think about with a rank 2 array where the corners of the padded array are calculated by using padded values from the first axis. The padding function, if used, should modify a rank 1 array in-place. It has the following signature:: padding_func(vector, iaxis_pad_width, iaxis, kwargs) where vector : ndarray A rank 1 array already padded with zeros. Padded values are vector[:iaxis_pad_width[0]] and vector[-iaxis_pad_width[1]:]. iaxis_pad_width : tuple A 2-tuple of ints, iaxis_pad_width[0] represents the number of values padded at the beginning of vector where iaxis_pad_width[1] represents the number of values padded at the end of vector. iaxis : int The axis currently being calculated. kwargs : dict Any keyword arguments the function requires. Examples -------- >>> a = [1, 2, 3, 4, 5] >>> np.pad(a, (2, 3), 'constant', constant_values=(4, 6)) array([4, 4, 1, ..., 6, 6, 6]) >>> np.pad(a, (2, 3), 'edge') array([1, 1, 1, ..., 5, 5, 5]) >>> np.pad(a, (2, 3), 'linear_ramp', end_values=(5, -4)) array([ 5, 3, 1, 2, 3, 4, 5, 2, -1, -4]) >>> np.pad(a, (2,), 'maximum') array([5, 5, 1, 2, 3, 4, 5, 5, 5]) >>> np.pad(a, (2,), 'mean') array([3, 3, 1, 2, 3, 4, 5, 3, 3]) >>> np.pad(a, (2,), 'median') array([3, 3, 1, 2, 3, 4, 5, 3, 3]) >>> a = [[1, 2], [3, 4]] >>> np.pad(a, ((3, 2), (2, 3)), 'minimum') array([[1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1], [3, 3, 3, 4, 3, 3, 3], [1, 1, 1, 2, 1, 1, 1], [1, 1, 1, 2, 1, 1, 1]]) >>> a = [1, 2, 3, 4, 5] >>> np.pad(a, (2, 3), 'reflect') array([3, 2, 1, 2, 3, 4, 5, 4, 3, 2]) >>> np.pad(a, (2, 3), 'reflect', reflect_type='odd') array([-1, 0, 1, 2, 3, 4, 5, 6, 7, 8]) >>> np.pad(a, (2, 3), 'symmetric') array([2, 1, 1, 2, 3, 4, 5, 5, 4, 3]) >>> np.pad(a, (2, 3), 'symmetric', reflect_type='odd') array([0, 1, 1, 2, 3, 4, 5, 5, 6, 7]) >>> np.pad(a, (2, 3), 'wrap') array([4, 5, 1, 2, 3, 4, 5, 1, 2, 3]) >>> def pad_with(vector, pad_width, iaxis, kwargs): ... pad_value = kwargs.get('padder', 10) ... vector[:pad_width[0]] = pad_value ... vector[-pad_width[1]:] = pad_value >>> a = np.arange(6) >>> a = a.reshape((2, 3)) >>> np.pad(a, 2, pad_with) array([[10, 10, 10, 10, 10, 10, 10], [10, 10, 10, 10, 10, 10, 10], [10, 10, 0, 1, 2, 10, 10], [10, 10, 3, 4, 5, 10, 10], [10, 10, 10, 10, 10, 10, 10], [10, 10, 10, 10, 10, 10, 10]]) >>> np.pad(a, 2, pad_with, padder=100) array([[100, 100, 100, 100, 100, 100, 100], [100, 100, 100, 100, 100, 100, 100], [100, 100, 0, 1, 2, 100, 100], [100, 100, 3, 4, 5, 100, 100], [100, 100, 100, 100, 100, 100, 100], [100, 100, 100, 100, 100, 100, 100]]) """ array = np.asarray(array) pad_width = np.asarray(pad_width) if not pad_width.dtype.kind == 'i': raise TypeError('`pad_width` must be of integral type.') # Broadcast to shape (array.ndim, 2) pad_width = _as_pairs(pad_width, array.ndim, as_index=True) if callable(mode): # Old behavior: Use user-supplied function with np.apply_along_axis function = mode # Create a new zero padded array padded, _ = _pad_simple(array, pad_width, fill_value=0) # And apply along each axis for axis in range(padded.ndim): # Iterate using ndindex as in apply_along_axis, but assuming that # function operates inplace on the padded array. # view with the iteration axis at the end view = np.moveaxis(padded, axis, -1) # compute indices for the iteration axes, and append a trailing # ellipsis to prevent 0d arrays decaying to scalars (gh-8642) inds = ndindex(view.shape[:-1]) inds = (ind + (Ellipsis,) for ind in inds) for ind in inds: function(view[ind], pad_width[axis], axis, kwargs) return padded # Make sure that no unsupported keywords were passed for the current mode allowed_kwargs = { 'empty': [], 'edge': [], 'wrap': [], 'constant': ['constant_values'], 'linear_ramp': ['end_values'], 'maximum': ['stat_length'], 'mean': ['stat_length'], 'median': ['stat_length'], 'minimum': ['stat_length'], 'reflect': ['reflect_type'], 'symmetric': ['reflect_type'], } try: unsupported_kwargs = set(kwargs) - set(allowed_kwargs[mode]) except KeyError: raise ValueError("mode '{}' is not supported".format(mode)) from None if unsupported_kwargs: raise ValueError("unsupported keyword arguments for mode '{}': {}" .format(mode, unsupported_kwargs)) stat_functions = {"maximum": np.amax, "minimum": np.amin, "mean": np.mean, "median": np.median} # Create array with final shape and original values # (padded area is undefined) padded, original_area_slice = _pad_simple(array, pad_width) # And prepare iteration over all dimensions # (zipping may be more readable than using enumerate) axes = range(padded.ndim) if mode == "constant": values = kwargs.get("constant_values", 0) values = _as_pairs(values, padded.ndim) for axis, width_pair, value_pair in zip(axes, pad_width, values): roi = _view_roi(padded, original_area_slice, axis) _set_pad_area(roi, axis, width_pair, value_pair) elif mode == "empty": pass # Do nothing as _pad_simple already returned the correct result elif array.size == 0: # Only modes "constant" and "empty" can extend empty axes, all other # modes depend on `array` not being empty # -> ensure every empty axis is only "padded with 0" for axis, width_pair in zip(axes, pad_width): if array.shape[axis] == 0 and any(width_pair): raise ValueError( "can't extend empty axis {} using modes other than " "'constant' or 'empty'".format(axis) ) # passed, don't need to do anything more as _pad_simple already # returned the correct result elif mode == "edge": for axis, width_pair in zip(axes, pad_width): roi = _view_roi(padded, original_area_slice, axis) edge_pair = _get_edges(roi, axis, width_pair) _set_pad_area(roi, axis, width_pair, edge_pair) elif mode == "linear_ramp": end_values = kwargs.get("end_values", 0) end_values = _as_pairs(end_values, padded.ndim) for axis, width_pair, value_pair in zip(axes, pad_width, end_values): roi = _view_roi(padded, original_area_slice, axis) ramp_pair = _get_linear_ramps(roi, axis, width_pair, value_pair) _set_pad_area(roi, axis, width_pair, ramp_pair) elif mode in stat_functions: func = stat_functions[mode] length = kwargs.get("stat_length", None) length = _as_pairs(length, padded.ndim, as_index=True) for axis, width_pair, length_pair in zip(axes, pad_width, length): roi = _view_roi(padded, original_area_slice, axis) stat_pair = _get_stats(roi, axis, width_pair, length_pair, func) _set_pad_area(roi, axis, width_pair, stat_pair) elif mode in {"reflect", "symmetric"}: method = kwargs.get("reflect_type", "even") include_edge = True if mode == "symmetric" else False for axis, (left_index, right_index) in zip(axes, pad_width): if array.shape[axis] == 1 and (left_index > 0 or right_index > 0): # Extending singleton dimension for 'reflect' is legacy # behavior; it really should raise an error. edge_pair = _get_edges(padded, axis, (left_index, right_index)) _set_pad_area( padded, axis, (left_index, right_index), edge_pair) continue roi = _view_roi(padded, original_area_slice, axis) while left_index > 0 or right_index > 0: # Iteratively pad until dimension is filled with reflected # values. This is necessary if the pad area is larger than # the length of the original values in the current dimension. left_index, right_index = _set_reflect_both( roi, axis, (left_index, right_index), method, include_edge ) elif mode == "wrap": for axis, (left_index, right_index) in zip(axes, pad_width): roi = _view_roi(padded, original_area_slice, axis) original_period = padded.shape[axis] - right_index - left_index while left_index > 0 or right_index > 0: # Iteratively pad until dimension is filled with wrapped # values. This is necessary if the pad area is larger than # the length of the original values in the current dimension. left_index, right_index = _set_wrap_both( roi, axis, (left_index, right_index), original_period) return padded	31.06 KB	2026-01-20 12:58
📄 arraypad.pyi from typing import ( Literal as L, Any, overload, TypeVar, Protocol, ) from numpy import generic from numpy._typing import ( ArrayLike, NDArray, _ArrayLikeInt, _ArrayLike, ) _SCT = TypeVar("_SCT", bound=generic) class _ModeFunc(Protocol): def __call__( self, vector: NDArray[Any], iaxis_pad_width: tuple[int, int], iaxis: int, kwargs: dict[str, Any], /, ) -> None: ... _ModeKind = L[ "constant", "edge", "linear_ramp", "maximum", "mean", "median", "minimum", "reflect", "symmetric", "wrap", "empty", ] __all__: list[str] # TODO: In practice each keyword argument is exclusive to one or more # specific modes. Consider adding more overloads to express this in the future. # Expand `*kwargs` into explicit keyword-only arguments @overload def pad( array: _ArrayLike[_SCT], pad_width: _ArrayLikeInt, mode: _ModeKind = ..., , stat_length: None \| _ArrayLikeInt = ..., constant_values: ArrayLike = ..., end_values: ArrayLike = ..., reflect_type: L["odd", "even"] = ..., ) -> NDArray[_SCT]: ... @overload def pad( array: ArrayLike, pad_width: _ArrayLikeInt, mode: _ModeKind = ..., , stat_length: None \| _ArrayLikeInt = ..., constant_values: ArrayLike = ..., end_values: ArrayLike = ..., reflect_type: L["odd", "even"] = ..., ) -> NDArray[Any]: ... @overload def pad( array: _ArrayLike[_SCT], pad_width: _ArrayLikeInt, mode: _ModeFunc, kwargs: Any, ) -> NDArray[_SCT]: ... @overload def pad( array: ArrayLike, pad_width: _ArrayLikeInt, mode: _ModeFunc, *kwargs: Any, ) -> NDArray[Any]: ...	1.69 KB	2026-01-20 12:58
📄 arraysetops.py """ Set operations for arrays based on sorting. Notes ----- For floating point arrays, inaccurate results may appear due to usual round-off and floating point comparison issues. Speed could be gained in some operations by an implementation of `numpy.sort`, that can provide directly the permutation vectors, thus avoiding calls to `numpy.argsort`. Original author: Robert Cimrman """ import functools import numpy as np from numpy.core import overrides array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') __all__ = [ 'ediff1d', 'intersect1d', 'setxor1d', 'union1d', 'setdiff1d', 'unique', 'in1d', 'isin' ] def _ediff1d_dispatcher(ary, to_end=None, to_begin=None): return (ary, to_end, to_begin) @array_function_dispatch(_ediff1d_dispatcher) def ediff1d(ary, to_end=None, to_begin=None): """ The differences between consecutive elements of an array. Parameters ---------- ary : array_like If necessary, will be flattened before the differences are taken. to_end : array_like, optional Number(s) to append at the end of the returned differences. to_begin : array_like, optional Number(s) to prepend at the beginning of the returned differences. Returns ------- ediff1d : ndarray The differences. Loosely, this is ``ary.flat[1:] - ary.flat[:-1]``. See Also -------- diff, gradient Notes ----- When applied to masked arrays, this function drops the mask information if the `to_begin` and/or `to_end` parameters are used. Examples -------- >>> x = np.array([1, 2, 4, 7, 0]) >>> np.ediff1d(x) array([ 1, 2, 3, -7]) >>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99])) array([-99, 1, 2, ..., -7, 88, 99]) The returned array is always 1D. >>> y = [[1, 2, 4], [1, 6, 24]] >>> np.ediff1d(y) array([ 1, 2, -3, 5, 18]) """ # force a 1d array ary = np.asanyarray(ary).ravel() # enforce that the dtype of `ary` is used for the output dtype_req = ary.dtype # fast track default case if to_begin is None and to_end is None: return ary[1:] - ary[:-1] if to_begin is None: l_begin = 0 else: to_begin = np.asanyarray(to_begin) if not np.can_cast(to_begin, dtype_req, casting="same_kind"): raise TypeError("dtype of `to_begin` must be compatible " "with input `ary` under the `same_kind` rule.") to_begin = to_begin.ravel() l_begin = len(to_begin) if to_end is None: l_end = 0 else: to_end = np.asanyarray(to_end) if not np.can_cast(to_end, dtype_req, casting="same_kind"): raise TypeError("dtype of `to_end` must be compatible " "with input `ary` under the `same_kind` rule.") to_end = to_end.ravel() l_end = len(to_end) # do the calculation in place and copy to_begin and to_end l_diff = max(len(ary) - 1, 0) result = np.empty(l_diff + l_begin + l_end, dtype=ary.dtype) result = ary.__array_wrap__(result) if l_begin > 0: result[:l_begin] = to_begin if l_end > 0: result[l_begin + l_diff:] = to_end np.subtract(ary[1:], ary[:-1], result[l_begin:l_begin + l_diff]) return result def _unpack_tuple(x): """ Unpacks one-element tuples for use as return values """ if len(x) == 1: return x[0] else: return x def _unique_dispatcher(ar, return_index=None, return_inverse=None, return_counts=None, axis=None, , equal_nan=None): return (ar,) @array_function_dispatch(_unique_dispatcher) def unique(ar, return_index=False, return_inverse=False, return_counts=False, axis=None, , equal_nan=True): """ Find the unique elements of an array. Returns the sorted unique elements of an array. There are three optional outputs in addition to the unique elements: * the indices of the input array that give the unique values * the indices of the unique array that reconstruct the input array * the number of times each unique value comes up in the input array Parameters ---------- ar : array_like Input array. Unless `axis` is specified, this will be flattened if it is not already 1-D. return_index : bool, optional If True, also return the indices of `ar` (along the specified axis, if provided, or in the flattened array) that result in the unique array. return_inverse : bool, optional If True, also return the indices of the unique array (for the specified axis, if provided) that can be used to reconstruct `ar`. return_counts : bool, optional If True, also return the number of times each unique item appears in `ar`. axis : int or None, optional The axis to operate on. If None, `ar` will be flattened. If an integer, the subarrays indexed by the given axis will be flattened and treated as the elements of a 1-D array with the dimension of the given axis, see the notes for more details. Object arrays or structured arrays that contain objects are not supported if the `axis` kwarg is used. The default is None. .. versionadded:: 1.13.0 equal_nan : bool, optional If True, collapses multiple NaN values in the return array into one. .. versionadded:: 1.24 Returns ------- unique : ndarray The sorted unique values. unique_indices : ndarray, optional The indices of the first occurrences of the unique values in the original array. Only provided if `return_index` is True. unique_inverse : ndarray, optional The indices to reconstruct the original array from the unique array. Only provided if `return_inverse` is True. unique_counts : ndarray, optional The number of times each of the unique values comes up in the original array. Only provided if `return_counts` is True. .. versionadded:: 1.9.0 See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. repeat : Repeat elements of an array. Notes ----- When an axis is specified the subarrays indexed by the axis are sorted. This is done by making the specified axis the first dimension of the array (move the axis to the first dimension to keep the order of the other axes) and then flattening the subarrays in C order. The flattened subarrays are then viewed as a structured type with each element given a label, with the effect that we end up with a 1-D array of structured types that can be treated in the same way as any other 1-D array. The result is that the flattened subarrays are sorted in lexicographic order starting with the first element. .. versionchanged: NumPy 1.21 If nan values are in the input array, a single nan is put to the end of the sorted unique values. Also for complex arrays all NaN values are considered equivalent (no matter whether the NaN is in the real or imaginary part). As the representant for the returned array the smallest one in the lexicographical order is chosen - see np.sort for how the lexicographical order is defined for complex arrays. Examples -------- >>> np.unique([1, 1, 2, 2, 3, 3]) array([1, 2, 3]) >>> a = np.array([[1, 1], [2, 3]]) >>> np.unique(a) array([1, 2, 3]) Return the unique rows of a 2D array >>> a = np.array([[1, 0, 0], [1, 0, 0], [2, 3, 4]]) >>> np.unique(a, axis=0) array([[1, 0, 0], [2, 3, 4]]) Return the indices of the original array that give the unique values: >>> a = np.array(['a', 'b', 'b', 'c', 'a']) >>> u, indices = np.unique(a, return_index=True) >>> u array(['a', 'b', 'c'], dtype='<U1') >>> indices array([0, 1, 3]) >>> a[indices] array(['a', 'b', 'c'], dtype='<U1') Reconstruct the input array from the unique values and inverse: >>> a = np.array([1, 2, 6, 4, 2, 3, 2]) >>> u, indices = np.unique(a, return_inverse=True) >>> u array([1, 2, 3, 4, 6]) >>> indices array([0, 1, 4, 3, 1, 2, 1]) >>> u[indices] array([1, 2, 6, 4, 2, 3, 2]) Reconstruct the input values from the unique values and counts: >>> a = np.array([1, 2, 6, 4, 2, 3, 2]) >>> values, counts = np.unique(a, return_counts=True) >>> values array([1, 2, 3, 4, 6]) >>> counts array([1, 3, 1, 1, 1]) >>> np.repeat(values, counts) array([1, 2, 2, 2, 3, 4, 6]) # original order not preserved """ ar = np.asanyarray(ar) if axis is None: ret = _unique1d(ar, return_index, return_inverse, return_counts, equal_nan=equal_nan) return _unpack_tuple(ret) # axis was specified and not None try: ar = np.moveaxis(ar, axis, 0) except np.AxisError: # this removes the "axis1" or "axis2" prefix from the error message raise np.AxisError(axis, ar.ndim) from None # Must reshape to a contiguous 2D array for this to work... orig_shape, orig_dtype = ar.shape, ar.dtype ar = ar.reshape(orig_shape[0], np.prod(orig_shape[1:], dtype=np.intp)) ar = np.ascontiguousarray(ar) dtype = [('f{i}'.format(i=i), ar.dtype) for i in range(ar.shape[1])] # At this point, `ar` has shape `(n, m)`, and `dtype` is a structured # data type with `m` fields where each field has the data type of `ar`. # In the following, we create the array `consolidated`, which has # shape `(n,)` with data type `dtype`. try: if ar.shape[1] > 0: consolidated = ar.view(dtype) else: # If ar.shape[1] == 0, then dtype will be `np.dtype([])`, which is # a data type with itemsize 0, and the call `ar.view(dtype)` will # fail. Instead, we'll use `np.empty` to explicitly create the # array with shape `(len(ar),)`. Because `dtype` in this case has # itemsize 0, the total size of the result is still 0 bytes. consolidated = np.empty(len(ar), dtype=dtype) except TypeError as e: # There's no good way to do this for object arrays, etc... msg = 'The axis argument to unique is not supported for dtype {dt}' raise TypeError(msg.format(dt=ar.dtype)) from e def reshape_uniq(uniq): n = len(uniq) uniq = uniq.view(orig_dtype) uniq = uniq.reshape(n, orig_shape[1:]) uniq = np.moveaxis(uniq, 0, axis) return uniq output = _unique1d(consolidated, return_index, return_inverse, return_counts, equal_nan=equal_nan) output = (reshape_uniq(output[0]),) + output[1:] return _unpack_tuple(output) def _unique1d(ar, return_index=False, return_inverse=False, return_counts=False, , equal_nan=True): """ Find the unique elements of an array, ignoring shape. """ ar = np.asanyarray(ar).flatten() optional_indices = return_index or return_inverse if optional_indices: perm = ar.argsort(kind='mergesort' if return_index else 'quicksort') aux = ar[perm] else: ar.sort() aux = ar mask = np.empty(aux.shape, dtype=np.bool_) mask[:1] = True if (equal_nan and aux.shape[0] > 0 and aux.dtype.kind in "cfmM" and np.isnan(aux[-1])): if aux.dtype.kind == "c": # for complex all NaNs are considered equivalent aux_firstnan = np.searchsorted(np.isnan(aux), True, side='left') else: aux_firstnan = np.searchsorted(aux, aux[-1], side='left') if aux_firstnan > 0: mask[1:aux_firstnan] = ( aux[1:aux_firstnan] != aux[:aux_firstnan - 1]) mask[aux_firstnan] = True mask[aux_firstnan + 1:] = False else: mask[1:] = aux[1:] != aux[:-1] ret = (aux[mask],) if return_index: ret += (perm[mask],) if return_inverse: imask = np.cumsum(mask) - 1 inv_idx = np.empty(mask.shape, dtype=np.intp) inv_idx[perm] = imask ret += (inv_idx,) if return_counts: idx = np.concatenate(np.nonzero(mask) + ([mask.size],)) ret += (np.diff(idx),) return ret def _intersect1d_dispatcher( ar1, ar2, assume_unique=None, return_indices=None): return (ar1, ar2) @array_function_dispatch(_intersect1d_dispatcher) def intersect1d(ar1, ar2, assume_unique=False, return_indices=False): """ Find the intersection of two arrays. Return the sorted, unique values that are in both of the input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. Will be flattened if not already 1D. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. If True but ``ar1`` or ``ar2`` are not unique, incorrect results and out-of-bounds indices could result. Default is False. return_indices : bool If True, the indices which correspond to the intersection of the two arrays are returned. The first instance of a value is used if there are multiple. Default is False. .. versionadded:: 1.15.0 Returns ------- intersect1d : ndarray Sorted 1D array of common and unique elements. comm1 : ndarray The indices of the first occurrences of the common values in `ar1`. Only provided if `return_indices` is True. comm2 : ndarray The indices of the first occurrences of the common values in `ar2`. Only provided if `return_indices` is True. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> np.intersect1d([1, 3, 4, 3], [3, 1, 2, 1]) array([1, 3]) To intersect more than two arrays, use functools.reduce: >>> from functools import reduce >>> reduce(np.intersect1d, ([1, 3, 4, 3], [3, 1, 2, 1], [6, 3, 4, 2])) array([3]) To return the indices of the values common to the input arrays along with the intersected values: >>> x = np.array([1, 1, 2, 3, 4]) >>> y = np.array([2, 1, 4, 6]) >>> xy, x_ind, y_ind = np.intersect1d(x, y, return_indices=True) >>> x_ind, y_ind (array([0, 2, 4]), array([1, 0, 2])) >>> xy, x[x_ind], y[y_ind] (array([1, 2, 4]), array([1, 2, 4]), array([1, 2, 4])) """ ar1 = np.asanyarray(ar1) ar2 = np.asanyarray(ar2) if not assume_unique: if return_indices: ar1, ind1 = unique(ar1, return_index=True) ar2, ind2 = unique(ar2, return_index=True) else: ar1 = unique(ar1) ar2 = unique(ar2) else: ar1 = ar1.ravel() ar2 = ar2.ravel() aux = np.concatenate((ar1, ar2)) if return_indices: aux_sort_indices = np.argsort(aux, kind='mergesort') aux = aux[aux_sort_indices] else: aux.sort() mask = aux[1:] == aux[:-1] int1d = aux[:-1][mask] if return_indices: ar1_indices = aux_sort_indices[:-1][mask] ar2_indices = aux_sort_indices[1:][mask] - ar1.size if not assume_unique: ar1_indices = ind1[ar1_indices] ar2_indices = ind2[ar2_indices] return int1d, ar1_indices, ar2_indices else: return int1d def _setxor1d_dispatcher(ar1, ar2, assume_unique=None): return (ar1, ar2) @array_function_dispatch(_setxor1d_dispatcher) def setxor1d(ar1, ar2, assume_unique=False): """ Find the set exclusive-or of two arrays. Return the sorted, unique values that are in only one (not both) of the input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. Returns ------- setxor1d : ndarray Sorted 1D array of unique values that are in only one of the input arrays. Examples -------- >>> a = np.array([1, 2, 3, 2, 4]) >>> b = np.array([2, 3, 5, 7, 5]) >>> np.setxor1d(a,b) array([1, 4, 5, 7]) """ if not assume_unique: ar1 = unique(ar1) ar2 = unique(ar2) aux = np.concatenate((ar1, ar2)) if aux.size == 0: return aux aux.sort() flag = np.concatenate(([True], aux[1:] != aux[:-1], [True])) return aux[flag[1:] & flag[:-1]] def _in1d_dispatcher(ar1, ar2, assume_unique=None, invert=None, , kind=None): return (ar1, ar2) @array_function_dispatch(_in1d_dispatcher) def in1d(ar1, ar2, assume_unique=False, invert=False, , kind=None): """ Test whether each element of a 1-D array is also present in a second array. Returns a boolean array the same length as `ar1` that is True where an element of `ar1` is in `ar2` and False otherwise. We recommend using :func:`isin` instead of `in1d` for new code. Parameters ---------- ar1 : (M,) array_like Input array. ar2 : array_like The values against which to test each value of `ar1`. assume_unique : bool, optional If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. invert : bool, optional If True, the values in the returned array are inverted (that is, False where an element of `ar1` is in `ar2` and True otherwise). Default is False. ``np.in1d(a, b, invert=True)`` is equivalent to (but is faster than) ``np.invert(in1d(a, b))``. kind : {None, 'sort', 'table'}, optional The algorithm to use. This will not affect the final result, but will affect the speed and memory use. The default, None, will select automatically based on memory considerations. * If 'sort', will use a mergesort-based approach. This will have a memory usage of roughly 6 times the sum of the sizes of `ar1` and `ar2`, not accounting for size of dtypes. * If 'table', will use a lookup table approach similar to a counting sort. This is only available for boolean and integer arrays. This will have a memory usage of the size of `ar1` plus the max-min value of `ar2`. `assume_unique` has no effect when the 'table' option is used. * If None, will automatically choose 'table' if the required memory allocation is less than or equal to 6 times the sum of the sizes of `ar1` and `ar2`, otherwise will use 'sort'. This is done to not use a large amount of memory by default, even though 'table' may be faster in most cases. If 'table' is chosen, `assume_unique` will have no effect. .. versionadded:: 1.8.0 Returns ------- in1d : (M,) ndarray, bool The values `ar1[in1d]` are in `ar2`. See Also -------- isin : Version of this function that preserves the shape of ar1. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Notes ----- `in1d` can be considered as an element-wise function version of the python keyword `in`, for 1-D sequences. ``in1d(a, b)`` is roughly equivalent to ``np.array([item in b for item in a])``. However, this idea fails if `ar2` is a set, or similar (non-sequence) container: As ``ar2`` is converted to an array, in those cases ``asarray(ar2)`` is an object array rather than the expected array of contained values. Using ``kind='table'`` tends to be faster than `kind='sort'` if the following relationship is true: ``log10(len(ar2)) > (log10(max(ar2)-min(ar2)) - 2.27) / 0.927``, but may use greater memory. The default value for `kind` will be automatically selected based only on memory usage, so one may manually set ``kind='table'`` if memory constraints can be relaxed. .. versionadded:: 1.4.0 Examples -------- >>> test = np.array([0, 1, 2, 5, 0]) >>> states = [0, 2] >>> mask = np.in1d(test, states) >>> mask array([ True, False, True, False, True]) >>> test[mask] array([0, 2, 0]) >>> mask = np.in1d(test, states, invert=True) >>> mask array([False, True, False, True, False]) >>> test[mask] array([1, 5]) """ # Ravel both arrays, behavior for the first array could be different ar1 = np.asarray(ar1).ravel() ar2 = np.asarray(ar2).ravel() # Ensure that iteration through object arrays yields size-1 arrays if ar2.dtype == object: ar2 = ar2.reshape(-1, 1) if kind not in {None, 'sort', 'table'}: raise ValueError( f"Invalid kind: '{kind}'. Please use None, 'sort' or 'table'.") # Can use the table method if all arrays are integers or boolean: is_int_arrays = all(ar.dtype.kind in ("u", "i", "b") for ar in (ar1, ar2)) use_table_method = is_int_arrays and kind in {None, 'table'} if use_table_method: if ar2.size == 0: if invert: return np.ones_like(ar1, dtype=bool) else: return np.zeros_like(ar1, dtype=bool) # Convert booleans to uint8 so we can use the fast integer algorithm if ar1.dtype == bool: ar1 = ar1.astype(np.uint8) if ar2.dtype == bool: ar2 = ar2.astype(np.uint8) ar2_min = np.min(ar2) ar2_max = np.max(ar2) ar2_range = int(ar2_max) - int(ar2_min) # Constraints on whether we can actually use the table method: # 1. Assert memory usage is not too large below_memory_constraint = ar2_range <= 6 * (ar1.size + ar2.size) # 2. Check overflows for (ar2 - ar2_min); dtype=ar2.dtype range_safe_from_overflow = ar2_range <= np.iinfo(ar2.dtype).max # 3. Check overflows for (ar1 - ar2_min); dtype=ar1.dtype if ar1.size > 0: ar1_min = np.min(ar1) ar1_max = np.max(ar1) # After masking, the range of ar1 is guaranteed to be # within the range of ar2: ar1_upper = min(int(ar1_max), int(ar2_max)) ar1_lower = max(int(ar1_min), int(ar2_min)) range_safe_from_overflow &= all(( ar1_upper - int(ar2_min) <= np.iinfo(ar1.dtype).max, ar1_lower - int(ar2_min) >= np.iinfo(ar1.dtype).min )) # Optimal performance is for approximately # log10(size) > (log10(range) - 2.27) / 0.927. # However, here we set the requirement that by default # the intermediate array can only be 6x # the combined memory allocation of the original # arrays. See discussion on # https://github.com/numpy/numpy/pull/12065. if ( range_safe_from_overflow and (below_memory_constraint or kind == 'table') ): if invert: outgoing_array = np.ones_like(ar1, dtype=bool) else: outgoing_array = np.zeros_like(ar1, dtype=bool) # Make elements 1 where the integer exists in ar2 if invert: isin_helper_ar = np.ones(ar2_range + 1, dtype=bool) isin_helper_ar[ar2 - ar2_min] = 0 else: isin_helper_ar = np.zeros(ar2_range + 1, dtype=bool) isin_helper_ar[ar2 - ar2_min] = 1 # Mask out elements we know won't work basic_mask = (ar1 <= ar2_max) & (ar1 >= ar2_min) outgoing_array[basic_mask] = isin_helper_ar[ar1[basic_mask] - ar2_min] return outgoing_array elif kind == 'table': # not range_safe_from_overflow raise RuntimeError( "You have specified kind='table', " "but the range of values in `ar2` or `ar1` exceed the " "maximum integer of the datatype. " "Please set `kind` to None or 'sort'." ) elif kind == 'table': raise ValueError( "The 'table' method is only " "supported for boolean or integer arrays. " "Please select 'sort' or None for kind." ) # Check if one of the arrays may contain arbitrary objects contains_object = ar1.dtype.hasobject or ar2.dtype.hasobject # This code is run when # a) the first condition is true, making the code significantly faster # b) the second condition is true (i.e. `ar1` or `ar2` may contain # arbitrary objects), since then sorting is not guaranteed to work if len(ar2) < 10 * len(ar1) ** 0.145 or contains_object: if invert: mask = np.ones(len(ar1), dtype=bool) for a in ar2: mask &= (ar1 != a) else: mask = np.zeros(len(ar1), dtype=bool) for a in ar2: mask \|= (ar1 == a) return mask # Otherwise use sorting if not assume_unique: ar1, rev_idx = np.unique(ar1, return_inverse=True) ar2 = np.unique(ar2) ar = np.concatenate((ar1, ar2)) # We need this to be a stable sort, so always use 'mergesort' # here. The values from the first array should always come before # the values from the second array. order = ar.argsort(kind='mergesort') sar = ar[order] if invert: bool_ar = (sar[1:] != sar[:-1]) else: bool_ar = (sar[1:] == sar[:-1]) flag = np.concatenate((bool_ar, [invert])) ret = np.empty(ar.shape, dtype=bool) ret[order] = flag if assume_unique: return ret[:len(ar1)] else: return ret[rev_idx] def _isin_dispatcher(element, test_elements, assume_unique=None, invert=None, , kind=None): return (element, test_elements) @array_function_dispatch(_isin_dispatcher) def isin(element, test_elements, assume_unique=False, invert=False, , kind=None): """ Calculates ``element in test_elements``, broadcasting over `element` only. Returns a boolean array of the same shape as `element` that is True where an element of `element` is in `test_elements` and False otherwise. Parameters ---------- element : array_like Input array. test_elements : array_like The values against which to test each value of `element`. This argument is flattened if it is an array or array_like. See notes for behavior with non-array-like parameters. assume_unique : bool, optional If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. invert : bool, optional If True, the values in the returned array are inverted, as if calculating `element not in test_elements`. Default is False. ``np.isin(a, b, invert=True)`` is equivalent to (but faster than) ``np.invert(np.isin(a, b))``. kind : {None, 'sort', 'table'}, optional The algorithm to use. This will not affect the final result, but will affect the speed and memory use. The default, None, will select automatically based on memory considerations. * If 'sort', will use a mergesort-based approach. This will have a memory usage of roughly 6 times the sum of the sizes of `ar1` and `ar2`, not accounting for size of dtypes. * If 'table', will use a lookup table approach similar to a counting sort. This is only available for boolean and integer arrays. This will have a memory usage of the size of `ar1` plus the max-min value of `ar2`. `assume_unique` has no effect when the 'table' option is used. * If None, will automatically choose 'table' if the required memory allocation is less than or equal to 6 times the sum of the sizes of `ar1` and `ar2`, otherwise will use 'sort'. This is done to not use a large amount of memory by default, even though 'table' may be faster in most cases. If 'table' is chosen, `assume_unique` will have no effect. Returns ------- isin : ndarray, bool Has the same shape as `element`. The values `element[isin]` are in `test_elements`. See Also -------- in1d : Flattened version of this function. numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Notes ----- `isin` is an element-wise function version of the python keyword `in`. ``isin(a, b)`` is roughly equivalent to ``np.array([item in b for item in a])`` if `a` and `b` are 1-D sequences. `element` and `test_elements` are converted to arrays if they are not already. If `test_elements` is a set (or other non-sequence collection) it will be converted to an object array with one element, rather than an array of the values contained in `test_elements`. This is a consequence of the `array` constructor's way of handling non-sequence collections. Converting the set to a list usually gives the desired behavior. Using ``kind='table'`` tends to be faster than `kind='sort'` if the following relationship is true: ``log10(len(ar2)) > (log10(max(ar2)-min(ar2)) - 2.27) / 0.927``, but may use greater memory. The default value for `kind` will be automatically selected based only on memory usage, so one may manually set ``kind='table'`` if memory constraints can be relaxed. .. versionadded:: 1.13.0 Examples -------- >>> element = 2*np.arange(4).reshape((2, 2)) >>> element array([[0, 2], [4, 6]]) >>> test_elements = [1, 2, 4, 8] >>> mask = np.isin(element, test_elements) >>> mask array([[False, True], [ True, False]]) >>> element[mask] array([2, 4]) The indices of the matched values can be obtained with `nonzero`: >>> np.nonzero(mask) (array([0, 1]), array([1, 0])) The test can also be inverted: >>> mask = np.isin(element, test_elements, invert=True) >>> mask array([[ True, False], [False, True]]) >>> element[mask] array([0, 6]) Because of how `array` handles sets, the following does not work as expected: >>> test_set = {1, 2, 4, 8} >>> np.isin(element, test_set) array([[False, False], [False, False]]) Casting the set to a list gives the expected result: >>> np.isin(element, list(test_set)) array([[False, True], [ True, False]]) """ element = np.asarray(element) return in1d(element, test_elements, assume_unique=assume_unique, invert=invert, kind=kind).reshape(element.shape) def _union1d_dispatcher(ar1, ar2): return (ar1, ar2) @array_function_dispatch(_union1d_dispatcher) def union1d(ar1, ar2): """ Find the union of two arrays. Return the unique, sorted array of values that are in either of the two input arrays. Parameters ---------- ar1, ar2 : array_like Input arrays. They are flattened if they are not already 1D. Returns ------- union1d : ndarray Unique, sorted union of the input arrays. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> np.union1d([-1, 0, 1], [-2, 0, 2]) array([-2, -1, 0, 1, 2]) To find the union of more than two arrays, use functools.reduce: >>> from functools import reduce >>> reduce(np.union1d, ([1, 3, 4, 3], [3, 1, 2, 1], [6, 3, 4, 2])) array([1, 2, 3, 4, 6]) """ return unique(np.concatenate((ar1, ar2), axis=None)) def _setdiff1d_dispatcher(ar1, ar2, assume_unique=None): return (ar1, ar2) @array_function_dispatch(_setdiff1d_dispatcher) def setdiff1d(ar1, ar2, assume_unique=False): """ Find the set difference of two arrays. Return the unique values in `ar1` that are not in `ar2`. Parameters ---------- ar1 : array_like Input array. ar2 : array_like Input comparison array. assume_unique : bool If True, the input arrays are both assumed to be unique, which can speed up the calculation. Default is False. Returns ------- setdiff1d : ndarray 1D array of values in `ar1` that are not in `ar2`. The result is sorted when `assume_unique=False`, but otherwise only sorted if the input is sorted. See Also -------- numpy.lib.arraysetops : Module with a number of other functions for performing set operations on arrays. Examples -------- >>> a = np.array([1, 2, 3, 2, 4, 1]) >>> b = np.array([3, 4, 5, 6]) >>> np.setdiff1d(a, b) array([1, 2]) """ if assume_unique: ar1 = np.asarray(ar1).ravel() else: ar1 = unique(ar1) ar2 = unique(ar2) return ar1[in1d(ar1, ar2, assume_unique=True, invert=True)]	32.87 KB	2026-01-20 12:58
📄 arraysetops.pyi from typing import ( Literal as L, Any, TypeVar, overload, SupportsIndex, ) from numpy import ( generic, number, bool_, ushort, ubyte, uintc, uint, ulonglong, short, int8, byte, intc, int_, intp, longlong, half, single, double, longdouble, csingle, cdouble, clongdouble, timedelta64, datetime64, object_, str_, bytes_, void, ) from numpy._typing import ( ArrayLike, NDArray, _ArrayLike, _ArrayLikeBool_co, _ArrayLikeDT64_co, _ArrayLikeTD64_co, _ArrayLikeObject_co, _ArrayLikeNumber_co, ) _SCT = TypeVar("_SCT", bound=generic) _NumberType = TypeVar("_NumberType", bound=number[Any]) # Explicitly set all allowed values to prevent accidental castings to # abstract dtypes (their common super-type). # # Only relevant if two or more arguments are parametrized, (e.g. `setdiff1d`) # which could result in, for example, `int64` and `float64`producing a # `number[_64Bit]` array _SCTNoCast = TypeVar( "_SCTNoCast", bool_, ushort, ubyte, uintc, uint, ulonglong, short, byte, intc, int_, longlong, half, single, double, longdouble, csingle, cdouble, clongdouble, timedelta64, datetime64, object_, str_, bytes_, void, ) __all__: list[str] @overload def ediff1d( ary: _ArrayLikeBool_co, to_end: None \| ArrayLike = ..., to_begin: None \| ArrayLike = ..., ) -> NDArray[int8]: ... @overload def ediff1d( ary: _ArrayLike[_NumberType], to_end: None \| ArrayLike = ..., to_begin: None \| ArrayLike = ..., ) -> NDArray[_NumberType]: ... @overload def ediff1d( ary: _ArrayLikeNumber_co, to_end: None \| ArrayLike = ..., to_begin: None \| ArrayLike = ..., ) -> NDArray[Any]: ... @overload def ediff1d( ary: _ArrayLikeDT64_co \| _ArrayLikeTD64_co, to_end: None \| ArrayLike = ..., to_begin: None \| ArrayLike = ..., ) -> NDArray[timedelta64]: ... @overload def ediff1d( ary: _ArrayLikeObject_co, to_end: None \| ArrayLike = ..., to_begin: None \| ArrayLike = ..., ) -> NDArray[object_]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[False] = ..., return_inverse: L[False] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> NDArray[_SCT]: ... @overload def unique( ar: ArrayLike, return_index: L[False] = ..., return_inverse: L[False] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> NDArray[Any]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[True] = ..., return_inverse: L[False] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[True] = ..., return_inverse: L[False] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[False] = ..., return_inverse: L[True] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[False] = ..., return_inverse: L[True] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[False] = ..., return_inverse: L[False] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[False] = ..., return_inverse: L[False] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[True] = ..., return_inverse: L[True] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[True] = ..., return_inverse: L[True] = ..., return_counts: L[False] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[True] = ..., return_inverse: L[False] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[True] = ..., return_inverse: L[False] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[False] = ..., return_inverse: L[True] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[False] = ..., return_inverse: L[True] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: _ArrayLike[_SCT], return_index: L[True] = ..., return_inverse: L[True] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[_SCT], NDArray[intp], NDArray[intp], NDArray[intp]]: ... @overload def unique( ar: ArrayLike, return_index: L[True] = ..., return_inverse: L[True] = ..., return_counts: L[True] = ..., axis: None \| SupportsIndex = ..., , equal_nan: bool = ..., ) -> tuple[NDArray[Any], NDArray[intp], NDArray[intp], NDArray[intp]]: ... @overload def intersect1d( ar1: _ArrayLike[_SCTNoCast], ar2: _ArrayLike[_SCTNoCast], assume_unique: bool = ..., return_indices: L[False] = ..., ) -> NDArray[_SCTNoCast]: ... @overload def intersect1d( ar1: ArrayLike, ar2: ArrayLike, assume_unique: bool = ..., return_indices: L[False] = ..., ) -> NDArray[Any]: ... @overload def intersect1d( ar1: _ArrayLike[_SCTNoCast], ar2: _ArrayLike[_SCTNoCast], assume_unique: bool = ..., return_indices: L[True] = ..., ) -> tuple[NDArray[_SCTNoCast], NDArray[intp], NDArray[intp]]: ... @overload def intersect1d( ar1: ArrayLike, ar2: ArrayLike, assume_unique: bool = ..., return_indices: L[True] = ..., ) -> tuple[NDArray[Any], NDArray[intp], NDArray[intp]]: ... @overload def setxor1d( ar1: _ArrayLike[_SCTNoCast], ar2: _ArrayLike[_SCTNoCast], assume_unique: bool = ..., ) -> NDArray[_SCTNoCast]: ... @overload def setxor1d( ar1: ArrayLike, ar2: ArrayLike, assume_unique: bool = ..., ) -> NDArray[Any]: ... def in1d( ar1: ArrayLike, ar2: ArrayLike, assume_unique: bool = ..., invert: bool = ..., ) -> NDArray[bool_]: ... def isin( element: ArrayLike, test_elements: ArrayLike, assume_unique: bool = ..., invert: bool = ..., ) -> NDArray[bool_]: ... @overload def union1d( ar1: _ArrayLike[_SCTNoCast], ar2: _ArrayLike[_SCTNoCast], ) -> NDArray[_SCTNoCast]: ... @overload def union1d( ar1: ArrayLike, ar2: ArrayLike, ) -> NDArray[Any]: ... @overload def setdiff1d( ar1: _ArrayLike[_SCTNoCast], ar2: _ArrayLike[_SCTNoCast], assume_unique: bool = ..., ) -> NDArray[_SCTNoCast]: ... @overload def setdiff1d( ar1: ArrayLike, ar2: ArrayLike, assume_unique: bool = ..., ) -> NDArray[Any]: ...	8.14 KB	2026-01-20 12:58
📄 arrayterator.py """ A buffered iterator for big arrays. This module solves the problem of iterating over a big file-based array without having to read it into memory. The `Arrayterator` class wraps an array object, and when iterated it will return sub-arrays with at most a user-specified number of elements. """ from operator import mul from functools import reduce __all__ = ['Arrayterator'] class Arrayterator: """ Buffered iterator for big arrays. `Arrayterator` creates a buffered iterator for reading big arrays in small contiguous blocks. The class is useful for objects stored in the file system. It allows iteration over the object without reading everything in memory; instead, small blocks are read and iterated over. `Arrayterator` can be used with any object that supports multidimensional slices. This includes NumPy arrays, but also variables from Scientific.IO.NetCDF or pynetcdf for example. Parameters ---------- var : array_like The object to iterate over. buf_size : int, optional The buffer size. If `buf_size` is supplied, the maximum amount of data that will be read into memory is `buf_size` elements. Default is None, which will read as many element as possible into memory. Attributes ---------- var buf_size start stop step shape flat See Also -------- ndenumerate : Multidimensional array iterator. flatiter : Flat array iterator. memmap : Create a memory-map to an array stored in a binary file on disk. Notes ----- The algorithm works by first finding a "running dimension", along which the blocks will be extracted. Given an array of dimensions ``(d1, d2, ..., dn)``, e.g. if `buf_size` is smaller than ``d1``, the first dimension will be used. If, on the other hand, ``d1 < buf_size < d1d2`` the second dimension will be used, and so on. Blocks are extracted along this dimension, and when the last block is returned the process continues from the next dimension, until all elements have been read. Examples -------- >>> a = np.arange(3 4 * 5 * 6).reshape(3, 4, 5, 6) >>> a_itor = np.lib.Arrayterator(a, 2) >>> a_itor.shape (3, 4, 5, 6) Now we can iterate over ``a_itor``, and it will return arrays of size two. Since `buf_size` was smaller than any dimension, the first dimension will be iterated over first: >>> for subarr in a_itor: ... if not subarr.all(): ... print(subarr, subarr.shape) # doctest: +SKIP >>> # [[[[0 1]]]] (1, 1, 1, 2) """ def __init__(self, var, buf_size=None): self.var = var self.buf_size = buf_size self.start = [0 for dim in var.shape] self.stop = [dim for dim in var.shape] self.step = [1 for dim in var.shape] def __getattr__(self, attr): return getattr(self.var, attr) def __getitem__(self, index): """ Return a new arrayterator. """ # Fix index, handling ellipsis and incomplete slices. if not isinstance(index, tuple): index = (index,) fixed = [] length, dims = len(index), self.ndim for slice_ in index: if slice_ is Ellipsis: fixed.extend([slice(None)] * (dims-length+1)) length = len(fixed) elif isinstance(slice_, int): fixed.append(slice(slice_, slice_+1, 1)) else: fixed.append(slice_) index = tuple(fixed) if len(index) < dims: index += (slice(None),) * (dims-len(index)) # Return a new arrayterator object. out = self.__class__(self.var, self.buf_size) for i, (start, stop, step, slice_) in enumerate( zip(self.start, self.stop, self.step, index)): out.start[i] = start + (slice_.start or 0) out.step[i] = step * (slice_.step or 1) out.stop[i] = start + (slice_.stop or stop-start) out.stop[i] = min(stop, out.stop[i]) return out def __array__(self): """ Return corresponding data. """ slice_ = tuple(slice(t) for t in zip( self.start, self.stop, self.step)) return self.var[slice_] @property def flat(self): """ A 1-D flat iterator for Arrayterator objects. This iterator returns elements of the array to be iterated over in `Arrayterator` one by one. It is similar to `flatiter`. See Also -------- Arrayterator flatiter Examples -------- >>> a = np.arange(3 4 * 5 * 6).reshape(3, 4, 5, 6) >>> a_itor = np.lib.Arrayterator(a, 2) >>> for subarr in a_itor.flat: ... if not subarr: ... print(subarr, type(subarr)) ... 0 <class 'numpy.int64'> """ for block in self: yield from block.flat @property def shape(self): """ The shape of the array to be iterated over. For an example, see `Arrayterator`. """ return tuple(((stop-start-1)//step+1) for start, stop, step in zip(self.start, self.stop, self.step)) def __iter__(self): # Skip arrays with degenerate dimensions if [dim for dim in self.shape if dim <= 0]: return start = self.start[:] stop = self.stop[:] step = self.step[:] ndims = self.var.ndim while True: count = self.buf_size or reduce(mul, self.shape) # iterate over each dimension, looking for the # running dimension (ie, the dimension along which # the blocks will be built from) rundim = 0 for i in range(ndims-1, -1, -1): # if count is zero we ran out of elements to read # along higher dimensions, so we read only a single position if count == 0: stop[i] = start[i]+1 elif count <= self.shape[i]: # limit along this dimension stop[i] = start[i] + countstep[i] rundim = i else: # read everything along this dimension stop[i] = self.stop[i] stop[i] = min(self.stop[i], stop[i]) count = count//self.shape[i] # yield a block slice_ = tuple(slice(t) for t in zip(start, stop, step)) yield self.var[slice_] # Update start position, taking care of overflow to # other dimensions start[rundim] = stop[rundim] # start where we stopped for i in range(ndims-1, 0, -1): if start[i] >= self.stop[i]: start[i] = self.start[i] start[i-1] += self.step[i-1] if start[0] >= self.stop[0]: return	6.9 KB	2026-01-20 12:58
📄 arrayterator.pyi from collections.abc import Generator from typing import ( Any, TypeVar, Union, overload, ) from numpy import ndarray, dtype, generic from numpy._typing import DTypeLike # TODO: Set a shape bound once we've got proper shape support _Shape = TypeVar("_Shape", bound=Any) _DType = TypeVar("_DType", bound=dtype[Any]) _ScalarType = TypeVar("_ScalarType", bound=generic) _Index = Union[ Union[ellipsis, int, slice], tuple[Union[ellipsis, int, slice], ...], ] __all__: list[str] # NOTE: In reality `Arrayterator` does not actually inherit from `ndarray`, # but its ``__getattr__` method does wrap around the former and thus has # access to all its methods class Arrayterator(ndarray[_Shape, _DType]): var: ndarray[_Shape, _DType] # type: ignore[assignment] buf_size: None \| int start: list[int] stop: list[int] step: list[int] @property # type: ignore[misc] def shape(self) -> tuple[int, ...]: ... @property def flat( # type: ignore[override] self: ndarray[Any, dtype[_ScalarType]] ) -> Generator[_ScalarType, None, None]: ... def __init__( self, var: ndarray[_Shape, _DType], buf_size: None \| int = ... ) -> None: ... @overload def __array__(self, dtype: None = ...) -> ndarray[Any, _DType]: ... @overload def __array__(self, dtype: DTypeLike) -> ndarray[Any, dtype[Any]]: ... def __getitem__(self, index: _Index) -> Arrayterator[Any, _DType]: ... def __iter__(self) -> Generator[ndarray[Any, _DType], None, None]: ...	1.5 KB	2026-01-20 12:58
📄 format.py """ Binary serialization NPY format ========== A simple format for saving numpy arrays to disk with the full information about them. The ``.npy`` format is the standard binary file format in NumPy for persisting a single arbitrary NumPy array on disk. The format stores all of the shape and dtype information necessary to reconstruct the array correctly even on another machine with a different architecture. The format is designed to be as simple as possible while achieving its limited goals. The ``.npz`` format is the standard format for persisting multiple NumPy arrays on disk. A ``.npz`` file is a zip file containing multiple ``.npy`` files, one for each array. Capabilities ------------ - Can represent all NumPy arrays including nested record arrays and object arrays. - Represents the data in its native binary form. - Supports Fortran-contiguous arrays directly. - Stores all of the necessary information to reconstruct the array including shape and dtype on a machine of a different architecture. Both little-endian and big-endian arrays are supported, and a file with little-endian numbers will yield a little-endian array on any machine reading the file. The types are described in terms of their actual sizes. For example, if a machine with a 64-bit C "long int" writes out an array with "long ints", a reading machine with 32-bit C "long ints" will yield an array with 64-bit integers. - Is straightforward to reverse engineer. Datasets often live longer than the programs that created them. A competent developer should be able to create a solution in their preferred programming language to read most ``.npy`` files that they have been given without much documentation. - Allows memory-mapping of the data. See `open_memmap`. - Can be read from a filelike stream object instead of an actual file. - Stores object arrays, i.e. arrays containing elements that are arbitrary Python objects. Files with object arrays are not to be mmapable, but can be read and written to disk. Limitations ----------- - Arbitrary subclasses of numpy.ndarray are not completely preserved. Subclasses will be accepted for writing, but only the array data will be written out. A regular numpy.ndarray object will be created upon reading the file. .. warning:: Due to limitations in the interpretation of structured dtypes, dtypes with fields with empty names will have the names replaced by 'f0', 'f1', etc. Such arrays will not round-trip through the format entirely accurately. The data is intact; only the field names will differ. We are working on a fix for this. This fix will not require a change in the file format. The arrays with such structures can still be saved and restored, and the correct dtype may be restored by using the ``loadedarray.view(correct_dtype)`` method. File extensions --------------- We recommend using the ``.npy`` and ``.npz`` extensions for files saved in this format. This is by no means a requirement; applications may wish to use these file formats but use an extension specific to the application. In the absence of an obvious alternative, however, we suggest using ``.npy`` and ``.npz``. Version numbering ----------------- The version numbering of these formats is independent of NumPy version numbering. If the format is upgraded, the code in `numpy.io` will still be able to read and write Version 1.0 files. Format Version 1.0 ------------------ The first 6 bytes are a magic string: exactly ``\\x93NUMPY``. The next 1 byte is an unsigned byte: the major version number of the file format, e.g. ``\\x01``. The next 1 byte is an unsigned byte: the minor version number of the file format, e.g. ``\\x00``. Note: the version of the file format is not tied to the version of the numpy package. The next 2 bytes form a little-endian unsigned short int: the length of the header data HEADER_LEN. The next HEADER_LEN bytes form the header data describing the array's format. It is an ASCII string which contains a Python literal expression of a dictionary. It is terminated by a newline (``\\n``) and padded with spaces (``\\x20``) to make the total of ``len(magic string) + 2 + len(length) + HEADER_LEN`` be evenly divisible by 64 for alignment purposes. The dictionary contains three keys: "descr" : dtype.descr An object that can be passed as an argument to the `numpy.dtype` constructor to create the array's dtype. "fortran_order" : bool Whether the array data is Fortran-contiguous or not. Since Fortran-contiguous arrays are a common form of non-C-contiguity, we allow them to be written directly to disk for efficiency. "shape" : tuple of int The shape of the array. For repeatability and readability, the dictionary keys are sorted in alphabetic order. This is for convenience only. A writer SHOULD implement this if possible. A reader MUST NOT depend on this. Following the header comes the array data. If the dtype contains Python objects (i.e. ``dtype.hasobject is True``), then the data is a Python pickle of the array. Otherwise the data is the contiguous (either C- or Fortran-, depending on ``fortran_order``) bytes of the array. Consumers can figure out the number of bytes by multiplying the number of elements given by the shape (noting that ``shape=()`` means there is 1 element) by ``dtype.itemsize``. Format Version 2.0 ------------------ The version 1.0 format only allowed the array header to have a total size of 65535 bytes. This can be exceeded by structured arrays with a large number of columns. The version 2.0 format extends the header size to 4 GiB. `numpy.save` will automatically save in 2.0 format if the data requires it, else it will always use the more compatible 1.0 format. The description of the fourth element of the header therefore has become: "The next 4 bytes form a little-endian unsigned int: the length of the header data HEADER_LEN." Format Version 3.0 ------------------ This version replaces the ASCII string (which in practice was latin1) with a utf8-encoded string, so supports structured types with any unicode field names. Notes ----- The ``.npy`` format, including motivation for creating it and a comparison of alternatives, is described in the :doc:`"npy-format" NEP <neps:nep-0001-npy-format>`, however details have evolved with time and this document is more current. """ import numpy import warnings from numpy.lib.utils import safe_eval, drop_metadata from numpy.compat import ( isfileobj, os_fspath, pickle ) __all__ = [] EXPECTED_KEYS = {'descr', 'fortran_order', 'shape'} MAGIC_PREFIX = b'\x93NUMPY' MAGIC_LEN = len(MAGIC_PREFIX) + 2 ARRAY_ALIGN = 64 # plausible values are powers of 2 between 16 and 4096 BUFFER_SIZE = 2*18 # size of buffer for reading npz files in bytes # allow growth within the address space of a 64 bit machine along one axis GROWTH_AXIS_MAX_DIGITS = 21 # = len(str(82*64-1)) hypothetical int1 dtype # difference between version 1.0 and 2.0 is a 4 byte (I) header length # instead of 2 bytes (H) allowing storage of large structured arrays _header_size_info = { (1, 0): ('<H', 'latin1'), (2, 0): ('<I', 'latin1'), (3, 0): ('<I', 'utf8'), } # Python's literal_eval is not actually safe for large inputs, since parsing # may become slow or even cause interpreter crashes. # This is an arbitrary, low limit which should make it safe in practice. _MAX_HEADER_SIZE = 10000 def _check_version(version): if version not in [(1, 0), (2, 0), (3, 0), None]: msg = "we only support format version (1,0), (2,0), and (3,0), not %s" raise ValueError(msg % (version,)) def magic(major, minor): """ Return the magic string for the given file format version. Parameters ---------- major : int in [0, 255] minor : int in [0, 255] Returns ------- magic : str Raises ------ ValueError if the version cannot be formatted. """ if major < 0 or major > 255: raise ValueError("major version must be 0 <= major < 256") if minor < 0 or minor > 255: raise ValueError("minor version must be 0 <= minor < 256") return MAGIC_PREFIX + bytes([major, minor]) def read_magic(fp): """ Read the magic string to get the version of the file format. Parameters ---------- fp : filelike object Returns ------- major : int minor : int """ magic_str = _read_bytes(fp, MAGIC_LEN, "magic string") if magic_str[:-2] != MAGIC_PREFIX: msg = "the magic string is not correct; expected %r, got %r" raise ValueError(msg % (MAGIC_PREFIX, magic_str[:-2])) major, minor = magic_str[-2:] return major, minor def dtype_to_descr(dtype): """ Get a serializable descriptor from the dtype. The .descr attribute of a dtype object cannot be round-tripped through the dtype() constructor. Simple types, like dtype('float32'), have a descr which looks like a record array with one field with '' as a name. The dtype() constructor interprets this as a request to give a default name. Instead, we construct descriptor that can be passed to dtype(). Parameters ---------- dtype : dtype The dtype of the array that will be written to disk. Returns ------- descr : object An object that can be passed to `numpy.dtype()` in order to replicate the input dtype. """ # NOTE: that drop_metadata may not return the right dtype e.g. for user # dtypes. In that case our code below would fail the same, though. new_dtype = drop_metadata(dtype) if new_dtype is not dtype: warnings.warn("metadata on a dtype is not saved to an npy/npz. " "Use another format (such as pickle) to store it.", UserWarning, stacklevel=2) if dtype.names is not None: # This is a record array. The .descr is fine. XXX: parts of the # record array with an empty name, like padding bytes, still get # fiddled with. This needs to be fixed in the C implementation of # dtype(). return dtype.descr else: return dtype.str def descr_to_dtype(descr): """ Returns a dtype based off the given description. This is essentially the reverse of `dtype_to_descr()`. It will remove the valueless padding fields created by, i.e. simple fields like dtype('float32'), and then convert the description to its corresponding dtype. Parameters ---------- descr : object The object retrieved by dtype.descr. Can be passed to `numpy.dtype()` in order to replicate the input dtype. Returns ------- dtype : dtype The dtype constructed by the description. """ if isinstance(descr, str): # No padding removal needed return numpy.dtype(descr) elif isinstance(descr, tuple): # subtype, will always have a shape descr[1] dt = descr_to_dtype(descr[0]) return numpy.dtype((dt, descr[1])) titles = [] names = [] formats = [] offsets = [] offset = 0 for field in descr: if len(field) == 2: name, descr_str = field dt = descr_to_dtype(descr_str) else: name, descr_str, shape = field dt = numpy.dtype((descr_to_dtype(descr_str), shape)) # Ignore padding bytes, which will be void bytes with '' as name # Once support for blank names is removed, only "if name == ''" needed) is_pad = (name == '' and dt.type is numpy.void and dt.names is None) if not is_pad: title, name = name if isinstance(name, tuple) else (None, name) titles.append(title) names.append(name) formats.append(dt) offsets.append(offset) offset += dt.itemsize return numpy.dtype({'names': names, 'formats': formats, 'titles': titles, 'offsets': offsets, 'itemsize': offset}) def header_data_from_array_1_0(array): """ Get the dictionary of header metadata from a numpy.ndarray. Parameters ---------- array : numpy.ndarray Returns ------- d : dict This has the appropriate entries for writing its string representation to the header of the file. """ d = {'shape': array.shape} if array.flags.c_contiguous: d['fortran_order'] = False elif array.flags.f_contiguous: d['fortran_order'] = True else: # Totally non-contiguous data. We will have to make it C-contiguous # before writing. Note that we need to test for C_CONTIGUOUS first # because a 1-D array is both C_CONTIGUOUS and F_CONTIGUOUS. d['fortran_order'] = False d['descr'] = dtype_to_descr(array.dtype) return d def _wrap_header(header, version): """ Takes a stringified header, and attaches the prefix and padding to it """ import struct assert version is not None fmt, encoding = _header_size_info[version] header = header.encode(encoding) hlen = len(header) + 1 padlen = ARRAY_ALIGN - ((MAGIC_LEN + struct.calcsize(fmt) + hlen) % ARRAY_ALIGN) try: header_prefix = magic(version) + struct.pack(fmt, hlen + padlen) except struct.error: msg = "Header length {} too big for version={}".format(hlen, version) raise ValueError(msg) from None # Pad the header with spaces and a final newline such that the magic # string, the header-length short and the header are aligned on a # ARRAY_ALIGN byte boundary. This supports memory mapping of dtypes # aligned up to ARRAY_ALIGN on systems like Linux where mmap() # offset must be page-aligned (i.e. the beginning of the file). return header_prefix + header + b' 'padlen + b'\n' def _wrap_header_guess_version(header): """ Like `_wrap_header`, but chooses an appropriate version given the contents """ try: return _wrap_header(header, (1, 0)) except ValueError: pass try: ret = _wrap_header(header, (2, 0)) except UnicodeEncodeError: pass else: warnings.warn("Stored array in format 2.0. It can only be" "read by NumPy >= 1.9", UserWarning, stacklevel=2) return ret header = _wrap_header(header, (3, 0)) warnings.warn("Stored array in format 3.0. It can only be " "read by NumPy >= 1.17", UserWarning, stacklevel=2) return header def _write_array_header(fp, d, version=None): """ Write the header for an array and returns the version used Parameters ---------- fp : filelike object d : dict This has the appropriate entries for writing its string representation to the header of the file. version : tuple or None None means use oldest that works. Providing an explicit version will raise a ValueError if the format does not allow saving this data. Default: None """ header = ["{"] for key, value in sorted(d.items()): # Need to use repr here, since we eval these when reading header.append("'%s': %s, " % (key, repr(value))) header.append("}") header = "".join(header) # Add some spare space so that the array header can be modified in-place # when changing the array size, e.g. when growing it by appending data at # the end. shape = d['shape'] header += " " ((GROWTH_AXIS_MAX_DIGITS - len(repr( shape[-1 if d['fortran_order'] else 0] ))) if len(shape) > 0 else 0) if version is None: header = _wrap_header_guess_version(header) else: header = _wrap_header(header, version) fp.write(header) def write_array_header_1_0(fp, d): """ Write the header for an array using the 1.0 format. Parameters ---------- fp : filelike object d : dict This has the appropriate entries for writing its string representation to the header of the file. """ _write_array_header(fp, d, (1, 0)) def write_array_header_2_0(fp, d): """ Write the header for an array using the 2.0 format. The 2.0 format allows storing very large structured arrays. .. versionadded:: 1.9.0 Parameters ---------- fp : filelike object d : dict This has the appropriate entries for writing its string representation to the header of the file. """ _write_array_header(fp, d, (2, 0)) def read_array_header_1_0(fp, max_header_size=_MAX_HEADER_SIZE): """ Read an array header from a filelike object using the 1.0 file format version. This will leave the file object located just after the header. Parameters ---------- fp : filelike object A file object or something with a `.read()` method like a file. Returns ------- shape : tuple of int The shape of the array. fortran_order : bool The array data will be written out directly if it is either C-contiguous or Fortran-contiguous. Otherwise, it will be made contiguous before writing it out. dtype : dtype The dtype of the file's data. max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. Raises ------ ValueError If the data is invalid. """ return _read_array_header( fp, version=(1, 0), max_header_size=max_header_size) def read_array_header_2_0(fp, max_header_size=_MAX_HEADER_SIZE): """ Read an array header from a filelike object using the 2.0 file format version. This will leave the file object located just after the header. .. versionadded:: 1.9.0 Parameters ---------- fp : filelike object A file object or something with a `.read()` method like a file. max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. Returns ------- shape : tuple of int The shape of the array. fortran_order : bool The array data will be written out directly if it is either C-contiguous or Fortran-contiguous. Otherwise, it will be made contiguous before writing it out. dtype : dtype The dtype of the file's data. Raises ------ ValueError If the data is invalid. """ return _read_array_header( fp, version=(2, 0), max_header_size=max_header_size) def _filter_header(s): """Clean up 'L' in npz header ints. Cleans up the 'L' in strings representing integers. Needed to allow npz headers produced in Python2 to be read in Python3. Parameters ---------- s : string Npy file header. Returns ------- header : str Cleaned up header. """ import tokenize from io import StringIO tokens = [] last_token_was_number = False for token in tokenize.generate_tokens(StringIO(s).readline): token_type = token[0] token_string = token[1] if (last_token_was_number and token_type == tokenize.NAME and token_string == "L"): continue else: tokens.append(token) last_token_was_number = (token_type == tokenize.NUMBER) return tokenize.untokenize(tokens) def _read_array_header(fp, version, max_header_size=_MAX_HEADER_SIZE): """ see read_array_header_1_0 """ # Read an unsigned, little-endian short int which has the length of the # header. import struct hinfo = _header_size_info.get(version) if hinfo is None: raise ValueError("Invalid version {!r}".format(version)) hlength_type, encoding = hinfo hlength_str = _read_bytes(fp, struct.calcsize(hlength_type), "array header length") header_length = struct.unpack(hlength_type, hlength_str)[0] header = _read_bytes(fp, header_length, "array header") header = header.decode(encoding) if len(header) > max_header_size: raise ValueError( f"Header info length ({len(header)}) is large and may not be safe " "to load securely.\n" "To allow loading, adjust `max_header_size` or fully trust " "the `.npy` file using `allow_pickle=True`.\n" "For safety against large resource use or crashes, sandboxing " "may be necessary.") # The header is a pretty-printed string representation of a literal # Python dictionary with trailing newlines padded to a ARRAY_ALIGN byte # boundary. The keys are strings. # "shape" : tuple of int # "fortran_order" : bool # "descr" : dtype.descr # Versions (2, 0) and (1, 0) could have been created by a Python 2 # implementation before header filtering was implemented. # # For performance reasons, we try without _filter_header first though try: d = safe_eval(header) except SyntaxError as e: if version <= (2, 0): header = _filter_header(header) try: d = safe_eval(header) except SyntaxError as e2: msg = "Cannot parse header: {!r}" raise ValueError(msg.format(header)) from e2 else: warnings.warn( "Reading `.npy` or `.npz` file required additional " "header parsing as it was created on Python 2. Save the " "file again to speed up loading and avoid this warning.", UserWarning, stacklevel=4) else: msg = "Cannot parse header: {!r}" raise ValueError(msg.format(header)) from e if not isinstance(d, dict): msg = "Header is not a dictionary: {!r}" raise ValueError(msg.format(d)) if EXPECTED_KEYS != d.keys(): keys = sorted(d.keys()) msg = "Header does not contain the correct keys: {!r}" raise ValueError(msg.format(keys)) # Sanity-check the values. if (not isinstance(d['shape'], tuple) or not all(isinstance(x, int) for x in d['shape'])): msg = "shape is not valid: {!r}" raise ValueError(msg.format(d['shape'])) if not isinstance(d['fortran_order'], bool): msg = "fortran_order is not a valid bool: {!r}" raise ValueError(msg.format(d['fortran_order'])) try: dtype = descr_to_dtype(d['descr']) except TypeError as e: msg = "descr is not a valid dtype descriptor: {!r}" raise ValueError(msg.format(d['descr'])) from e return d['shape'], d['fortran_order'], dtype def write_array(fp, array, version=None, allow_pickle=True, pickle_kwargs=None): """ Write an array to an NPY file, including a header. If the array is neither C-contiguous nor Fortran-contiguous AND the file_like object is not a real file object, this function will have to copy data in memory. Parameters ---------- fp : file_like object An open, writable file object, or similar object with a ``.write()`` method. array : ndarray The array to write to disk. version : (int, int) or None, optional The version number of the format. None means use the oldest supported version that is able to store the data. Default: None allow_pickle : bool, optional Whether to allow writing pickled data. Default: True pickle_kwargs : dict, optional Additional keyword arguments to pass to pickle.dump, excluding 'protocol'. These are only useful when pickling objects in object arrays on Python 3 to Python 2 compatible format. Raises ------ ValueError If the array cannot be persisted. This includes the case of allow_pickle=False and array being an object array. Various other errors If the array contains Python objects as part of its dtype, the process of pickling them may raise various errors if the objects are not picklable. """ _check_version(version) _write_array_header(fp, header_data_from_array_1_0(array), version) if array.itemsize == 0: buffersize = 0 else: # Set buffer size to 16 MiB to hide the Python loop overhead. buffersize = max(16 * 1024 2 // array.itemsize, 1) if array.dtype.hasobject: # We contain Python objects so we cannot write out the data # directly. Instead, we will pickle it out if not allow_pickle: raise ValueError("Object arrays cannot be saved when " "allow_pickle=False") if pickle_kwargs is None: pickle_kwargs = {} pickle.dump(array, fp, protocol=3, pickle_kwargs) elif array.flags.f_contiguous and not array.flags.c_contiguous: if isfileobj(fp): array.T.tofile(fp) else: for chunk in numpy.nditer( array, flags=['external_loop', 'buffered', 'zerosize_ok'], buffersize=buffersize, order='F'): fp.write(chunk.tobytes('C')) else: if isfileobj(fp): array.tofile(fp) else: for chunk in numpy.nditer( array, flags=['external_loop', 'buffered', 'zerosize_ok'], buffersize=buffersize, order='C'): fp.write(chunk.tobytes('C')) def read_array(fp, allow_pickle=False, pickle_kwargs=None, , max_header_size=_MAX_HEADER_SIZE): """ Read an array from an NPY file. Parameters ---------- fp : file_like object If this is not a real file object, then this may take extra memory and time. allow_pickle : bool, optional Whether to allow writing pickled data. Default: False .. versionchanged:: 1.16.3 Made default False in response to CVE-2019-6446. pickle_kwargs : dict Additional keyword arguments to pass to pickle.load. These are only useful when loading object arrays saved on Python 2 when using Python 3. max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. This option is ignored when `allow_pickle` is passed. In that case the file is by definition trusted and the limit is unnecessary. Returns ------- array : ndarray The array from the data on disk. Raises ------ ValueError If the data is invalid, or allow_pickle=False and the file contains an object array. """ if allow_pickle: # Effectively ignore max_header_size, since `allow_pickle` indicates # that the input is fully trusted. max_header_size = 264 version = read_magic(fp) _check_version(version) shape, fortran_order, dtype = _read_array_header( fp, version, max_header_size=max_header_size) if len(shape) == 0: count = 1 else: count = numpy.multiply.reduce(shape, dtype=numpy.int64) # Now read the actual data. if dtype.hasobject: # The array contained Python objects. We need to unpickle the data. if not allow_pickle: raise ValueError("Object arrays cannot be loaded when " "allow_pickle=False") if pickle_kwargs is None: pickle_kwargs = {} try: array = pickle.load(fp, pickle_kwargs) except UnicodeError as err: # Friendlier error message raise UnicodeError("Unpickling a python object failed: %r\n" "You may need to pass the encoding= option " "to numpy.load" % (err,)) from err else: if isfileobj(fp): # We can use the fast fromfile() function. array = numpy.fromfile(fp, dtype=dtype, count=count) else: # This is not a real file. We have to read it the # memory-intensive way. # crc32 module fails on reads greater than 2 * 32 bytes, # breaking large reads from gzip streams. Chunk reads to # BUFFER_SIZE bytes to avoid issue and reduce memory overhead # of the read. In non-chunked case count < max_read_count, so # only one read is performed. # Use np.ndarray instead of np.empty since the latter does # not correctly instantiate zero-width string dtypes; see # https://github.com/numpy/numpy/pull/6430 array = numpy.ndarray(count, dtype=dtype) if dtype.itemsize > 0: # If dtype.itemsize == 0 then there's nothing more to read max_read_count = BUFFER_SIZE // min(BUFFER_SIZE, dtype.itemsize) for i in range(0, count, max_read_count): read_count = min(max_read_count, count - i) read_size = int(read_count * dtype.itemsize) data = _read_bytes(fp, read_size, "array data") array[i:i+read_count] = numpy.frombuffer(data, dtype=dtype, count=read_count) if fortran_order: array.shape = shape[::-1] array = array.transpose() else: array.shape = shape return array def open_memmap(filename, mode='r+', dtype=None, shape=None, fortran_order=False, version=None, , max_header_size=_MAX_HEADER_SIZE): """ Open a .npy file as a memory-mapped array. This may be used to read an existing file or create a new one. Parameters ---------- filename : str or path-like The name of the file on disk. This may not* be a file-like object. mode : str, optional The mode in which to open the file; the default is 'r+'. In addition to the standard file modes, 'c' is also accepted to mean "copy on write." See `memmap` for the available mode strings. dtype : data-type, optional The data type of the array if we are creating a new file in "write" mode, if not, `dtype` is ignored. The default value is None, which results in a data-type of `float64`. shape : tuple of int The shape of the array if we are creating a new file in "write" mode, in which case this parameter is required. Otherwise, this parameter is ignored and is thus optional. fortran_order : bool, optional Whether the array should be Fortran-contiguous (True) or C-contiguous (False, the default) if we are creating a new file in "write" mode. version : tuple of int (major, minor) or None If the mode is a "write" mode, then this is the version of the file format used to create the file. None means use the oldest supported version that is able to store the data. Default: None max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. Returns ------- marray : memmap The memory-mapped array. Raises ------ ValueError If the data or the mode is invalid. OSError If the file is not found or cannot be opened correctly. See Also -------- numpy.memmap """ if isfileobj(filename): raise ValueError("Filename must be a string or a path-like object." " Memmap cannot use existing file handles.") if 'w' in mode: # We are creating the file, not reading it. # Check if we ought to create the file. _check_version(version) # Ensure that the given dtype is an authentic dtype object rather # than just something that can be interpreted as a dtype object. dtype = numpy.dtype(dtype) if dtype.hasobject: msg = "Array can't be memory-mapped: Python objects in dtype." raise ValueError(msg) d = dict( descr=dtype_to_descr(dtype), fortran_order=fortran_order, shape=shape, ) # If we got here, then it should be safe to create the file. with open(os_fspath(filename), mode+'b') as fp: _write_array_header(fp, d, version) offset = fp.tell() else: # Read the header of the file first. with open(os_fspath(filename), 'rb') as fp: version = read_magic(fp) _check_version(version) shape, fortran_order, dtype = _read_array_header( fp, version, max_header_size=max_header_size) if dtype.hasobject: msg = "Array can't be memory-mapped: Python objects in dtype." raise ValueError(msg) offset = fp.tell() if fortran_order: order = 'F' else: order = 'C' # We need to change a write-only mode to a read-write mode since we've # already written data to the file. if mode == 'w+': mode = 'r+' marray = numpy.memmap(filename, dtype=dtype, shape=shape, order=order, mode=mode, offset=offset) return marray def _read_bytes(fp, size, error_template="ran out of data"): """ Read from file-like object until size bytes are read. Raises ValueError if not EOF is encountered before size bytes are read. Non-blocking objects only supported if they derive from io objects. Required as e.g. ZipExtFile in python 2.6 can return less data than requested. """ data = bytes() while True: # io files (default in python3) return None or raise on # would-block, python2 file will truncate, probably nothing can be # done about that. note that regular files can't be non-blocking try: r = fp.read(size - len(data)) data += r if len(r) == 0 or len(data) == size: break except BlockingIOError: pass if len(data) != size: msg = "EOF: reading %s, expected %d bytes got %d" raise ValueError(msg % (error_template, size, len(data))) else: return data	33.95 KB	2026-01-20 12:58
📄 format.pyi from typing import Any, Literal, Final __all__: list[str] EXPECTED_KEYS: Final[set[str]] MAGIC_PREFIX: Final[bytes] MAGIC_LEN: Literal[8] ARRAY_ALIGN: Literal[64] BUFFER_SIZE: Literal[262144] # 2**18 def magic(major, minor): ... def read_magic(fp): ... def dtype_to_descr(dtype): ... def descr_to_dtype(descr): ... def header_data_from_array_1_0(array): ... def write_array_header_1_0(fp, d): ... def write_array_header_2_0(fp, d): ... def read_array_header_1_0(fp): ... def read_array_header_2_0(fp): ... def write_array(fp, array, version=..., allow_pickle=..., pickle_kwargs=...): ... def read_array(fp, allow_pickle=..., pickle_kwargs=...): ... def open_memmap(filename, mode=..., dtype=..., shape=..., fortran_order=..., version=...): ...	748 B	2026-01-20 12:58
📄 function_base.py import collections.abc import functools import re import sys import warnings from .._utils import set_module import numpy as np import numpy.core.numeric as _nx from numpy.core import transpose from numpy.core.numeric import ( ones, zeros_like, arange, concatenate, array, asarray, asanyarray, empty, ndarray, take, dot, where, intp, integer, isscalar, absolute ) from numpy.core.umath import ( pi, add, arctan2, frompyfunc, cos, less_equal, sqrt, sin, mod, exp, not_equal, subtract ) from numpy.core.fromnumeric import ( ravel, nonzero, partition, mean, any, sum ) from numpy.core.numerictypes import typecodes from numpy.core import overrides from numpy.core.function_base import add_newdoc from numpy.lib.twodim_base import diag from numpy.core.multiarray import ( _place, add_docstring, bincount, normalize_axis_index, _monotonicity, interp as compiled_interp, interp_complex as compiled_interp_complex ) from numpy.core.umath import _add_newdoc_ufunc as add_newdoc_ufunc import builtins # needed in this module for compatibility from numpy.lib.histograms import histogram, histogramdd # noqa: F401 array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') __all__ = [ 'select', 'piecewise', 'trim_zeros', 'copy', 'iterable', 'percentile', 'diff', 'gradient', 'angle', 'unwrap', 'sort_complex', 'disp', 'flip', 'rot90', 'extract', 'place', 'vectorize', 'asarray_chkfinite', 'average', 'bincount', 'digitize', 'cov', 'corrcoef', 'msort', 'median', 'sinc', 'hamming', 'hanning', 'bartlett', 'blackman', 'kaiser', 'trapz', 'i0', 'add_newdoc', 'add_docstring', 'meshgrid', 'delete', 'insert', 'append', 'interp', 'add_newdoc_ufunc', 'quantile' ] # _QuantileMethods is a dictionary listing all the supported methods to # compute quantile/percentile. # # Below virtual_index refer to the index of the element where the percentile # would be found in the sorted sample. # When the sample contains exactly the percentile wanted, the virtual_index is # an integer to the index of this element. # When the percentile wanted is in between two elements, the virtual_index # is made of a integer part (a.k.a 'i' or 'left') and a fractional part # (a.k.a 'g' or 'gamma') # # Each method in _QuantileMethods has two properties # get_virtual_index : Callable # The function used to compute the virtual_index. # fix_gamma : Callable # A function used for discret methods to force the index to a specific value. _QuantileMethods = dict( # --- HYNDMAN and FAN METHODS # Discrete methods inverted_cdf=dict( get_virtual_index=lambda n, quantiles: _inverted_cdf(n, quantiles), fix_gamma=lambda gamma, _: gamma, # should never be called ), averaged_inverted_cdf=dict( get_virtual_index=lambda n, quantiles: (n * quantiles) - 1, fix_gamma=lambda gamma, _: _get_gamma_mask( shape=gamma.shape, default_value=1., conditioned_value=0.5, where=gamma == 0), ), closest_observation=dict( get_virtual_index=lambda n, quantiles: _closest_observation(n, quantiles), fix_gamma=lambda gamma, _: gamma, # should never be called ), # Continuous methods interpolated_inverted_cdf=dict( get_virtual_index=lambda n, quantiles: _compute_virtual_index(n, quantiles, 0, 1), fix_gamma=lambda gamma, _: gamma, ), hazen=dict( get_virtual_index=lambda n, quantiles: _compute_virtual_index(n, quantiles, 0.5, 0.5), fix_gamma=lambda gamma, _: gamma, ), weibull=dict( get_virtual_index=lambda n, quantiles: _compute_virtual_index(n, quantiles, 0, 0), fix_gamma=lambda gamma, _: gamma, ), # Default method. # To avoid some rounding issues, `(n-1) * quantiles` is preferred to # `_compute_virtual_index(n, quantiles, 1, 1)`. # They are mathematically equivalent. linear=dict( get_virtual_index=lambda n, quantiles: (n - 1) * quantiles, fix_gamma=lambda gamma, _: gamma, ), median_unbiased=dict( get_virtual_index=lambda n, quantiles: _compute_virtual_index(n, quantiles, 1 / 3.0, 1 / 3.0), fix_gamma=lambda gamma, _: gamma, ), normal_unbiased=dict( get_virtual_index=lambda n, quantiles: _compute_virtual_index(n, quantiles, 3 / 8.0, 3 / 8.0), fix_gamma=lambda gamma, _: gamma, ), # --- OTHER METHODS lower=dict( get_virtual_index=lambda n, quantiles: np.floor( (n - 1) * quantiles).astype(np.intp), fix_gamma=lambda gamma, _: gamma, # should never be called, index dtype is int ), higher=dict( get_virtual_index=lambda n, quantiles: np.ceil( (n - 1) * quantiles).astype(np.intp), fix_gamma=lambda gamma, _: gamma, # should never be called, index dtype is int ), midpoint=dict( get_virtual_index=lambda n, quantiles: 0.5 * ( np.floor((n - 1) * quantiles) + np.ceil((n - 1) * quantiles)), fix_gamma=lambda gamma, index: _get_gamma_mask( shape=gamma.shape, default_value=0.5, conditioned_value=0., where=index % 1 == 0), ), nearest=dict( get_virtual_index=lambda n, quantiles: np.around( (n - 1) * quantiles).astype(np.intp), fix_gamma=lambda gamma, _: gamma, # should never be called, index dtype is int )) def _rot90_dispatcher(m, k=None, axes=None): return (m,) @array_function_dispatch(_rot90_dispatcher) def rot90(m, k=1, axes=(0, 1)): """ Rotate an array by 90 degrees in the plane specified by axes. Rotation direction is from the first towards the second axis. This means for a 2D array with the default `k` and `axes`, the rotation will be counterclockwise. Parameters ---------- m : array_like Array of two or more dimensions. k : integer Number of times the array is rotated by 90 degrees. axes : (2,) array_like The array is rotated in the plane defined by the axes. Axes must be different. .. versionadded:: 1.12.0 Returns ------- y : ndarray A rotated view of `m`. See Also -------- flip : Reverse the order of elements in an array along the given axis. fliplr : Flip an array horizontally. flipud : Flip an array vertically. Notes ----- ``rot90(m, k=1, axes=(1,0))`` is the reverse of ``rot90(m, k=1, axes=(0,1))`` ``rot90(m, k=1, axes=(1,0))`` is equivalent to ``rot90(m, k=-1, axes=(0,1))`` Examples -------- >>> m = np.array([[1,2],[3,4]], int) >>> m array([[1, 2], [3, 4]]) >>> np.rot90(m) array([[2, 4], [1, 3]]) >>> np.rot90(m, 2) array([[4, 3], [2, 1]]) >>> m = np.arange(8).reshape((2,2,2)) >>> np.rot90(m, 1, (1,2)) array([[[1, 3], [0, 2]], [[5, 7], [4, 6]]]) """ axes = tuple(axes) if len(axes) != 2: raise ValueError("len(axes) must be 2.") m = asanyarray(m) if axes[0] == axes[1] or absolute(axes[0] - axes[1]) == m.ndim: raise ValueError("Axes must be different.") if (axes[0] >= m.ndim or axes[0] < -m.ndim or axes[1] >= m.ndim or axes[1] < -m.ndim): raise ValueError("Axes={} out of range for array of ndim={}." .format(axes, m.ndim)) k %= 4 if k == 0: return m[:] if k == 2: return flip(flip(m, axes[0]), axes[1]) axes_list = arange(0, m.ndim) (axes_list[axes[0]], axes_list[axes[1]]) = (axes_list[axes[1]], axes_list[axes[0]]) if k == 1: return transpose(flip(m, axes[1]), axes_list) else: # k == 3 return flip(transpose(m, axes_list), axes[1]) def _flip_dispatcher(m, axis=None): return (m,) @array_function_dispatch(_flip_dispatcher) def flip(m, axis=None): """ Reverse the order of elements in an array along the given axis. The shape of the array is preserved, but the elements are reordered. .. versionadded:: 1.12.0 Parameters ---------- m : array_like Input array. axis : None or int or tuple of ints, optional Axis or axes along which to flip over. The default, axis=None, will flip over all of the axes of the input array. If axis is negative it counts from the last to the first axis. If axis is a tuple of ints, flipping is performed on all of the axes specified in the tuple. .. versionchanged:: 1.15.0 None and tuples of axes are supported Returns ------- out : array_like A view of `m` with the entries of axis reversed. Since a view is returned, this operation is done in constant time. See Also -------- flipud : Flip an array vertically (axis=0). fliplr : Flip an array horizontally (axis=1). Notes ----- flip(m, 0) is equivalent to flipud(m). flip(m, 1) is equivalent to fliplr(m). flip(m, n) corresponds to ``m[...,::-1,...]`` with ``::-1`` at position n. flip(m) corresponds to ``m[::-1,::-1,...,::-1]`` with ``::-1`` at all positions. flip(m, (0, 1)) corresponds to ``m[::-1,::-1,...]`` with ``::-1`` at position 0 and position 1. Examples -------- >>> A = np.arange(8).reshape((2,2,2)) >>> A array([[[0, 1], [2, 3]], [[4, 5], [6, 7]]]) >>> np.flip(A, 0) array([[[4, 5], [6, 7]], [[0, 1], [2, 3]]]) >>> np.flip(A, 1) array([[[2, 3], [0, 1]], [[6, 7], [4, 5]]]) >>> np.flip(A) array([[[7, 6], [5, 4]], [[3, 2], [1, 0]]]) >>> np.flip(A, (0, 2)) array([[[5, 4], [7, 6]], [[1, 0], [3, 2]]]) >>> A = np.random.randn(3,4,5) >>> np.all(np.flip(A,2) == A[:,:,::-1,...]) True """ if not hasattr(m, 'ndim'): m = asarray(m) if axis is None: indexer = (np.s_[::-1],) * m.ndim else: axis = _nx.normalize_axis_tuple(axis, m.ndim) indexer = [np.s_[:]] * m.ndim for ax in axis: indexer[ax] = np.s_[::-1] indexer = tuple(indexer) return m[indexer] @set_module('numpy') def iterable(y): """ Check whether or not an object can be iterated over. Parameters ---------- y : object Input object. Returns ------- b : bool Return ``True`` if the object has an iterator method or is a sequence and ``False`` otherwise. Examples -------- >>> np.iterable([1, 2, 3]) True >>> np.iterable(2) False Notes ----- In most cases, the results of ``np.iterable(obj)`` are consistent with ``isinstance(obj, collections.abc.Iterable)``. One notable exception is the treatment of 0-dimensional arrays:: >>> from collections.abc import Iterable >>> a = np.array(1.0) # 0-dimensional numpy array >>> isinstance(a, Iterable) True >>> np.iterable(a) False """ try: iter(y) except TypeError: return False return True def _average_dispatcher(a, axis=None, weights=None, returned=None, , keepdims=None): return (a, weights) @array_function_dispatch(_average_dispatcher) def average(a, axis=None, weights=None, returned=False, , keepdims=np._NoValue): """ Compute the weighted average along the specified axis. Parameters ---------- a : array_like Array containing data to be averaged. If `a` is not an array, a conversion is attempted. axis : None or int or tuple of ints, optional Axis or axes along which to average `a`. The default, axis=None, will average over all of the elements of the input array. If axis is negative it counts from the last to the first axis. .. versionadded:: 1.7.0 If axis is a tuple of ints, averaging is performed on all of the axes specified in the tuple instead of a single axis or all the axes as before. weights : array_like, optional An array of weights associated with the values in `a`. Each value in `a` contributes to the average according to its associated weight. The weights array can either be 1-D (in which case its length must be the size of `a` along the given axis) or of the same shape as `a`. If `weights=None`, then all data in `a` are assumed to have a weight equal to one. The 1-D calculation is:: avg = sum(a * weights) / sum(weights) The only constraint on `weights` is that `sum(weights)` must not be 0. returned : bool, optional Default is `False`. If `True`, the tuple (`average`, `sum_of_weights`) is returned, otherwise only the average is returned. If `weights=None`, `sum_of_weights` is equivalent to the number of elements over which the average is taken. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. Note: `keepdims` will not work with instances of `numpy.matrix` or other classes whose methods do not support `keepdims`. .. versionadded:: 1.23.0 Returns ------- retval, [sum_of_weights] : array_type or double Return the average along the specified axis. When `returned` is `True`, return a tuple with the average as the first element and the sum of the weights as the second element. `sum_of_weights` is of the same type as `retval`. The result dtype follows a genereal pattern. If `weights` is None, the result dtype will be that of `a` , or ``float64`` if `a` is integral. Otherwise, if `weights` is not None and `a` is non- integral, the result type will be the type of lowest precision capable of representing values of both `a` and `weights`. If `a` happens to be integral, the previous rules still applies but the result dtype will at least be ``float64``. Raises ------ ZeroDivisionError When all weights along axis are zero. See `numpy.ma.average` for a version robust to this type of error. TypeError When the length of 1D `weights` is not the same as the shape of `a` along axis. See Also -------- mean ma.average : average for masked arrays -- useful if your data contains "missing" values numpy.result_type : Returns the type that results from applying the numpy type promotion rules to the arguments. Examples -------- >>> data = np.arange(1, 5) >>> data array([1, 2, 3, 4]) >>> np.average(data) 2.5 >>> np.average(np.arange(1, 11), weights=np.arange(10, 0, -1)) 4.0 >>> data = np.arange(6).reshape((3, 2)) >>> data array([[0, 1], [2, 3], [4, 5]]) >>> np.average(data, axis=1, weights=[1./4, 3./4]) array([0.75, 2.75, 4.75]) >>> np.average(data, weights=[1./4, 3./4]) Traceback (most recent call last): ... TypeError: Axis must be specified when shapes of a and weights differ. >>> a = np.ones(5, dtype=np.float128) >>> w = np.ones(5, dtype=np.complex64) >>> avg = np.average(a, weights=w) >>> print(avg.dtype) complex256 With ``keepdims=True``, the following result has shape (3, 1). >>> np.average(data, axis=1, keepdims=True) array([[0.5], [2.5], [4.5]]) """ a = np.asanyarray(a) if keepdims is np._NoValue: # Don't pass on the keepdims argument if one wasn't given. keepdims_kw = {} else: keepdims_kw = {'keepdims': keepdims} if weights is None: avg = a.mean(axis, *keepdims_kw) avg_as_array = np.asanyarray(avg) scl = avg_as_array.dtype.type(a.size/avg_as_array.size) else: wgt = np.asanyarray(weights) if issubclass(a.dtype.type, (np.integer, np.bool_)): result_dtype = np.result_type(a.dtype, wgt.dtype, 'f8') else: result_dtype = np.result_type(a.dtype, wgt.dtype) # Sanity checks if a.shape != wgt.shape: if axis is None: raise TypeError( "Axis must be specified when shapes of a and weights " "differ.") if wgt.ndim != 1: raise TypeError( "1D weights expected when shapes of a and weights differ.") if wgt.shape[0] != a.shape[axis]: raise ValueError( "Length of weights not compatible with specified axis.") # setup wgt to broadcast along axis wgt = np.broadcast_to(wgt, (a.ndim-1)(1,) + wgt.shape) wgt = wgt.swapaxes(-1, axis) scl = wgt.sum(axis=axis, dtype=result_dtype, keepdims_kw) if np.any(scl == 0.0): raise ZeroDivisionError( "Weights sum to zero, can't be normalized") avg = avg_as_array = np.multiply(a, wgt, dtype=result_dtype).sum(axis, keepdims_kw) / scl if returned: if scl.shape != avg_as_array.shape: scl = np.broadcast_to(scl, avg_as_array.shape).copy() return avg, scl else: return avg @set_module('numpy') def asarray_chkfinite(a, dtype=None, order=None): """Convert the input to an array, checking for NaNs or Infs. Parameters ---------- a : array_like Input data, in any form that can be converted to an array. This includes lists, lists of tuples, tuples, tuples of tuples, tuples of lists and ndarrays. Success requires no NaNs or Infs. dtype : data-type, optional By default, the data-type is inferred from the input data. order : {'C', 'F', 'A', 'K'}, optional Memory layout. 'A' and 'K' depend on the order of input array a. 'C' row-major (C-style), 'F' column-major (Fortran-style) memory representation. 'A' (any) means 'F' if `a` is Fortran contiguous, 'C' otherwise 'K' (keep) preserve input order Defaults to 'C'. Returns ------- out : ndarray Array interpretation of `a`. No copy is performed if the input is already an ndarray. If `a` is a subclass of ndarray, a base class ndarray is returned. Raises ------ ValueError Raises ValueError if `a` contains NaN (Not a Number) or Inf (Infinity). See Also -------- asarray : Create and array. asanyarray : Similar function which passes through subclasses. ascontiguousarray : Convert input to a contiguous array. asfarray : Convert input to a floating point ndarray. asfortranarray : Convert input to an ndarray with column-major memory order. fromiter : Create an array from an iterator. fromfunction : Construct an array by executing a function on grid positions. Examples -------- Convert a list into an array. If all elements are finite ``asarray_chkfinite`` is identical to ``asarray``. >>> a = [1, 2] >>> np.asarray_chkfinite(a, dtype=float) array([1., 2.]) Raises ValueError if array_like contains Nans or Infs. >>> a = [1, 2, np.inf] >>> try: ... np.asarray_chkfinite(a) ... except ValueError: ... print('ValueError') ... ValueError """ a = asarray(a, dtype=dtype, order=order) if a.dtype.char in typecodes['AllFloat'] and not np.isfinite(a).all(): raise ValueError( "array must not contain infs or NaNs") return a def _piecewise_dispatcher(x, condlist, funclist, args, kw): yield x # support the undocumented behavior of allowing scalars if np.iterable(condlist): yield from condlist @array_function_dispatch(_piecewise_dispatcher) def piecewise(x, condlist, funclist, args, *kw): """ Evaluate a piecewise-defined function. Given a set of conditions and corresponding functions, evaluate each function on the input data wherever its condition is true. Parameters ---------- x : ndarray or scalar The input domain. condlist : list of bool arrays or bool scalars Each boolean array corresponds to a function in `funclist`. Wherever `condlist[i]` is True, `funclist[i](x)` is used as the output value. Each boolean array in `condlist` selects a piece of `x`, and should therefore be of the same shape as `x`. The length of `condlist` must correspond to that of `funclist`. If one extra function is given, i.e. if ``len(funclist) == len(condlist) + 1``, then that extra function is the default value, used wherever all conditions are false. funclist : list of callables, f(x,args,*kw), or scalars Each function is evaluated over `x` wherever its corresponding condition is True. It should take a 1d array as input and give an 1d array or a scalar value as output. If, instead of a callable, a scalar is provided then a constant function (``lambda x: scalar``) is assumed. args : tuple, optional Any further arguments given to `piecewise` are passed to the functions upon execution, i.e., if called ``piecewise(..., ..., 1, 'a')``, then each function is called as ``f(x, 1, 'a')``. kw : dict, optional Keyword arguments used in calling `piecewise` are passed to the functions upon execution, i.e., if called ``piecewise(..., ..., alpha=1)``, then each function is called as ``f(x, alpha=1)``. Returns ------- out : ndarray The output is the same shape and type as x and is found by calling the functions in `funclist` on the appropriate portions of `x`, as defined by the boolean arrays in `condlist`. Portions not covered by any condition have a default value of 0. See Also -------- choose, select, where Notes ----- This is similar to choose or select, except that functions are evaluated on elements of `x` that satisfy the corresponding condition from `condlist`. The result is:: \|-- \|funclist[0](x[condlist[0]]) out = \|funclist[1](x[condlist[1]]) \|... \|funclist[n2](x[condlist[n2]]) \|-- Examples -------- Define the sigma function, which is -1 for ``x < 0`` and +1 for ``x >= 0``. >>> x = np.linspace(-2.5, 2.5, 6) >>> np.piecewise(x, [x < 0, x >= 0], [-1, 1]) array([-1., -1., -1., 1., 1., 1.]) Define the absolute value, which is ``-x`` for ``x <0`` and ``x`` for ``x >= 0``. >>> np.piecewise(x, [x < 0, x >= 0], [lambda x: -x, lambda x: x]) array([2.5, 1.5, 0.5, 0.5, 1.5, 2.5]) Apply the same function to a scalar value. >>> y = -2 >>> np.piecewise(y, [y < 0, y >= 0], [lambda x: -x, lambda x: x]) array(2) """ x = asanyarray(x) n2 = len(funclist) # undocumented: single condition is promoted to a list of one condition if isscalar(condlist) or ( not isinstance(condlist[0], (list, ndarray)) and x.ndim != 0): condlist = [condlist] condlist = asarray(condlist, dtype=bool) n = len(condlist) if n == n2 - 1: # compute the "otherwise" condition. condelse = ~np.any(condlist, axis=0, keepdims=True) condlist = np.concatenate([condlist, condelse], axis=0) n += 1 elif n != n2: raise ValueError( "with {} condition(s), either {} or {} functions are expected" .format(n, n, n+1) ) y = zeros_like(x) for cond, func in zip(condlist, funclist): if not isinstance(func, collections.abc.Callable): y[cond] = func else: vals = x[cond] if vals.size > 0: y[cond] = func(vals, args, kw) return y def _select_dispatcher(condlist, choicelist, default=None): yield from condlist yield from choicelist @array_function_dispatch(_select_dispatcher) def select(condlist, choicelist, default=0): """ Return an array drawn from elements in choicelist, depending on conditions. Parameters ---------- condlist : list of bool ndarrays The list of conditions which determine from which array in `choicelist` the output elements are taken. When multiple conditions are satisfied, the first one encountered in `condlist` is used. choicelist : list of ndarrays The list of arrays from which the output elements are taken. It has to be of the same length as `condlist`. default : scalar, optional The element inserted in `output` when all conditions evaluate to False. Returns ------- output : ndarray The output at position m is the m-th element of the array in `choicelist` where the m-th element of the corresponding array in `condlist` is True. See Also -------- where : Return elements from one of two arrays depending on condition. take, choose, compress, diag, diagonal Examples -------- >>> x = np.arange(6) >>> condlist = [x<3, x>3] >>> choicelist = [x, x2] >>> np.select(condlist, choicelist, 42) array([ 0, 1, 2, 42, 16, 25]) >>> condlist = [x<=4, x>3] >>> choicelist = [x, x*2] >>> np.select(condlist, choicelist, 55) array([ 0, 1, 2, 3, 4, 25]) """ # Check the size of condlist and choicelist are the same, or abort. if len(condlist) != len(choicelist): raise ValueError( 'list of cases must be same length as list of conditions') # Now that the dtype is known, handle the deprecated select([], []) case if len(condlist) == 0: raise ValueError("select with an empty condition list is not possible") choicelist = [np.asarray(choice) for choice in choicelist] try: intermediate_dtype = np.result_type(choicelist) except TypeError as e: msg = f'Choicelist elements do not have a common dtype: {e}' raise TypeError(msg) from None default_array = np.asarray(default) choicelist.append(default_array) # need to get the result type before broadcasting for correct scalar # behaviour try: dtype = np.result_type(intermediate_dtype, default_array) except TypeError as e: msg = f'Choicelists and default value do not have a common dtype: {e}' raise TypeError(msg) from None # Convert conditions to arrays and broadcast conditions and choices # as the shape is needed for the result. Doing it separately optimizes # for example when all choices are scalars. condlist = np.broadcast_arrays(condlist) choicelist = np.broadcast_arrays(choicelist) # If cond array is not an ndarray in boolean format or scalar bool, abort. for i, cond in enumerate(condlist): if cond.dtype.type is not np.bool_: raise TypeError( 'invalid entry {} in condlist: should be boolean ndarray'.format(i)) if choicelist[0].ndim == 0: # This may be common, so avoid the call. result_shape = condlist[0].shape else: result_shape = np.broadcast_arrays(condlist[0], choicelist[0])[0].shape result = np.full(result_shape, choicelist[-1], dtype) # Use np.copyto to burn each choicelist array onto result, using the # corresponding condlist as a boolean mask. This is done in reverse # order since the first choice should take precedence. choicelist = choicelist[-2::-1] condlist = condlist[::-1] for choice, cond in zip(choicelist, condlist): np.copyto(result, choice, where=cond) return result def _copy_dispatcher(a, order=None, subok=None): return (a,) @array_function_dispatch(_copy_dispatcher) def copy(a, order='K', subok=False): """ Return an array copy of the given object. Parameters ---------- a : array_like Input data. order : {'C', 'F', 'A', 'K'}, optional Controls the memory layout of the copy. 'C' means C-order, 'F' means F-order, 'A' means 'F' if `a` is Fortran contiguous, 'C' otherwise. 'K' means match the layout of `a` as closely as possible. (Note that this function and :meth:`ndarray.copy` are very similar, but have different default values for their order= arguments.) subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (defaults to False). .. versionadded:: 1.19.0 Returns ------- arr : ndarray Array interpretation of `a`. See Also -------- ndarray.copy : Preferred method for creating an array copy Notes ----- This is equivalent to: >>> np.array(a, copy=True) #doctest: +SKIP Examples -------- Create an array x, with a reference y and a copy z: >>> x = np.array([1, 2, 3]) >>> y = x >>> z = np.copy(x) Note that, when we modify x, y changes, but not z: >>> x[0] = 10 >>> x[0] == y[0] True >>> x[0] == z[0] False Note that, np.copy clears previously set WRITEABLE=False flag. >>> a = np.array([1, 2, 3]) >>> a.flags["WRITEABLE"] = False >>> b = np.copy(a) >>> b.flags["WRITEABLE"] True >>> b[0] = 3 >>> b array([3, 2, 3]) Note that np.copy is a shallow copy and will not copy object elements within arrays. This is mainly important for arrays containing Python objects. The new array will contain the same object which may lead to surprises if that object can be modified (is mutable): >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object) >>> b = np.copy(a) >>> b[2][0] = 10 >>> a array([1, 'm', list([10, 3, 4])], dtype=object) To ensure all elements within an ``object`` array are copied, use `copy.deepcopy`: >>> import copy >>> a = np.array([1, 'm', [2, 3, 4]], dtype=object) >>> c = copy.deepcopy(a) >>> c[2][0] = 10 >>> c array([1, 'm', list([10, 3, 4])], dtype=object) >>> a array([1, 'm', list([2, 3, 4])], dtype=object) """ return array(a, order=order, subok=subok, copy=True) # Basic operations def _gradient_dispatcher(f, varargs, axis=None, edge_order=None): yield f yield from varargs @array_function_dispatch(_gradient_dispatcher) def gradient(f, varargs, axis=None, edge_order=1): """ Return the gradient of an N-dimensional array. The gradient is computed using second order accurate central differences in the interior points and either first or second order accurate one-sides (forward or backwards) differences at the boundaries. The returned gradient hence has the same shape as the input array. Parameters ---------- f : array_like An N-dimensional array containing samples of a scalar function. varargs : list of scalar or array, optional Spacing between f values. Default unitary spacing for all dimensions. Spacing can be specified using: 1. single scalar to specify a sample distance for all dimensions. 2. N scalars to specify a constant sample distance for each dimension. i.e. `dx`, `dy`, `dz`, ... 3. N arrays to specify the coordinates of the values along each dimension of F. The length of the array must match the size of the corresponding dimension 4. Any combination of N scalars/arrays with the meaning of 2. and 3. If `axis` is given, the number of varargs must equal the number of axes. Default: 1. edge_order : {1, 2}, optional Gradient is calculated using N-th order accurate differences at the boundaries. Default: 1. .. versionadded:: 1.9.1 axis : None or int or tuple of ints, optional Gradient is calculated only along the given axis or axes The default (axis = None) is to calculate the gradient for all the axes of the input array. axis may be negative, in which case it counts from the last to the first axis. .. versionadded:: 1.11.0 Returns ------- gradient : ndarray or list of ndarray A list of ndarrays (or a single ndarray if there is only one dimension) corresponding to the derivatives of f with respect to each dimension. Each derivative has the same shape as f. Examples -------- >>> f = np.array([1, 2, 4, 7, 11, 16], dtype=float) >>> np.gradient(f) array([1. , 1.5, 2.5, 3.5, 4.5, 5. ]) >>> np.gradient(f, 2) array([0.5 , 0.75, 1.25, 1.75, 2.25, 2.5 ]) Spacing can be also specified with an array that represents the coordinates of the values F along the dimensions. For instance a uniform spacing: >>> x = np.arange(f.size) >>> np.gradient(f, x) array([1. , 1.5, 2.5, 3.5, 4.5, 5. ]) Or a non uniform one: >>> x = np.array([0., 1., 1.5, 3.5, 4., 6.], dtype=float) >>> np.gradient(f, x) array([1. , 3. , 3.5, 6.7, 6.9, 2.5]) For two dimensional arrays, the return will be two arrays ordered by axis. In this example the first array stands for the gradient in rows and the second one in columns direction: >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float)) [array([[ 2., 2., -1.], [ 2., 2., -1.]]), array([[1. , 2.5, 4. ], [1. , 1. , 1. ]])] In this example the spacing is also specified: uniform for axis=0 and non uniform for axis=1 >>> dx = 2. >>> y = [1., 1.5, 3.5] >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), dx, y) [array([[ 1. , 1. , -0.5], [ 1. , 1. , -0.5]]), array([[2. , 2. , 2. ], [2. , 1.7, 0.5]])] It is possible to specify how boundaries are treated using `edge_order` >>> x = np.array([0, 1, 2, 3, 4]) >>> f = x*2 >>> np.gradient(f, edge_order=1) array([1., 2., 4., 6., 7.]) >>> np.gradient(f, edge_order=2) array([0., 2., 4., 6., 8.]) The `axis` keyword can be used to specify a subset of axes of which the gradient is calculated >>> np.gradient(np.array([[1, 2, 6], [3, 4, 5]], dtype=float), axis=0) array([[ 2., 2., -1.], [ 2., 2., -1.]]) Notes ----- Assuming that :math:`f\\in C^{3}` (i.e., :math:`f` has at least 3 continuous derivatives) and let :math:`h_{}` be a non-homogeneous stepsize, we minimize the "consistency error" :math:`\\eta_{i}` between the true gradient and its estimate from a linear combination of the neighboring grid-points: .. math:: \\eta_{i} = f_{i}^{\\left(1\\right)} - \\left[ \\alpha f\\left(x_{i}\\right) + \\beta f\\left(x_{i} + h_{d}\\right) + \\gamma f\\left(x_{i}-h_{s}\\right) \\right] By substituting :math:`f(x_{i} + h_{d})` and :math:`f(x_{i} - h_{s})` with their Taylor series expansion, this translates into solving the following the linear system: .. math:: \\left\\{ \\begin{array}{r} \\alpha+\\beta+\\gamma=0 \\\\ \\beta h_{d}-\\gamma h_{s}=1 \\\\ \\beta h_{d}^{2}+\\gamma h_{s}^{2}=0 \\end{array} \\right. The resulting approximation of :math:`f_{i}^{(1)}` is the following: .. math:: \\hat f_{i}^{(1)} = \\frac{ h_{s}^{2}f\\left(x_{i} + h_{d}\\right) + \\left(h_{d}^{2} - h_{s}^{2}\\right)f\\left(x_{i}\\right) - h_{d}^{2}f\\left(x_{i}-h_{s}\\right)} { h_{s}h_{d}\\left(h_{d} + h_{s}\\right)} + \\mathcal{O}\\left(\\frac{h_{d}h_{s}^{2} + h_{s}h_{d}^{2}}{h_{d} + h_{s}}\\right) It is worth noting that if :math:`h_{s}=h_{d}` (i.e., data are evenly spaced) we find the standard second order approximation: .. math:: \\hat f_{i}^{(1)}= \\frac{f\\left(x_{i+1}\\right) - f\\left(x_{i-1}\\right)}{2h} + \\mathcal{O}\\left(h^{2}\\right) With a similar procedure the forward/backward approximations used for boundaries can be derived. References ---------- .. [1] Quarteroni A., Sacco R., Saleri F. (2007) Numerical Mathematics (Texts in Applied Mathematics). New York: Springer. .. [2] Durran D. R. (1999) Numerical Methods for Wave Equations in Geophysical Fluid Dynamics. New York: Springer. .. [3] Fornberg B. (1988) Generation of Finite Difference Formulas on Arbitrarily Spaced Grids, Mathematics of Computation 51, no. 184 : 699-706. `PDF <http://www.ams.org/journals/mcom/1988-51-184/ S0025-5718-1988-0935077-0/S0025-5718-1988-0935077-0.pdf>`_. """ f = np.asanyarray(f) N = f.ndim # number of dimensions if axis is None: axes = tuple(range(N)) else: axes = _nx.normalize_axis_tuple(axis, N) len_axes = len(axes) n = len(varargs) if n == 0: # no spacing argument - use 1 in all axes dx = [1.0] * len_axes elif n == 1 and np.ndim(varargs[0]) == 0: # single scalar for all axes dx = varargs * len_axes elif n == len_axes: # scalar or 1d array for each axis dx = list(varargs) for i, distances in enumerate(dx): distances = np.asanyarray(distances) if distances.ndim == 0: continue elif distances.ndim != 1: raise ValueError("distances must be either scalars or 1d") if len(distances) != f.shape[axes[i]]: raise ValueError("when 1d, distances must match " "the length of the corresponding dimension") if np.issubdtype(distances.dtype, np.integer): # Convert numpy integer types to float64 to avoid modular # arithmetic in np.diff(distances). distances = distances.astype(np.float64) diffx = np.diff(distances) # if distances are constant reduce to the scalar case # since it brings a consistent speedup if (diffx == diffx[0]).all(): diffx = diffx[0] dx[i] = diffx else: raise TypeError("invalid number of arguments") if edge_order > 2: raise ValueError("'edge_order' greater than 2 not supported") # use central differences on interior and one-sided differences on the # endpoints. This preserves second order-accuracy over the full domain. outvals = [] # create slice objects --- initially all are [:, :, ..., :] slice1 = [slice(None)]N slice2 = [slice(None)]N slice3 = [slice(None)]N slice4 = [slice(None)]N otype = f.dtype if otype.type is np.datetime64: # the timedelta dtype with the same unit information otype = np.dtype(otype.name.replace('datetime', 'timedelta')) # view as timedelta to allow addition f = f.view(otype) elif otype.type is np.timedelta64: pass elif np.issubdtype(otype, np.inexact): pass else: # All other types convert to floating point. # First check if f is a numpy integer type; if so, convert f to float64 # to avoid modular arithmetic when computing the changes in f. if np.issubdtype(otype, np.integer): f = f.astype(np.float64) otype = np.float64 for axis, ax_dx in zip(axes, dx): if f.shape[axis] < edge_order + 1: raise ValueError( "Shape of array too small to calculate a numerical gradient, " "at least (edge_order + 1) elements are required.") # result allocation out = np.empty_like(f, dtype=otype) # spacing for the current axis uniform_spacing = np.ndim(ax_dx) == 0 # Numerical differentiation: 2nd order interior slice1[axis] = slice(1, -1) slice2[axis] = slice(None, -2) slice3[axis] = slice(1, -1) slice4[axis] = slice(2, None) if uniform_spacing: out[tuple(slice1)] = (f[tuple(slice4)] - f[tuple(slice2)]) / (2. * ax_dx) else: dx1 = ax_dx[0:-1] dx2 = ax_dx[1:] a = -(dx2)/(dx1 * (dx1 + dx2)) b = (dx2 - dx1) / (dx1 * dx2) c = dx1 / (dx2 * (dx1 + dx2)) # fix the shape for broadcasting shape = np.ones(N, dtype=int) shape[axis] = -1 a.shape = b.shape = c.shape = shape # 1D equivalent -- out[1:-1] = a * f[:-2] + b * f[1:-1] + c * f[2:] out[tuple(slice1)] = a * f[tuple(slice2)] + b * f[tuple(slice3)] + c * f[tuple(slice4)] # Numerical differentiation: 1st order edges if edge_order == 1: slice1[axis] = 0 slice2[axis] = 1 slice3[axis] = 0 dx_0 = ax_dx if uniform_spacing else ax_dx[0] # 1D equivalent -- out[0] = (f[1] - f[0]) / (x[1] - x[0]) out[tuple(slice1)] = (f[tuple(slice2)] - f[tuple(slice3)]) / dx_0 slice1[axis] = -1 slice2[axis] = -1 slice3[axis] = -2 dx_n = ax_dx if uniform_spacing else ax_dx[-1] # 1D equivalent -- out[-1] = (f[-1] - f[-2]) / (x[-1] - x[-2]) out[tuple(slice1)] = (f[tuple(slice2)] - f[tuple(slice3)]) / dx_n # Numerical differentiation: 2nd order edges else: slice1[axis] = 0 slice2[axis] = 0 slice3[axis] = 1 slice4[axis] = 2 if uniform_spacing: a = -1.5 / ax_dx b = 2. / ax_dx c = -0.5 / ax_dx else: dx1 = ax_dx[0] dx2 = ax_dx[1] a = -(2. * dx1 + dx2)/(dx1 * (dx1 + dx2)) b = (dx1 + dx2) / (dx1 * dx2) c = - dx1 / (dx2 * (dx1 + dx2)) # 1D equivalent -- out[0] = a * f[0] + b * f[1] + c * f[2] out[tuple(slice1)] = a * f[tuple(slice2)] + b * f[tuple(slice3)] + c * f[tuple(slice4)] slice1[axis] = -1 slice2[axis] = -3 slice3[axis] = -2 slice4[axis] = -1 if uniform_spacing: a = 0.5 / ax_dx b = -2. / ax_dx c = 1.5 / ax_dx else: dx1 = ax_dx[-2] dx2 = ax_dx[-1] a = (dx2) / (dx1 * (dx1 + dx2)) b = - (dx2 + dx1) / (dx1 * dx2) c = (2. * dx2 + dx1) / (dx2 * (dx1 + dx2)) # 1D equivalent -- out[-1] = a * f[-3] + b * f[-2] + c * f[-1] out[tuple(slice1)] = a * f[tuple(slice2)] + b * f[tuple(slice3)] + c * f[tuple(slice4)] outvals.append(out) # reset the slice object in this dimension to ":" slice1[axis] = slice(None) slice2[axis] = slice(None) slice3[axis] = slice(None) slice4[axis] = slice(None) if len_axes == 1: return outvals[0] elif np._using_numpy2_behavior(): return tuple(outvals) else: return outvals def _diff_dispatcher(a, n=None, axis=None, prepend=None, append=None): return (a, prepend, append) @array_function_dispatch(_diff_dispatcher) def diff(a, n=1, axis=-1, prepend=np._NoValue, append=np._NoValue): """ Calculate the n-th discrete difference along the given axis. The first difference is given by ``out[i] = a[i+1] - a[i]`` along the given axis, higher differences are calculated by using `diff` recursively. Parameters ---------- a : array_like Input array n : int, optional The number of times values are differenced. If zero, the input is returned as-is. axis : int, optional The axis along which the difference is taken, default is the last axis. prepend, append : array_like, optional Values to prepend or append to `a` along axis prior to performing the difference. Scalar values are expanded to arrays with length 1 in the direction of axis and the shape of the input array in along all other axes. Otherwise the dimension and shape must match `a` except along axis. .. versionadded:: 1.16.0 Returns ------- diff : ndarray The n-th differences. The shape of the output is the same as `a` except along `axis` where the dimension is smaller by `n`. The type of the output is the same as the type of the difference between any two elements of `a`. This is the same as the type of `a` in most cases. A notable exception is `datetime64`, which results in a `timedelta64` output array. See Also -------- gradient, ediff1d, cumsum Notes ----- Type is preserved for boolean arrays, so the result will contain `False` when consecutive elements are the same and `True` when they differ. For unsigned integer arrays, the results will also be unsigned. This should not be surprising, as the result is consistent with calculating the difference directly: >>> u8_arr = np.array([1, 0], dtype=np.uint8) >>> np.diff(u8_arr) array([255], dtype=uint8) >>> u8_arr[1,...] - u8_arr[0,...] 255 If this is not desirable, then the array should be cast to a larger integer type first: >>> i16_arr = u8_arr.astype(np.int16) >>> np.diff(i16_arr) array([-1], dtype=int16) Examples -------- >>> x = np.array([1, 2, 4, 7, 0]) >>> np.diff(x) array([ 1, 2, 3, -7]) >>> np.diff(x, n=2) array([ 1, 1, -10]) >>> x = np.array([[1, 3, 6, 10], [0, 5, 6, 8]]) >>> np.diff(x) array([[2, 3, 4], [5, 1, 2]]) >>> np.diff(x, axis=0) array([[-1, 2, 0, -2]]) >>> x = np.arange('1066-10-13', '1066-10-16', dtype=np.datetime64) >>> np.diff(x) array([1, 1], dtype='timedelta64[D]') """ if n == 0: return a if n < 0: raise ValueError( "order must be non-negative but got " + repr(n)) a = asanyarray(a) nd = a.ndim if nd == 0: raise ValueError("diff requires input that is at least one dimensional") axis = normalize_axis_index(axis, nd) combined = [] if prepend is not np._NoValue: prepend = np.asanyarray(prepend) if prepend.ndim == 0: shape = list(a.shape) shape[axis] = 1 prepend = np.broadcast_to(prepend, tuple(shape)) combined.append(prepend) combined.append(a) if append is not np._NoValue: append = np.asanyarray(append) if append.ndim == 0: shape = list(a.shape) shape[axis] = 1 append = np.broadcast_to(append, tuple(shape)) combined.append(append) if len(combined) > 1: a = np.concatenate(combined, axis) slice1 = [slice(None)] * nd slice2 = [slice(None)] * nd slice1[axis] = slice(1, None) slice2[axis] = slice(None, -1) slice1 = tuple(slice1) slice2 = tuple(slice2) op = not_equal if a.dtype == np.bool_ else subtract for _ in range(n): a = op(a[slice1], a[slice2]) return a def _interp_dispatcher(x, xp, fp, left=None, right=None, period=None): return (x, xp, fp) @array_function_dispatch(_interp_dispatcher) def interp(x, xp, fp, left=None, right=None, period=None): """ One-dimensional linear interpolation for monotonically increasing sample points. Returns the one-dimensional piecewise linear interpolant to a function with given discrete data points (`xp`, `fp`), evaluated at `x`. Parameters ---------- x : array_like The x-coordinates at which to evaluate the interpolated values. xp : 1-D sequence of floats The x-coordinates of the data points, must be increasing if argument `period` is not specified. Otherwise, `xp` is internally sorted after normalizing the periodic boundaries with ``xp = xp % period``. fp : 1-D sequence of float or complex The y-coordinates of the data points, same length as `xp`. left : optional float or complex corresponding to fp Value to return for `x < xp[0]`, default is `fp[0]`. right : optional float or complex corresponding to fp Value to return for `x > xp[-1]`, default is `fp[-1]`. period : None or float, optional A period for the x-coordinates. This parameter allows the proper interpolation of angular x-coordinates. Parameters `left` and `right` are ignored if `period` is specified. .. versionadded:: 1.10.0 Returns ------- y : float or complex (corresponding to fp) or ndarray The interpolated values, same shape as `x`. Raises ------ ValueError If `xp` and `fp` have different length If `xp` or `fp` are not 1-D sequences If `period == 0` See Also -------- scipy.interpolate Warnings -------- The x-coordinate sequence is expected to be increasing, but this is not explicitly enforced. However, if the sequence `xp` is non-increasing, interpolation results are meaningless. Note that, since NaN is unsortable, `xp` also cannot contain NaNs. A simple check for `xp` being strictly increasing is:: np.all(np.diff(xp) > 0) Examples -------- >>> xp = [1, 2, 3] >>> fp = [3, 2, 0] >>> np.interp(2.5, xp, fp) 1.0 >>> np.interp([0, 1, 1.5, 2.72, 3.14], xp, fp) array([3. , 3. , 2.5 , 0.56, 0. ]) >>> UNDEF = -99.0 >>> np.interp(3.14, xp, fp, right=UNDEF) -99.0 Plot an interpolant to the sine function: >>> x = np.linspace(0, 2np.pi, 10) >>> y = np.sin(x) >>> xvals = np.linspace(0, 2np.pi, 50) >>> yinterp = np.interp(xvals, x, y) >>> import matplotlib.pyplot as plt >>> plt.plot(x, y, 'o') [<matplotlib.lines.Line2D object at 0x...>] >>> plt.plot(xvals, yinterp, '-x') [<matplotlib.lines.Line2D object at 0x...>] >>> plt.show() Interpolation with periodic x-coordinates: >>> x = [-180, -170, -185, 185, -10, -5, 0, 365] >>> xp = [190, -190, 350, -350] >>> fp = [5, 10, 3, 4] >>> np.interp(x, xp, fp, period=360) array([7.5 , 5. , 8.75, 6.25, 3. , 3.25, 3.5 , 3.75]) Complex interpolation: >>> x = [1.5, 4.0] >>> xp = [2,3,5] >>> fp = [1.0j, 0, 2+3j] >>> np.interp(x, xp, fp) array([0.+1.j , 1.+1.5j]) """ fp = np.asarray(fp) if np.iscomplexobj(fp): interp_func = compiled_interp_complex input_dtype = np.complex128 else: interp_func = compiled_interp input_dtype = np.float64 if period is not None: if period == 0: raise ValueError("period must be a non-zero value") period = abs(period) left = None right = None x = np.asarray(x, dtype=np.float64) xp = np.asarray(xp, dtype=np.float64) fp = np.asarray(fp, dtype=input_dtype) if xp.ndim != 1 or fp.ndim != 1: raise ValueError("Data points must be 1-D sequences") if xp.shape[0] != fp.shape[0]: raise ValueError("fp and xp are not of the same length") # normalizing periodic boundaries x = x % period xp = xp % period asort_xp = np.argsort(xp) xp = xp[asort_xp] fp = fp[asort_xp] xp = np.concatenate((xp[-1:]-period, xp, xp[0:1]+period)) fp = np.concatenate((fp[-1:], fp, fp[0:1])) return interp_func(x, xp, fp, left, right) def _angle_dispatcher(z, deg=None): return (z,) @array_function_dispatch(_angle_dispatcher) def angle(z, deg=False): """ Return the angle of the complex argument. Parameters ---------- z : array_like A complex number or sequence of complex numbers. deg : bool, optional Return angle in degrees if True, radians if False (default). Returns ------- angle : ndarray or scalar The counterclockwise angle from the positive real axis on the complex plane in the range ``(-pi, pi]``, with dtype as numpy.float64. .. versionchanged:: 1.16.0 This function works on subclasses of ndarray like `ma.array`. See Also -------- arctan2 absolute Notes ----- Although the angle of the complex number 0 is undefined, ``numpy.angle(0)`` returns the value 0. Examples -------- >>> np.angle([1.0, 1.0j, 1+1j]) # in radians array([ 0. , 1.57079633, 0.78539816]) # may vary >>> np.angle(1+1j, deg=True) # in degrees 45.0 """ z = asanyarray(z) if issubclass(z.dtype.type, _nx.complexfloating): zimag = z.imag zreal = z.real else: zimag = 0 zreal = z a = arctan2(zimag, zreal) if deg: a = 180/pi return a def _unwrap_dispatcher(p, discont=None, axis=None, , period=None): return (p,) @array_function_dispatch(_unwrap_dispatcher) def unwrap(p, discont=None, axis=-1, , period=2pi): r""" Unwrap by taking the complement of large deltas with respect to the period. This unwraps a signal `p` by changing elements which have an absolute difference from their predecessor of more than ``max(discont, period/2)`` to their `period`-complementary values. For the default case where `period` is :math:`2\pi` and `discont` is :math:`\pi`, this unwraps a radian phase `p` such that adjacent differences are never greater than :math:`\pi` by adding :math:`2k\pi` for some integer :math:`k`. Parameters ---------- p : array_like Input array. discont : float, optional Maximum discontinuity between values, default is ``period/2``. Values below ``period/2`` are treated as if they were ``period/2``. To have an effect different from the default, `discont` should be larger than ``period/2``. axis : int, optional Axis along which unwrap will operate, default is the last axis. period : float, optional Size of the range over which the input wraps. By default, it is ``2 pi``. .. versionadded:: 1.21.0 Returns ------- out : ndarray Output array. See Also -------- rad2deg, deg2rad Notes ----- If the discontinuity in `p` is smaller than ``period/2``, but larger than `discont`, no unwrapping is done because taking the complement would only make the discontinuity larger. Examples -------- >>> phase = np.linspace(0, np.pi, num=5) >>> phase[3:] += np.pi >>> phase array([ 0. , 0.78539816, 1.57079633, 5.49778714, 6.28318531]) # may vary >>> np.unwrap(phase) array([ 0. , 0.78539816, 1.57079633, -0.78539816, 0. ]) # may vary >>> np.unwrap([0, 1, 2, -1, 0], period=4) array([0, 1, 2, 3, 4]) >>> np.unwrap([ 1, 2, 3, 4, 5, 6, 1, 2, 3], period=6) array([1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> np.unwrap([2, 3, 4, 5, 2, 3, 4, 5], period=4) array([2, 3, 4, 5, 6, 7, 8, 9]) >>> phase_deg = np.mod(np.linspace(0 ,720, 19), 360) - 180 >>> np.unwrap(phase_deg, period=360) array([-180., -140., -100., -60., -20., 20., 60., 100., 140., 180., 220., 260., 300., 340., 380., 420., 460., 500., 540.]) """ p = asarray(p) nd = p.ndim dd = diff(p, axis=axis) if discont is None: discont = period/2 slice1 = [slice(None, None)]nd # full slices slice1[axis] = slice(1, None) slice1 = tuple(slice1) dtype = np.result_type(dd, period) if _nx.issubdtype(dtype, _nx.integer): interval_high, rem = divmod(period, 2) boundary_ambiguous = rem == 0 else: interval_high = period / 2 boundary_ambiguous = True interval_low = -interval_high ddmod = mod(dd - interval_low, period) + interval_low if boundary_ambiguous: # for `mask = (abs(dd) == period/2)`, the above line made # `ddmod[mask] == -period/2`. correct these such that # `ddmod[mask] == sign(dd[mask])period/2`. _nx.copyto(ddmod, interval_high, where=(ddmod == interval_low) & (dd > 0)) ph_correct = ddmod - dd _nx.copyto(ph_correct, 0, where=abs(dd) < discont) up = array(p, copy=True, dtype=dtype) up[slice1] = p[slice1] + ph_correct.cumsum(axis) return up def _sort_complex(a): return (a,) @array_function_dispatch(_sort_complex) def sort_complex(a): """ Sort a complex array using the real part first, then the imaginary part. Parameters ---------- a : array_like Input array Returns ------- out : complex ndarray Always returns a sorted complex array. Examples -------- >>> np.sort_complex([5, 3, 6, 2, 1]) array([1.+0.j, 2.+0.j, 3.+0.j, 5.+0.j, 6.+0.j]) >>> np.sort_complex([1 + 2j, 2 - 1j, 3 - 2j, 3 - 3j, 3 + 5j]) array([1.+2.j, 2.-1.j, 3.-3.j, 3.-2.j, 3.+5.j]) """ b = array(a, copy=True) b.sort() if not issubclass(b.dtype.type, _nx.complexfloating): if b.dtype.char in 'bhBH': return b.astype('F') elif b.dtype.char == 'g': return b.astype('G') else: return b.astype('D') else: return b def _trim_zeros(filt, trim=None): return (filt,) @array_function_dispatch(_trim_zeros) def trim_zeros(filt, trim='fb'): """ Trim the leading and/or trailing zeros from a 1-D array or sequence. Parameters ---------- filt : 1-D array or sequence Input array. trim : str, optional A string with 'f' representing trim from front and 'b' to trim from back. Default is 'fb', trim zeros from both front and back of the array. Returns ------- trimmed : 1-D array or sequence The result of trimming the input. The input data type is preserved. Examples -------- >>> a = np.array((0, 0, 0, 1, 2, 3, 0, 2, 1, 0)) >>> np.trim_zeros(a) array([1, 2, 3, 0, 2, 1]) >>> np.trim_zeros(a, 'b') array([0, 0, 0, ..., 0, 2, 1]) The input data type is preserved, list/tuple in means list/tuple out. >>> np.trim_zeros([0, 1, 2, 0]) [1, 2] """ first = 0 trim = trim.upper() if 'F' in trim: for i in filt: if i != 0.: break else: first = first + 1 last = len(filt) if 'B' in trim: for i in filt[::-1]: if i != 0.: break else: last = last - 1 return filt[first:last] def _extract_dispatcher(condition, arr): return (condition, arr) @array_function_dispatch(_extract_dispatcher) def extract(condition, arr): """ Return the elements of an array that satisfy some condition. This is equivalent to ``np.compress(ravel(condition), ravel(arr))``. If `condition` is boolean ``np.extract`` is equivalent to ``arr[condition]``. Note that `place` does the exact opposite of `extract`. Parameters ---------- condition : array_like An array whose nonzero or True entries indicate the elements of `arr` to extract. arr : array_like Input array of the same size as `condition`. Returns ------- extract : ndarray Rank 1 array of values from `arr` where `condition` is True. See Also -------- take, put, copyto, compress, place Examples -------- >>> arr = np.arange(12).reshape((3, 4)) >>> arr array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]]) >>> condition = np.mod(arr, 3)==0 >>> condition array([[ True, False, False, True], [False, False, True, False], [False, True, False, False]]) >>> np.extract(condition, arr) array([0, 3, 6, 9]) If `condition` is boolean: >>> arr[condition] array([0, 3, 6, 9]) """ return _nx.take(ravel(arr), nonzero(ravel(condition))[0]) def _place_dispatcher(arr, mask, vals): return (arr, mask, vals) @array_function_dispatch(_place_dispatcher) def place(arr, mask, vals): """ Change elements of an array based on conditional and input values. Similar to ``np.copyto(arr, vals, where=mask)``, the difference is that `place` uses the first N elements of `vals`, where N is the number of True values in `mask`, while `copyto` uses the elements where `mask` is True. Note that `extract` does the exact opposite of `place`. Parameters ---------- arr : ndarray Array to put data into. mask : array_like Boolean mask array. Must have the same size as `a`. vals : 1-D sequence Values to put into `a`. Only the first N elements are used, where N is the number of True values in `mask`. If `vals` is smaller than N, it will be repeated, and if elements of `a` are to be masked, this sequence must be non-empty. See Also -------- copyto, put, take, extract Examples -------- >>> arr = np.arange(6).reshape(2, 3) >>> np.place(arr, arr>2, [44, 55]) >>> arr array([[ 0, 1, 2], [44, 55, 44]]) """ return _place(arr, mask, vals) def disp(mesg, device=None, linefeed=True): """ Display a message on a device. Parameters ---------- mesg : str Message to display. device : object Device to write message. If None, defaults to ``sys.stdout`` which is very similar to ``print``. `device` needs to have ``write()`` and ``flush()`` methods. linefeed : bool, optional Option whether to print a line feed or not. Defaults to True. Raises ------ AttributeError If `device` does not have a ``write()`` or ``flush()`` method. Examples -------- Besides ``sys.stdout``, a file-like object can also be used as it has both required methods: >>> from io import StringIO >>> buf = StringIO() >>> np.disp(u'"Display" in a file', device=buf) >>> buf.getvalue() '"Display" in a file\\n' """ if device is None: device = sys.stdout if linefeed: device.write('%s\n' % mesg) else: device.write('%s' % mesg) device.flush() return # See https://docs.scipy.org/doc/numpy/reference/c-api.generalized-ufuncs.html _DIMENSION_NAME = r'\w+' _CORE_DIMENSION_LIST = '(?:{0:}(?:,{0:}))?'.format(_DIMENSION_NAME) _ARGUMENT = r'${}$'.format(_CORE_DIMENSION_LIST) _ARGUMENT_LIST = '{0:}(?:,{0:})'.format(_ARGUMENT) _SIGNATURE = '^{0:}->{0:}$'.format(_ARGUMENT_LIST) def _parse_gufunc_signature(signature): """ Parse string signatures for a generalized universal function. Arguments --------- signature : string Generalized universal function signature, e.g., ``(m,n),(n,p)->(m,p)`` for ``np.matmul``. Returns ------- Tuple of input and output core dimensions parsed from the signature, each of the form List[Tuple[str, ...]]. """ signature = re.sub(r'\s+', '', signature) if not re.match(_SIGNATURE, signature): raise ValueError( 'not a valid gufunc signature: {}'.format(signature)) return tuple([tuple(re.findall(_DIMENSION_NAME, arg)) for arg in re.findall(_ARGUMENT, arg_list)] for arg_list in signature.split('->')) def _update_dim_sizes(dim_sizes, arg, core_dims): """ Incrementally check and update core dimension sizes for a single argument. Arguments --------- dim_sizes : Dict[str, int] Sizes of existing core dimensions. Will be updated in-place. arg : ndarray Argument to examine. core_dims : Tuple[str, ...] Core dimensions for this argument. """ if not core_dims: return num_core_dims = len(core_dims) if arg.ndim < num_core_dims: raise ValueError( '%d-dimensional argument does not have enough ' 'dimensions for all core dimensions %r' % (arg.ndim, core_dims)) core_shape = arg.shape[-num_core_dims:] for dim, size in zip(core_dims, core_shape): if dim in dim_sizes: if size != dim_sizes[dim]: raise ValueError( 'inconsistent size for core dimension %r: %r vs %r' % (dim, size, dim_sizes[dim])) else: dim_sizes[dim] = size def _parse_input_dimensions(args, input_core_dims): """ Parse broadcast and core dimensions for vectorize with a signature. Arguments --------- args : Tuple[ndarray, ...] Tuple of input arguments to examine. input_core_dims : List[Tuple[str, ...]] List of core dimensions corresponding to each input. Returns ------- broadcast_shape : Tuple[int, ...] Common shape to broadcast all non-core dimensions to. dim_sizes : Dict[str, int] Common sizes for named core dimensions. """ broadcast_args = [] dim_sizes = {} for arg, core_dims in zip(args, input_core_dims): _update_dim_sizes(dim_sizes, arg, core_dims) ndim = arg.ndim - len(core_dims) dummy_array = np.lib.stride_tricks.as_strided(0, arg.shape[:ndim]) broadcast_args.append(dummy_array) broadcast_shape = np.lib.stride_tricks._broadcast_shape(broadcast_args) return broadcast_shape, dim_sizes def _calculate_shapes(broadcast_shape, dim_sizes, list_of_core_dims): """Helper for calculating broadcast shapes with core dimensions.""" return [broadcast_shape + tuple(dim_sizes[dim] for dim in core_dims) for core_dims in list_of_core_dims] def _create_arrays(broadcast_shape, dim_sizes, list_of_core_dims, dtypes, results=None): """Helper for creating output arrays in vectorize.""" shapes = _calculate_shapes(broadcast_shape, dim_sizes, list_of_core_dims) if dtypes is None: dtypes = [None] len(shapes) if results is None: arrays = tuple(np.empty(shape=shape, dtype=dtype) for shape, dtype in zip(shapes, dtypes)) else: arrays = tuple(np.empty_like(result, shape=shape, dtype=dtype) for result, shape, dtype in zip(results, shapes, dtypes)) return arrays @set_module('numpy') class vectorize: """ vectorize(pyfunc=np._NoValue, otypes=None, doc=None, excluded=None, cache=False, signature=None) Returns an object that acts like pyfunc, but takes arrays as input. Define a vectorized function which takes a nested sequence of objects or numpy arrays as inputs and returns a single numpy array or a tuple of numpy arrays. The vectorized function evaluates `pyfunc` over successive tuples of the input arrays like the python map function, except it uses the broadcasting rules of numpy. The data type of the output of `vectorized` is determined by calling the function with the first element of the input. This can be avoided by specifying the `otypes` argument. Parameters ---------- pyfunc : callable, optional A python function or method. Can be omitted to produce a decorator with keyword arguments. otypes : str or list of dtypes, optional The output data type. It must be specified as either a string of typecode characters or a list of data type specifiers. There should be one data type specifier for each output. doc : str, optional The docstring for the function. If None, the docstring will be the ``pyfunc.__doc__``. excluded : set, optional Set of strings or integers representing the positional or keyword arguments for which the function will not be vectorized. These will be passed directly to `pyfunc` unmodified. .. versionadded:: 1.7.0 cache : bool, optional If `True`, then cache the first function call that determines the number of outputs if `otypes` is not provided. .. versionadded:: 1.7.0 signature : string, optional Generalized universal function signature, e.g., ``(m,n),(n)->(m)`` for vectorized matrix-vector multiplication. If provided, ``pyfunc`` will be called with (and expected to return) arrays with shapes given by the size of corresponding core dimensions. By default, ``pyfunc`` is assumed to take scalars as input and output. .. versionadded:: 1.12.0 Returns ------- out : callable A vectorized function if ``pyfunc`` was provided, a decorator otherwise. See Also -------- frompyfunc : Takes an arbitrary Python function and returns a ufunc Notes ----- The `vectorize` function is provided primarily for convenience, not for performance. The implementation is essentially a for loop. If `otypes` is not specified, then a call to the function with the first argument will be used to determine the number of outputs. The results of this call will be cached if `cache` is `True` to prevent calling the function twice. However, to implement the cache, the original function must be wrapped which will slow down subsequent calls, so only do this if your function is expensive. The new keyword argument interface and `excluded` argument support further degrades performance. References ---------- .. [1] :doc:`/reference/c-api/generalized-ufuncs` Examples -------- >>> def myfunc(a, b): ... "Return a-b if a>b, otherwise return a+b" ... if a > b: ... return a - b ... else: ... return a + b >>> vfunc = np.vectorize(myfunc) >>> vfunc([1, 2, 3, 4], 2) array([3, 4, 1, 2]) The docstring is taken from the input function to `vectorize` unless it is specified: >>> vfunc.__doc__ 'Return a-b if a>b, otherwise return a+b' >>> vfunc = np.vectorize(myfunc, doc='Vectorized `myfunc`') >>> vfunc.__doc__ 'Vectorized `myfunc`' The output type is determined by evaluating the first element of the input, unless it is specified: >>> out = vfunc([1, 2, 3, 4], 2) >>> type(out[0]) <class 'numpy.int64'> >>> vfunc = np.vectorize(myfunc, otypes=[float]) >>> out = vfunc([1, 2, 3, 4], 2) >>> type(out[0]) <class 'numpy.float64'> The `excluded` argument can be used to prevent vectorizing over certain arguments. This can be useful for array-like arguments of a fixed length such as the coefficients for a polynomial as in `polyval`: >>> def mypolyval(p, x): ... _p = list(p) ... res = _p.pop(0) ... while _p: ... res = resx + _p.pop(0) ... return res >>> vpolyval = np.vectorize(mypolyval, excluded=['p']) >>> vpolyval(p=[1, 2, 3], x=[0, 1]) array([3, 6]) Positional arguments may also be excluded by specifying their position: >>> vpolyval.excluded.add(0) >>> vpolyval([1, 2, 3], x=[0, 1]) array([3, 6]) The `signature` argument allows for vectorizing functions that act on non-scalar arrays of fixed length. For example, you can use it for a vectorized calculation of Pearson correlation coefficient and its p-value: >>> import scipy.stats >>> pearsonr = np.vectorize(scipy.stats.pearsonr, ... signature='(n),(n)->(),()') >>> pearsonr([[0, 1, 2, 3]], [[1, 2, 3, 4], [4, 3, 2, 1]]) (array([ 1., -1.]), array([ 0., 0.])) Or for a vectorized convolution: >>> convolve = np.vectorize(np.convolve, signature='(n),(m)->(k)') >>> convolve(np.eye(4), [1, 2, 1]) array([[1., 2., 1., 0., 0., 0.], [0., 1., 2., 1., 0., 0.], [0., 0., 1., 2., 1., 0.], [0., 0., 0., 1., 2., 1.]]) Decorator syntax is supported. The decorator can be called as a function to provide keyword arguments. >>>@np.vectorize ...def identity(x): ... return x ... >>>identity([0, 1, 2]) array([0, 1, 2]) >>>@np.vectorize(otypes=[float]) ...def as_float(x): ... return x ... >>>as_float([0, 1, 2]) array([0., 1., 2.]) """ def __init__(self, pyfunc=np._NoValue, otypes=None, doc=None, excluded=None, cache=False, signature=None): if (pyfunc != np._NoValue) and (not callable(pyfunc)): #Splitting the error message to keep #the length below 79 characters. part1 = "When used as a decorator, " part2 = "only accepts keyword arguments." raise TypeError(part1 + part2) self.pyfunc = pyfunc self.cache = cache self.signature = signature if pyfunc != np._NoValue and hasattr(pyfunc, '__name__'): self.__name__ = pyfunc.__name__ self._ufunc = {} # Caching to improve default performance self._doc = None self.__doc__ = doc if doc is None and hasattr(pyfunc, '__doc__'): self.__doc__ = pyfunc.__doc__ else: self._doc = doc if isinstance(otypes, str): for char in otypes: if char not in typecodes['All']: raise ValueError("Invalid otype specified: %s" % (char,)) elif iterable(otypes): otypes = ''.join([_nx.dtype(x).char for x in otypes]) elif otypes is not None: raise ValueError("Invalid otype specification") self.otypes = otypes # Excluded variable support if excluded is None: excluded = set() self.excluded = set(excluded) if signature is not None: self._in_and_out_core_dims = _parse_gufunc_signature(signature) else: self._in_and_out_core_dims = None def _init_stage_2(self, pyfunc, args, *kwargs): self.__name__ = pyfunc.__name__ self.pyfunc = pyfunc if self._doc is None: self.__doc__ = pyfunc.__doc__ else: self.__doc__ = self._doc def _call_as_normal(self, args, *kwargs): """ Return arrays with the results of `pyfunc` broadcast (vectorized) over `args` and `kwargs` not in `excluded`. """ excluded = self.excluded if not kwargs and not excluded: func = self.pyfunc vargs = args else: # The wrapper accepts only positional arguments: we use `names` and # `inds` to mutate `the_args` and `kwargs` to pass to the original # function. nargs = len(args) names = [_n for _n in kwargs if _n not in excluded] inds = [_i for _i in range(nargs) if _i not in excluded] the_args = list(args) def func(vargs): for _n, _i in enumerate(inds): the_args[_i] = vargs[_n] kwargs.update(zip(names, vargs[len(inds):])) return self.pyfunc(the_args, kwargs) vargs = [args[_i] for _i in inds] vargs.extend([kwargs[_n] for _n in names]) return self._vectorize_call(func=func, args=vargs) def __call__(self, args, *kwargs): if self.pyfunc is np._NoValue: self._init_stage_2(args, *kwargs) return self return self._call_as_normal(args, *kwargs) def _get_ufunc_and_otypes(self, func, args): """Return (ufunc, otypes).""" # frompyfunc will fail if args is empty if not args: raise ValueError('args can not be empty') if self.otypes is not None: otypes = self.otypes # self._ufunc is a dictionary whose keys are the number of # arguments (i.e. len(args)) and whose values are ufuncs created # by frompyfunc. len(args) can be different for different calls if # self.pyfunc has parameters with default values. We only use the # cache when func is self.pyfunc, which occurs when the call uses # only positional arguments and no arguments are excluded. nin = len(args) nout = len(self.otypes) if func is not self.pyfunc or nin not in self._ufunc: ufunc = frompyfunc(func, nin, nout) else: ufunc = None # We'll get it from self._ufunc if func is self.pyfunc: ufunc = self._ufunc.setdefault(nin, ufunc) else: # Get number of outputs and output types by calling the function on # the first entries of args. We also cache the result to prevent # the subsequent call when the ufunc is evaluated. # Assumes that ufunc first evaluates the 0th elements in the input # arrays (the input values are not checked to ensure this) args = [asarray(arg) for arg in args] if builtins.any(arg.size == 0 for arg in args): raise ValueError('cannot call `vectorize` on size 0 inputs ' 'unless `otypes` is set') inputs = [arg.flat[0] for arg in args] outputs = func(inputs) # Performance note: profiling indicates that -- for simple # functions at least -- this wrapping can almost double the # execution time. # Hence we make it optional. if self.cache: _cache = [outputs] def _func(vargs): if _cache: return _cache.pop() else: return func(vargs) else: _func = func if isinstance(outputs, tuple): nout = len(outputs) else: nout = 1 outputs = (outputs,) otypes = ''.join([asarray(outputs[_k]).dtype.char for _k in range(nout)]) # Performance note: profiling indicates that creating the ufunc is # not a significant cost compared with wrapping so it seems not # worth trying to cache this. ufunc = frompyfunc(_func, len(args), nout) return ufunc, otypes def _vectorize_call(self, func, args): """Vectorized call to `func` over positional `args`.""" if self.signature is not None: res = self._vectorize_call_with_signature(func, args) elif not args: res = func() else: ufunc, otypes = self._get_ufunc_and_otypes(func=func, args=args) # Convert args to object arrays first inputs = [asanyarray(a, dtype=object) for a in args] outputs = ufunc(inputs) if ufunc.nout == 1: res = asanyarray(outputs, dtype=otypes[0]) else: res = tuple([asanyarray(x, dtype=t) for x, t in zip(outputs, otypes)]) return res def _vectorize_call_with_signature(self, func, args): """Vectorized call over positional arguments with a signature.""" input_core_dims, output_core_dims = self._in_and_out_core_dims if len(args) != len(input_core_dims): raise TypeError('wrong number of positional arguments: ' 'expected %r, got %r' % (len(input_core_dims), len(args))) args = tuple(asanyarray(arg) for arg in args) broadcast_shape, dim_sizes = _parse_input_dimensions( args, input_core_dims) input_shapes = _calculate_shapes(broadcast_shape, dim_sizes, input_core_dims) args = [np.broadcast_to(arg, shape, subok=True) for arg, shape in zip(args, input_shapes)] outputs = None otypes = self.otypes nout = len(output_core_dims) for index in np.ndindex(broadcast_shape): results = func((arg[index] for arg in args)) n_results = len(results) if isinstance(results, tuple) else 1 if nout != n_results: raise ValueError( 'wrong number of outputs from pyfunc: expected %r, got %r' % (nout, n_results)) if nout == 1: results = (results,) if outputs is None: for result, core_dims in zip(results, output_core_dims): _update_dim_sizes(dim_sizes, result, core_dims) outputs = _create_arrays(broadcast_shape, dim_sizes, output_core_dims, otypes, results) for output, result in zip(outputs, results): output[index] = result if outputs is None: # did not call the function even once if otypes is None: raise ValueError('cannot call `vectorize` on size 0 inputs ' 'unless `otypes` is set') if builtins.any(dim not in dim_sizes for dims in output_core_dims for dim in dims): raise ValueError('cannot call `vectorize` with a signature ' 'including new output dimensions on size 0 ' 'inputs') outputs = _create_arrays(broadcast_shape, dim_sizes, output_core_dims, otypes) return outputs[0] if nout == 1 else outputs def _cov_dispatcher(m, y=None, rowvar=None, bias=None, ddof=None, fweights=None, aweights=None, , dtype=None): return (m, y, fweights, aweights) @array_function_dispatch(_cov_dispatcher) def cov(m, y=None, rowvar=True, bias=False, ddof=None, fweights=None, aweights=None, , dtype=None): """ Estimate a covariance matrix, given data and weights. Covariance indicates the level to which two variables vary together. If we examine N-dimensional samples, :math:`X = [x_1, x_2, ... x_N]^T`, then the covariance matrix element :math:`C_{ij}` is the covariance of :math:`x_i` and :math:`x_j`. The element :math:`C_{ii}` is the variance of :math:`x_i`. See the notes for an outline of the algorithm. Parameters ---------- m : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `m` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same form as that of `m`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : bool, optional Default normalization (False) is by ``(N - 1)``, where ``N`` is the number of observations given (unbiased estimate). If `bias` is True, then normalization is by ``N``. These values can be overridden by using the keyword ``ddof`` in numpy versions >= 1.5. ddof : int, optional If not ``None`` the default value implied by `bias` is overridden. Note that ``ddof=1`` will return the unbiased estimate, even if both `fweights` and `aweights` are specified, and ``ddof=0`` will return the simple average. See the notes for the details. The default value is ``None``. .. versionadded:: 1.5 fweights : array_like, int, optional 1-D array of integer frequency weights; the number of times each observation vector should be repeated. .. versionadded:: 1.10 aweights : array_like, optional 1-D array of observation vector weights. These relative weights are typically large for observations considered "important" and smaller for observations considered less "important". If ``ddof=0`` the array of weights can be used to assign probabilities to observation vectors. .. versionadded:: 1.10 dtype : data-type, optional Data-type of the result. By default, the return data-type will have at least `numpy.float64` precision. .. versionadded:: 1.20 Returns ------- out : ndarray The covariance matrix of the variables. See Also -------- corrcoef : Normalized covariance matrix Notes ----- Assume that the observations are in the columns of the observation array `m` and let ``f = fweights`` and ``a = aweights`` for brevity. The steps to compute the weighted covariance are as follows:: >>> m = np.arange(10, dtype=np.float64) >>> f = np.arange(10) 2 >>> a = np.arange(10) ** 2. >>> ddof = 1 >>> w = f * a >>> v1 = np.sum(w) >>> v2 = np.sum(w * a) >>> m -= np.sum(m * w, axis=None, keepdims=True) / v1 >>> cov = np.dot(m * w, m.T) * v1 / (v1*2 - ddof v2) Note that when ``a == 1``, the normalization factor ``v1 / (v1*2 - ddof v2)`` goes over to ``1 / (np.sum(f) - ddof)`` as it should. Examples -------- Consider two variables, :math:`x_0` and :math:`x_1`, which correlate perfectly, but in opposite directions: >>> x = np.array([[0, 2], [1, 1], [2, 0]]).T >>> x array([[0, 1, 2], [2, 1, 0]]) Note how :math:`x_0` increases while :math:`x_1` decreases. The covariance matrix shows this clearly: >>> np.cov(x) array([[ 1., -1.], [-1., 1.]]) Note that element :math:`C_{0,1}`, which shows the correlation between :math:`x_0` and :math:`x_1`, is negative. Further, note how `x` and `y` are combined: >>> x = [-2.1, -1, 4.3] >>> y = [3, 1.1, 0.12] >>> X = np.stack((x, y), axis=0) >>> np.cov(X) array([[11.71 , -4.286 ], # may vary [-4.286 , 2.144133]]) >>> np.cov(x, y) array([[11.71 , -4.286 ], # may vary [-4.286 , 2.144133]]) >>> np.cov(x) array(11.71) """ # Check inputs if ddof is not None and ddof != int(ddof): raise ValueError( "ddof must be integer") # Handles complex arrays too m = np.asarray(m) if m.ndim > 2: raise ValueError("m has more than 2 dimensions") if y is not None: y = np.asarray(y) if y.ndim > 2: raise ValueError("y has more than 2 dimensions") if dtype is None: if y is None: dtype = np.result_type(m, np.float64) else: dtype = np.result_type(m, y, np.float64) X = array(m, ndmin=2, dtype=dtype) if not rowvar and X.shape[0] != 1: X = X.T if X.shape[0] == 0: return np.array([]).reshape(0, 0) if y is not None: y = array(y, copy=False, ndmin=2, dtype=dtype) if not rowvar and y.shape[0] != 1: y = y.T X = np.concatenate((X, y), axis=0) if ddof is None: if bias == 0: ddof = 1 else: ddof = 0 # Get the product of frequencies and weights w = None if fweights is not None: fweights = np.asarray(fweights, dtype=float) if not np.all(fweights == np.around(fweights)): raise TypeError( "fweights must be integer") if fweights.ndim > 1: raise RuntimeError( "cannot handle multidimensional fweights") if fweights.shape[0] != X.shape[1]: raise RuntimeError( "incompatible numbers of samples and fweights") if any(fweights < 0): raise ValueError( "fweights cannot be negative") w = fweights if aweights is not None: aweights = np.asarray(aweights, dtype=float) if aweights.ndim > 1: raise RuntimeError( "cannot handle multidimensional aweights") if aweights.shape[0] != X.shape[1]: raise RuntimeError( "incompatible numbers of samples and aweights") if any(aweights < 0): raise ValueError( "aweights cannot be negative") if w is None: w = aweights else: w = aweights avg, w_sum = average(X, axis=1, weights=w, returned=True) w_sum = w_sum[0] # Determine the normalization if w is None: fact = X.shape[1] - ddof elif ddof == 0: fact = w_sum elif aweights is None: fact = w_sum - ddof else: fact = w_sum - ddofsum(waweights)/w_sum if fact <= 0: warnings.warn("Degrees of freedom <= 0 for slice", RuntimeWarning, stacklevel=2) fact = 0.0 X -= avg[:, None] if w is None: X_T = X.T else: X_T = (Xw).T c = dot(X, X_T.conj()) c = np.true_divide(1, fact) return c.squeeze() def _corrcoef_dispatcher(x, y=None, rowvar=None, bias=None, ddof=None, , dtype=None): return (x, y) @array_function_dispatch(_corrcoef_dispatcher) def corrcoef(x, y=None, rowvar=True, bias=np._NoValue, ddof=np._NoValue, , dtype=None): """ Return Pearson product-moment correlation coefficients. Please refer to the documentation for `cov` for more detail. The relationship between the correlation coefficient matrix, `R`, and the covariance matrix, `C`, is .. math:: R_{ij} = \\frac{ C_{ij} } { \\sqrt{ C_{ii} C_{jj} } } The values of `R` are between -1 and 1, inclusive. Parameters ---------- x : array_like A 1-D or 2-D array containing multiple variables and observations. Each row of `x` represents a variable, and each column a single observation of all those variables. Also see `rowvar` below. y : array_like, optional An additional set of variables and observations. `y` has the same shape as `x`. rowvar : bool, optional If `rowvar` is True (default), then each row represents a variable, with observations in the columns. Otherwise, the relationship is transposed: each column represents a variable, while the rows contain observations. bias : _NoValue, optional Has no effect, do not use. .. deprecated:: 1.10.0 ddof : _NoValue, optional Has no effect, do not use. .. deprecated:: 1.10.0 dtype : data-type, optional Data-type of the result. By default, the return data-type will have at least `numpy.float64` precision. .. versionadded:: 1.20 Returns ------- R : ndarray The correlation coefficient matrix of the variables. See Also -------- cov : Covariance matrix Notes ----- Due to floating point rounding the resulting array may not be Hermitian, the diagonal elements may not be 1, and the elements may not satisfy the inequality abs(a) <= 1. The real and imaginary parts are clipped to the interval [-1, 1] in an attempt to improve on that situation but is not much help in the complex case. This function accepts but discards arguments `bias` and `ddof`. This is for backwards compatibility with previous versions of this function. These arguments had no effect on the return values of the function and can be safely ignored in this and previous versions of numpy. Examples -------- In this example we generate two random arrays, ``xarr`` and ``yarr``, and compute the row-wise and column-wise Pearson correlation coefficients, ``R``. Since ``rowvar`` is true by default, we first find the row-wise Pearson correlation coefficients between the variables of ``xarr``. >>> import numpy as np >>> rng = np.random.default_rng(seed=42) >>> xarr = rng.random((3, 3)) >>> xarr array([[0.77395605, 0.43887844, 0.85859792], [0.69736803, 0.09417735, 0.97562235], [0.7611397 , 0.78606431, 0.12811363]]) >>> R1 = np.corrcoef(xarr) >>> R1 array([[ 1. , 0.99256089, -0.68080986], [ 0.99256089, 1. , -0.76492172], [-0.68080986, -0.76492172, 1. ]]) If we add another set of variables and observations ``yarr``, we can compute the row-wise Pearson correlation coefficients between the variables in ``xarr`` and ``yarr``. >>> yarr = rng.random((3, 3)) >>> yarr array([[0.45038594, 0.37079802, 0.92676499], [0.64386512, 0.82276161, 0.4434142 ], [0.22723872, 0.55458479, 0.06381726]]) >>> R2 = np.corrcoef(xarr, yarr) >>> R2 array([[ 1. , 0.99256089, -0.68080986, 0.75008178, -0.934284 , -0.99004057], [ 0.99256089, 1. , -0.76492172, 0.82502011, -0.97074098, -0.99981569], [-0.68080986, -0.76492172, 1. , -0.99507202, 0.89721355, 0.77714685], [ 0.75008178, 0.82502011, -0.99507202, 1. , -0.93657855, -0.83571711], [-0.934284 , -0.97074098, 0.89721355, -0.93657855, 1. , 0.97517215], [-0.99004057, -0.99981569, 0.77714685, -0.83571711, 0.97517215, 1. ]]) Finally if we use the option ``rowvar=False``, the columns are now being treated as the variables and we will find the column-wise Pearson correlation coefficients between variables in ``xarr`` and ``yarr``. >>> R3 = np.corrcoef(xarr, yarr, rowvar=False) >>> R3 array([[ 1. , 0.77598074, -0.47458546, -0.75078643, -0.9665554 , 0.22423734], [ 0.77598074, 1. , -0.92346708, -0.99923895, -0.58826587, -0.44069024], [-0.47458546, -0.92346708, 1. , 0.93773029, 0.23297648, 0.75137473], [-0.75078643, -0.99923895, 0.93773029, 1. , 0.55627469, 0.47536961], [-0.9665554 , -0.58826587, 0.23297648, 0.55627469, 1. , -0.46666491], [ 0.22423734, -0.44069024, 0.75137473, 0.47536961, -0.46666491, 1. ]]) """ if bias is not np._NoValue or ddof is not np._NoValue: # 2015-03-15, 1.10 warnings.warn('bias and ddof have no effect and are deprecated', DeprecationWarning, stacklevel=2) c = cov(x, y, rowvar, dtype=dtype) try: d = diag(c) except ValueError: # scalar covariance # nan if incorrect value (nan, inf, 0), 1 otherwise return c / c stddev = sqrt(d.real) c /= stddev[:, None] c /= stddev[None, :] # Clip real and imaginary parts to [-1, 1]. This does not guarantee # abs(a[i,j]) <= 1 for complex arrays, but is the best we can do without # excessive work. np.clip(c.real, -1, 1, out=c.real) if np.iscomplexobj(c): np.clip(c.imag, -1, 1, out=c.imag) return c @set_module('numpy') def blackman(M): """ Return the Blackman window. The Blackman window is a taper formed by using the first three terms of a summation of cosines. It was designed to have close to the minimal leakage possible. It is close to optimal, only slightly worse than a Kaiser window. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, hamming, hanning, kaiser Notes ----- The Blackman window is defined as .. math:: w(n) = 0.42 - 0.5 \\cos(2\\pi n/M) + 0.08 \\cos(4\\pi n/M) Most references to the Blackman window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means "removing the foot", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. It is known as a "near optimal" tapering function, almost as good (by some measures) as the kaiser window. References ---------- Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing. Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471. Examples -------- >>> import matplotlib.pyplot as plt >>> np.blackman(12) array([-1.38777878e-17, 3.26064346e-02, 1.59903635e-01, # may vary 4.14397981e-01, 7.36045180e-01, 9.67046769e-01, 9.67046769e-01, 7.36045180e-01, 4.14397981e-01, 1.59903635e-01, 3.26064346e-02, -1.38777878e-17]) Plot the window and the frequency response: >>> from numpy.fft import fft, fftshift >>> window = np.blackman(51) >>> plt.plot(window) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Blackman window") Text(0.5, 1.0, 'Blackman window') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("Sample") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Frequency response of Blackman window") Text(0.5, 1.0, 'Frequency response of Blackman window') >>> plt.ylabel("Magnitude [dB]") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel("Normalized frequency [cycles per sample]") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> _ = plt.axis('tight') >>> plt.show() """ # Ensures at least float64 via 0.0. M should be an integer, but conversion # to double is safe for a range. values = np.array([0.0, M]) M = values[1] if M < 1: return array([], dtype=values.dtype) if M == 1: return ones(1, dtype=values.dtype) n = arange(1-M, M, 2) return 0.42 + 0.5cos(pin/(M-1)) + 0.08cos(2.0pin/(M-1)) @set_module('numpy') def bartlett(M): """ Return the Bartlett window. The Bartlett window is very similar to a triangular window, except that the end points are at zero. It is often used in signal processing for tapering a signal, without generating too much ripple in the frequency domain. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : array The triangular window, with the maximum value normalized to one (the value one appears only if the number of samples is odd), with the first and last samples equal to zero. See Also -------- blackman, hamming, hanning, kaiser Notes ----- The Bartlett window is defined as .. math:: w(n) = \\frac{2}{M-1} \\left( \\frac{M-1}{2} - \\left\|n - \\frac{M-1}{2}\\right\| \\right) Most references to the Bartlett window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. Note that convolution with this window produces linear interpolation. It is also known as an apodization (which means "removing the foot", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. The Fourier transform of the Bartlett window is the product of two sinc functions. Note the excellent discussion in Kanasewich [2]_. References ---------- .. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra", Biometrika 37, 1-16, 1950. .. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics", The University of Alberta Press, 1975, pp. 109-110. .. [3] A.V. Oppenheim and R.W. Schafer, "Discrete-Time Signal Processing", Prentice-Hall, 1999, pp. 468-471. .. [4] Wikipedia, "Window function", https://en.wikipedia.org/wiki/Window_function .. [5] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, "Numerical Recipes", Cambridge University Press, 1986, page 429. Examples -------- >>> import matplotlib.pyplot as plt >>> np.bartlett(12) array([ 0. , 0.18181818, 0.36363636, 0.54545455, 0.72727273, # may vary 0.90909091, 0.90909091, 0.72727273, 0.54545455, 0.36363636, 0.18181818, 0. ]) Plot the window and its frequency response (requires SciPy and matplotlib): >>> from numpy.fft import fft, fftshift >>> window = np.bartlett(51) >>> plt.plot(window) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Bartlett window") Text(0.5, 1.0, 'Bartlett window') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("Sample") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Frequency response of Bartlett window") Text(0.5, 1.0, 'Frequency response of Bartlett window') >>> plt.ylabel("Magnitude [dB]") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel("Normalized frequency [cycles per sample]") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> _ = plt.axis('tight') >>> plt.show() """ # Ensures at least float64 via 0.0. M should be an integer, but conversion # to double is safe for a range. values = np.array([0.0, M]) M = values[1] if M < 1: return array([], dtype=values.dtype) if M == 1: return ones(1, dtype=values.dtype) n = arange(1-M, M, 2) return where(less_equal(n, 0), 1 + n/(M-1), 1 - n/(M-1)) @set_module('numpy') def hanning(M): """ Return the Hanning window. The Hanning window is a taper formed by using a weighted cosine. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray, shape(M,) The window, with the maximum value normalized to one (the value one appears only if `M` is odd). See Also -------- bartlett, blackman, hamming, kaiser Notes ----- The Hanning window is defined as .. math:: w(n) = 0.5 - 0.5\\cos\\left(\\frac{2\\pi{n}}{M-1}\\right) \\qquad 0 \\leq n \\leq M-1 The Hanning was named for Julius von Hann, an Austrian meteorologist. It is also known as the Cosine Bell. Some authors prefer that it be called a Hann window, to help avoid confusion with the very similar Hamming window. Most references to the Hanning window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means "removing the foot", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. .. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics", The University of Alberta Press, 1975, pp. 106-108. .. [3] Wikipedia, "Window function", https://en.wikipedia.org/wiki/Window_function .. [4] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, "Numerical Recipes", Cambridge University Press, 1986, page 425. Examples -------- >>> np.hanning(12) array([0. , 0.07937323, 0.29229249, 0.57115742, 0.82743037, 0.97974649, 0.97974649, 0.82743037, 0.57115742, 0.29229249, 0.07937323, 0. ]) Plot the window and its frequency response: >>> import matplotlib.pyplot as plt >>> from numpy.fft import fft, fftshift >>> window = np.hanning(51) >>> plt.plot(window) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Hann window") Text(0.5, 1.0, 'Hann window') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("Sample") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> with np.errstate(divide='ignore', invalid='ignore'): ... response = 20 * np.log10(mag) ... >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Frequency response of the Hann window") Text(0.5, 1.0, 'Frequency response of the Hann window') >>> plt.ylabel("Magnitude [dB]") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel("Normalized frequency [cycles per sample]") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') ... >>> plt.show() """ # Ensures at least float64 via 0.0. M should be an integer, but conversion # to double is safe for a range. values = np.array([0.0, M]) M = values[1] if M < 1: return array([], dtype=values.dtype) if M == 1: return ones(1, dtype=values.dtype) n = arange(1-M, M, 2) return 0.5 + 0.5cos(pin/(M-1)) @set_module('numpy') def hamming(M): """ Return the Hamming window. The Hamming window is a taper formed by using a weighted cosine. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. Returns ------- out : ndarray The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, blackman, hanning, kaiser Notes ----- The Hamming window is defined as .. math:: w(n) = 0.54 - 0.46\\cos\\left(\\frac{2\\pi{n}}{M-1}\\right) \\qquad 0 \\leq n \\leq M-1 The Hamming was named for R. W. Hamming, an associate of J. W. Tukey and is described in Blackman and Tukey. It was recommended for smoothing the truncated autocovariance function in the time domain. Most references to the Hamming window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means "removing the foot", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra, Dover Publications, New York. .. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics", The University of Alberta Press, 1975, pp. 109-110. .. [3] Wikipedia, "Window function", https://en.wikipedia.org/wiki/Window_function .. [4] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, "Numerical Recipes", Cambridge University Press, 1986, page 425. Examples -------- >>> np.hamming(12) array([ 0.08 , 0.15302337, 0.34890909, 0.60546483, 0.84123594, # may vary 0.98136677, 0.98136677, 0.84123594, 0.60546483, 0.34890909, 0.15302337, 0.08 ]) Plot the window and the frequency response: >>> import matplotlib.pyplot as plt >>> from numpy.fft import fft, fftshift >>> window = np.hamming(51) >>> plt.plot(window) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Hamming window") Text(0.5, 1.0, 'Hamming window') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("Sample") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> response = 20 * np.log10(mag) >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Frequency response of Hamming window") Text(0.5, 1.0, 'Frequency response of Hamming window') >>> plt.ylabel("Magnitude [dB]") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel("Normalized frequency [cycles per sample]") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') ... >>> plt.show() """ # Ensures at least float64 via 0.0. M should be an integer, but conversion # to double is safe for a range. values = np.array([0.0, M]) M = values[1] if M < 1: return array([], dtype=values.dtype) if M == 1: return ones(1, dtype=values.dtype) n = arange(1-M, M, 2) return 0.54 + 0.46cos(pin/(M-1)) ## Code from cephes for i0 _i0A = [ -4.41534164647933937950E-18, 3.33079451882223809783E-17, -2.43127984654795469359E-16, 1.71539128555513303061E-15, -1.16853328779934516808E-14, 7.67618549860493561688E-14, -4.85644678311192946090E-13, 2.95505266312963983461E-12, -1.72682629144155570723E-11, 9.67580903537323691224E-11, -5.18979560163526290666E-10, 2.65982372468238665035E-9, -1.30002500998624804212E-8, 6.04699502254191894932E-8, -2.67079385394061173391E-7, 1.11738753912010371815E-6, -4.41673835845875056359E-6, 1.64484480707288970893E-5, -5.75419501008210370398E-5, 1.88502885095841655729E-4, -5.76375574538582365885E-4, 1.63947561694133579842E-3, -4.32430999505057594430E-3, 1.05464603945949983183E-2, -2.37374148058994688156E-2, 4.93052842396707084878E-2, -9.49010970480476444210E-2, 1.71620901522208775349E-1, -3.04682672343198398683E-1, 6.76795274409476084995E-1 ] _i0B = [ -7.23318048787475395456E-18, -4.83050448594418207126E-18, 4.46562142029675999901E-17, 3.46122286769746109310E-17, -2.82762398051658348494E-16, -3.42548561967721913462E-16, 1.77256013305652638360E-15, 3.81168066935262242075E-15, -9.55484669882830764870E-15, -4.15056934728722208663E-14, 1.54008621752140982691E-14, 3.85277838274214270114E-13, 7.18012445138366623367E-13, -1.79417853150680611778E-12, -1.32158118404477131188E-11, -3.14991652796324136454E-11, 1.18891471078464383424E-11, 4.94060238822496958910E-10, 3.39623202570838634515E-9, 2.26666899049817806459E-8, 2.04891858946906374183E-7, 2.89137052083475648297E-6, 6.88975834691682398426E-5, 3.36911647825569408990E-3, 8.04490411014108831608E-1 ] def _chbevl(x, vals): b0 = vals[0] b1 = 0.0 for i in range(1, len(vals)): b2 = b1 b1 = b0 b0 = xb1 - b2 + vals[i] return 0.5(b0 - b2) def _i0_1(x): return exp(x) * _chbevl(x/2.0-2, _i0A) def _i0_2(x): return exp(x) * _chbevl(32.0/x - 2.0, _i0B) / sqrt(x) def _i0_dispatcher(x): return (x,) @array_function_dispatch(_i0_dispatcher) def i0(x): """ Modified Bessel function of the first kind, order 0. Usually denoted :math:`I_0`. Parameters ---------- x : array_like of float Argument of the Bessel function. Returns ------- out : ndarray, shape = x.shape, dtype = float The modified Bessel function evaluated at each of the elements of `x`. See Also -------- scipy.special.i0, scipy.special.iv, scipy.special.ive Notes ----- The scipy implementation is recommended over this function: it is a proper ufunc written in C, and more than an order of magnitude faster. We use the algorithm published by Clenshaw [1]_ and referenced by Abramowitz and Stegun [2]_, for which the function domain is partitioned into the two intervals [0,8] and (8,inf), and Chebyshev polynomial expansions are employed in each interval. Relative error on the domain [0,30] using IEEE arithmetic is documented [3]_ as having a peak of 5.8e-16 with an rms of 1.4e-16 (n = 30000). References ---------- .. [1] C. W. Clenshaw, "Chebyshev series for mathematical functions", in National Physical Laboratory Mathematical Tables, vol. 5, London: Her Majesty's Stationery Office, 1962. .. [2] M. Abramowitz and I. A. Stegun, Handbook of Mathematical Functions, 10th printing, New York: Dover, 1964, pp. 379. https://personal.math.ubc.ca/~cbm/aands/page_379.htm .. [3] https://metacpan.org/pod/distribution/Math-Cephes/lib/Math/Cephes.pod#i0:-Modified-Bessel-function-of-order-zero Examples -------- >>> np.i0(0.) array(1.0) >>> np.i0([0, 1, 2, 3]) array([1. , 1.26606588, 2.2795853 , 4.88079259]) """ x = np.asanyarray(x) if x.dtype.kind == 'c': raise TypeError("i0 not supported for complex values") if x.dtype.kind != 'f': x = x.astype(float) x = np.abs(x) return piecewise(x, [x <= 8.0], [_i0_1, _i0_2]) ## End of cephes code for i0 @set_module('numpy') def kaiser(M, beta): """ Return the Kaiser window. The Kaiser window is a taper formed by using a Bessel function. Parameters ---------- M : int Number of points in the output window. If zero or less, an empty array is returned. beta : float Shape parameter for window. Returns ------- out : array The window, with the maximum value normalized to one (the value one appears only if the number of samples is odd). See Also -------- bartlett, blackman, hamming, hanning Notes ----- The Kaiser window is defined as .. math:: w(n) = I_0\\left( \\beta \\sqrt{1-\\frac{4n^2}{(M-1)^2}} \\right)/I_0(\\beta) with .. math:: \\quad -\\frac{M-1}{2} \\leq n \\leq \\frac{M-1}{2}, where :math:`I_0` is the modified zeroth-order Bessel function. The Kaiser was named for Jim Kaiser, who discovered a simple approximation to the DPSS window based on Bessel functions. The Kaiser window is a very good approximation to the Digital Prolate Spheroidal Sequence, or Slepian window, which is the transform which maximizes the energy in the main lobe of the window relative to total energy. The Kaiser can approximate many other windows by varying the beta parameter. ==== ======================= beta Window shape ==== ======================= 0 Rectangular 5 Similar to a Hamming 6 Similar to a Hanning 8.6 Similar to a Blackman ==== ======================= A beta value of 14 is probably a good starting point. Note that as beta gets large, the window narrows, and so the number of samples needs to be large enough to sample the increasingly narrow spike, otherwise NaNs will get returned. Most references to the Kaiser window come from the signal processing literature, where it is used as one of many windowing functions for smoothing values. It is also known as an apodization (which means "removing the foot", i.e. smoothing discontinuities at the beginning and end of the sampled signal) or tapering function. References ---------- .. [1] J. F. Kaiser, "Digital Filters" - Ch 7 in "Systems analysis by digital computer", Editors: F.F. Kuo and J.F. Kaiser, p 218-285. John Wiley and Sons, New York, (1966). .. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics", The University of Alberta Press, 1975, pp. 177-178. .. [3] Wikipedia, "Window function", https://en.wikipedia.org/wiki/Window_function Examples -------- >>> import matplotlib.pyplot as plt >>> np.kaiser(12, 14) array([7.72686684e-06, 3.46009194e-03, 4.65200189e-02, # may vary 2.29737120e-01, 5.99885316e-01, 9.45674898e-01, 9.45674898e-01, 5.99885316e-01, 2.29737120e-01, 4.65200189e-02, 3.46009194e-03, 7.72686684e-06]) Plot the window and the frequency response: >>> from numpy.fft import fft, fftshift >>> window = np.kaiser(51, 14) >>> plt.plot(window) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Kaiser window") Text(0.5, 1.0, 'Kaiser window') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("Sample") Text(0.5, 0, 'Sample') >>> plt.show() >>> plt.figure() <Figure size 640x480 with 0 Axes> >>> A = fft(window, 2048) / 25.5 >>> mag = np.abs(fftshift(A)) >>> freq = np.linspace(-0.5, 0.5, len(A)) >>> response = 20 * np.log10(mag) >>> response = np.clip(response, -100, 100) >>> plt.plot(freq, response) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Frequency response of Kaiser window") Text(0.5, 1.0, 'Frequency response of Kaiser window') >>> plt.ylabel("Magnitude [dB]") Text(0, 0.5, 'Magnitude [dB]') >>> plt.xlabel("Normalized frequency [cycles per sample]") Text(0.5, 0, 'Normalized frequency [cycles per sample]') >>> plt.axis('tight') (-0.5, 0.5, -100.0, ...) # may vary >>> plt.show() """ # Ensures at least float64 via 0.0. M should be an integer, but conversion # to double is safe for a range. (Simplified result_type with 0.0 # strongly typed. result-type is not/less order sensitive, but that mainly # matters for integers anyway.) values = np.array([0.0, M, beta]) M = values[1] beta = values[2] if M == 1: return np.ones(1, dtype=values.dtype) n = arange(0, M) alpha = (M-1)/2.0 return i0(beta * sqrt(1-((n-alpha)/alpha)*2.0))/i0(beta) def _sinc_dispatcher(x): return (x,) @array_function_dispatch(_sinc_dispatcher) def sinc(x): r""" Return the normalized sinc function. The sinc function is equal to :math:`\sin(\pi x)/(\pi x)` for any argument :math:`x\ne 0`. ``sinc(0)`` takes the limit value 1, making ``sinc`` not only everywhere continuous but also infinitely differentiable. .. note:: Note the normalization factor of ``pi`` used in the definition. This is the most commonly used definition in signal processing. Use ``sinc(x / np.pi)`` to obtain the unnormalized sinc function :math:`\sin(x)/x` that is more common in mathematics. Parameters ---------- x : ndarray Array (possibly multi-dimensional) of values for which to calculate ``sinc(x)``. Returns ------- out : ndarray ``sinc(x)``, which has the same shape as the input. Notes ----- The name sinc is short for "sine cardinal" or "sinus cardinalis". The sinc function is used in various signal processing applications, including in anti-aliasing, in the construction of a Lanczos resampling filter, and in interpolation. For bandlimited interpolation of discrete-time signals, the ideal interpolation kernel is proportional to the sinc function. References ---------- .. [1] Weisstein, Eric W. "Sinc Function." From MathWorld--A Wolfram Web Resource. http://mathworld.wolfram.com/SincFunction.html .. [2] Wikipedia, "Sinc function", https://en.wikipedia.org/wiki/Sinc_function Examples -------- >>> import matplotlib.pyplot as plt >>> x = np.linspace(-4, 4, 41) >>> np.sinc(x) array([-3.89804309e-17, -4.92362781e-02, -8.40918587e-02, # may vary -8.90384387e-02, -5.84680802e-02, 3.89804309e-17, 6.68206631e-02, 1.16434881e-01, 1.26137788e-01, 8.50444803e-02, -3.89804309e-17, -1.03943254e-01, -1.89206682e-01, -2.16236208e-01, -1.55914881e-01, 3.89804309e-17, 2.33872321e-01, 5.04551152e-01, 7.56826729e-01, 9.35489284e-01, 1.00000000e+00, 9.35489284e-01, 7.56826729e-01, 5.04551152e-01, 2.33872321e-01, 3.89804309e-17, -1.55914881e-01, -2.16236208e-01, -1.89206682e-01, -1.03943254e-01, -3.89804309e-17, 8.50444803e-02, 1.26137788e-01, 1.16434881e-01, 6.68206631e-02, 3.89804309e-17, -5.84680802e-02, -8.90384387e-02, -8.40918587e-02, -4.92362781e-02, -3.89804309e-17]) >>> plt.plot(x, np.sinc(x)) [<matplotlib.lines.Line2D object at 0x...>] >>> plt.title("Sinc Function") Text(0.5, 1.0, 'Sinc Function') >>> plt.ylabel("Amplitude") Text(0, 0.5, 'Amplitude') >>> plt.xlabel("X") Text(0.5, 0, 'X') >>> plt.show() """ x = np.asanyarray(x) y = pi where(x == 0, 1.0e-20, x) return sin(y)/y def _msort_dispatcher(a): return (a,) @array_function_dispatch(_msort_dispatcher) def msort(a): """ Return a copy of an array sorted along the first axis. .. deprecated:: 1.24 msort is deprecated, use ``np.sort(a, axis=0)`` instead. Parameters ---------- a : array_like Array to be sorted. Returns ------- sorted_array : ndarray Array of the same type and shape as `a`. See Also -------- sort Notes ----- ``np.msort(a)`` is equivalent to ``np.sort(a, axis=0)``. Examples -------- >>> a = np.array([[1, 4], [3, 1]]) >>> np.msort(a) # sort along the first axis array([[1, 1], [3, 4]]) """ # 2022-10-20 1.24 warnings.warn( "msort is deprecated, use np.sort(a, axis=0) instead", DeprecationWarning, stacklevel=2, ) b = array(a, subok=True, copy=True) b.sort(0) return b def _ureduce(a, func, keepdims=False, kwargs): """ Internal Function. Call `func` with `a` as first argument swapping the axes to use extended axis on functions that don't support it natively. Returns result and a.shape with axis dims set to 1. Parameters ---------- a : array_like Input array or object that can be converted to an array. func : callable Reduction function capable of receiving a single axis argument. It is called with `a` as first argument followed by `kwargs`. kwargs : keyword arguments additional keyword arguments to pass to `func`. Returns ------- result : tuple Result of func(a, kwargs) and a.shape with axis dims set to 1 which can be used to reshape the result to the same shape a ufunc with keepdims=True would produce. """ a = np.asanyarray(a) axis = kwargs.get('axis', None) out = kwargs.get('out', None) if keepdims is np._NoValue: keepdims = False nd = a.ndim if axis is not None: axis = _nx.normalize_axis_tuple(axis, nd) if keepdims: if out is not None: index_out = tuple( 0 if i in axis else slice(None) for i in range(nd)) kwargs['out'] = out[(Ellipsis, ) + index_out] if len(axis) == 1: kwargs['axis'] = axis[0] else: keep = set(range(nd)) - set(axis) nkeep = len(keep) # swap axis that should not be reduced to front for i, s in enumerate(sorted(keep)): a = a.swapaxes(i, s) # merge reduced axis a = a.reshape(a.shape[:nkeep] + (-1,)) kwargs['axis'] = -1 else: if keepdims: if out is not None: index_out = (0, ) * nd kwargs['out'] = out[(Ellipsis, ) + index_out] r = func(a, *kwargs) if out is not None: return out if keepdims: if axis is None: index_r = (np.newaxis, ) nd else: index_r = tuple( np.newaxis if i in axis else slice(None) for i in range(nd)) r = r[(Ellipsis, ) + index_r] return r def _median_dispatcher( a, axis=None, out=None, overwrite_input=None, keepdims=None): return (a, out) @array_function_dispatch(_median_dispatcher) def median(a, axis=None, out=None, overwrite_input=False, keepdims=False): """ Compute the median along the specified axis. Returns the median of the array elements. Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : {int, sequence of int, None}, optional Axis or axes along which the medians are computed. The default is to compute the median along a flattened version of the array. A sequence of axes is supported since version 1.9.0. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow use of memory of input array `a` for calculations. The input array will be modified by the call to `median`. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. If `overwrite_input` is ``True`` and `a` is not already an `ndarray`, an error will be raised. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `arr`. .. versionadded:: 1.9.0 Returns ------- median : ndarray A new array holding the result. If the input contains integers or floats smaller than ``float64``, then the output data-type is ``np.float64``. Otherwise, the data-type of the output is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean, percentile Notes ----- Given a vector ``V`` of length ``N``, the median of ``V`` is the middle value of a sorted copy of ``V``, ``V_sorted`` - i e., ``V_sorted[(N-1)/2]``, when ``N`` is odd, and the average of the two middle values of ``V_sorted`` when ``N`` is even. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.median(a) 3.5 >>> np.median(a, axis=0) array([6.5, 4.5, 2.5]) >>> np.median(a, axis=1) array([7., 2.]) >>> m = np.median(a, axis=0) >>> out = np.zeros_like(m) >>> np.median(a, axis=0, out=m) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.median(b, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) >>> b = a.copy() >>> np.median(b, axis=None, overwrite_input=True) 3.5 >>> assert not np.all(a==b) """ return _ureduce(a, func=_median, keepdims=keepdims, axis=axis, out=out, overwrite_input=overwrite_input) def _median(a, axis=None, out=None, overwrite_input=False): # can't be reasonably be implemented in terms of percentile as we have to # call mean to not break astropy a = np.asanyarray(a) # Set the partition indexes if axis is None: sz = a.size else: sz = a.shape[axis] if sz % 2 == 0: szh = sz // 2 kth = [szh - 1, szh] else: kth = [(sz - 1) // 2] # We have to check for NaNs (as of writing 'M' doesn't actually work). supports_nans = np.issubdtype(a.dtype, np.inexact) or a.dtype.kind in 'Mm' if supports_nans: kth.append(-1) if overwrite_input: if axis is None: part = a.ravel() part.partition(kth) else: a.partition(kth, axis=axis) part = a else: part = partition(a, kth, axis=axis) if part.shape == (): # make 0-D arrays work return part.item() if axis is None: axis = 0 indexer = [slice(None)] * part.ndim index = part.shape[axis] // 2 if part.shape[axis] % 2 == 1: # index with slice to allow mean (below) to work indexer[axis] = slice(index, index+1) else: indexer[axis] = slice(index-1, index+1) indexer = tuple(indexer) # Use mean in both odd and even case to coerce data type, # using out array if needed. rout = mean(part[indexer], axis=axis, out=out) if supports_nans and sz > 0: # If nans are possible, warn and replace by nans like mean would. rout = np.lib.utils._median_nancheck(part, rout, axis) return rout def _percentile_dispatcher(a, q, axis=None, out=None, overwrite_input=None, method=None, keepdims=None, , interpolation=None): return (a, q, out) @array_function_dispatch(_percentile_dispatcher) def percentile(a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=False, , interpolation=None): """ Compute the q-th percentile of the data along the specified axis. Returns the q-th percentile(s) of the array elements. Parameters ---------- a : array_like of real numbers Input array or object that can be converted to an array. q : array_like of float Percentage or sequence of percentages for the percentiles to compute. Values must be between 0 and 100 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the percentiles are computed. The default is to compute the percentile(s) along a flattened version of the array. .. versionchanged:: 1.9.0 A tuple of axes is supported out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. method : str, optional This parameter specifies the method to use for estimating the percentile. There are many different methods, some unique to NumPy. See the notes for explanation. The options sorted by their R type as summarized in the H&F paper [1]_ are: 1. 'inverted_cdf' 2. 'averaged_inverted_cdf' 3. 'closest_observation' 4. 'interpolated_inverted_cdf' 5. 'hazen' 6. 'weibull' 7. 'linear' (default) 8. 'median_unbiased' 9. 'normal_unbiased' The first three methods are discontinuous. NumPy further defines the following discontinuous variations of the default 'linear' (7.) option: * 'lower' * 'higher', * 'midpoint' * 'nearest' .. versionchanged:: 1.22.0 This argument was previously called "interpolation" and only offered the "linear" default and last four options. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array `a`. .. versionadded:: 1.9.0 interpolation : str, optional Deprecated name for the method keyword argument. .. deprecated:: 1.22.0 Returns ------- percentile : scalar or ndarray If `q` is a single percentile and `axis=None`, then the result is a scalar. If multiple percentiles are given, first axis of the result corresponds to the percentiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean median : equivalent to ``percentile(..., 50)`` nanpercentile quantile : equivalent to percentile, except q in the range [0, 1]. Notes ----- Given a vector ``V`` of length ``n``, the q-th percentile of ``V`` is the value ``q/100`` of the way from the minimum to the maximum in a sorted copy of ``V``. The values and distances of the two nearest neighbors as well as the `method` parameter will determine the percentile if the normalized ranking does not match the location of ``q`` exactly. This function is the same as the median if ``q=50``, the same as the minimum if ``q=0`` and the same as the maximum if ``q=100``. The optional `method` parameter specifies the method to use when the desired percentile lies between two indexes ``i`` and ``j = i + 1``. In that case, we first determine ``i + g``, a virtual index that lies between ``i`` and ``j``, where ``i`` is the floor and ``g`` is the fractional part of the index. The final result is, then, an interpolation of ``a[i]`` and ``a[j]`` based on ``g``. During the computation of ``g``, ``i`` and ``j`` are modified using correction constants ``alpha`` and ``beta`` whose choices depend on the ``method`` used. Finally, note that since Python uses 0-based indexing, the code subtracts another 1 from the index internally. The following formula determines the virtual index ``i + g``, the location of the percentile in the sorted sample: .. math:: i + g = (q / 100) * ( n - alpha - beta + 1 ) + alpha The different methods then work as follows inverted_cdf: method 1 of H&F [1]_. This method gives discontinuous results: * if g > 0 ; then take j * if g = 0 ; then take i averaged_inverted_cdf: method 2 of H&F [1]_. This method give discontinuous results: * if g > 0 ; then take j * if g = 0 ; then average between bounds closest_observation: method 3 of H&F [1]_. This method give discontinuous results: * if g > 0 ; then take j * if g = 0 and index is odd ; then take j * if g = 0 and index is even ; then take i interpolated_inverted_cdf: method 4 of H&F [1]_. This method give continuous results using: * alpha = 0 * beta = 1 hazen: method 5 of H&F [1]_. This method give continuous results using: * alpha = 1/2 * beta = 1/2 weibull: method 6 of H&F [1]_. This method give continuous results using: * alpha = 0 * beta = 0 linear: method 7 of H&F [1]_. This method give continuous results using: * alpha = 1 * beta = 1 median_unbiased: method 8 of H&F [1]_. This method is probably the best method if the sample distribution function is unknown (see reference). This method give continuous results using: * alpha = 1/3 * beta = 1/3 normal_unbiased: method 9 of H&F [1]_. This method is probably the best method if the sample distribution function is known to be normal. This method give continuous results using: * alpha = 3/8 * beta = 3/8 lower: NumPy method kept for backwards compatibility. Takes ``i`` as the interpolation point. higher: NumPy method kept for backwards compatibility. Takes ``j`` as the interpolation point. nearest: NumPy method kept for backwards compatibility. Takes ``i`` or ``j``, whichever is nearest. midpoint: NumPy method kept for backwards compatibility. Uses ``(i + j) / 2``. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.percentile(a, 50) 3.5 >>> np.percentile(a, 50, axis=0) array([6.5, 4.5, 2.5]) >>> np.percentile(a, 50, axis=1) array([7., 2.]) >>> np.percentile(a, 50, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.percentile(a, 50, axis=0) >>> out = np.zeros_like(m) >>> np.percentile(a, 50, axis=0, out=out) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.percentile(b, 50, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a == b) The different methods can be visualized graphically: .. plot:: import matplotlib.pyplot as plt a = np.arange(4) p = np.linspace(0, 100, 6001) ax = plt.gca() lines = [ ('linear', '-', 'C0'), ('inverted_cdf', ':', 'C1'), # Almost the same as `inverted_cdf`: ('averaged_inverted_cdf', '-.', 'C1'), ('closest_observation', ':', 'C2'), ('interpolated_inverted_cdf', '--', 'C1'), ('hazen', '--', 'C3'), ('weibull', '-.', 'C4'), ('median_unbiased', '--', 'C5'), ('normal_unbiased', '-.', 'C6'), ] for method, style, color in lines: ax.plot( p, np.percentile(a, p, method=method), label=method, linestyle=style, color=color) ax.set( title='Percentiles for different methods and data: ' + str(a), xlabel='Percentile', ylabel='Estimated percentile value', yticks=a) ax.legend(bbox_to_anchor=(1.03, 1)) plt.tight_layout() plt.show() References ---------- .. [1] R. J. Hyndman and Y. Fan, "Sample quantiles in statistical packages," The American Statistician, 50(4), pp. 361-365, 1996 """ if interpolation is not None: method = _check_interpolation_as_method( method, interpolation, "percentile") a = np.asanyarray(a) if a.dtype.kind == "c": raise TypeError("a must be an array of real numbers") q = np.true_divide(q, 100) q = asanyarray(q) # undo any decay that the ufunc performed (see gh-13105) if not _quantile_is_valid(q): raise ValueError("Percentiles must be in the range [0, 100]") return _quantile_unchecked( a, q, axis, out, overwrite_input, method, keepdims) def _quantile_dispatcher(a, q, axis=None, out=None, overwrite_input=None, method=None, keepdims=None, , interpolation=None): return (a, q, out) @array_function_dispatch(_quantile_dispatcher) def quantile(a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=False, , interpolation=None): """ Compute the q-th quantile of the data along the specified axis. .. versionadded:: 1.15.0 Parameters ---------- a : array_like of real numbers Input array or object that can be converted to an array. q : array_like of float Probability or sequence of probabilities for the quantiles to compute. Values must be between 0 and 1 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the quantiles are computed. The default is to compute the quantile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. method : str, optional This parameter specifies the method to use for estimating the quantile. There are many different methods, some unique to NumPy. See the notes for explanation. The options sorted by their R type as summarized in the H&F paper [1]_ are: 1. 'inverted_cdf' 2. 'averaged_inverted_cdf' 3. 'closest_observation' 4. 'interpolated_inverted_cdf' 5. 'hazen' 6. 'weibull' 7. 'linear' (default) 8. 'median_unbiased' 9. 'normal_unbiased' The first three methods are discontinuous. NumPy further defines the following discontinuous variations of the default 'linear' (7.) option: * 'lower' * 'higher', * 'midpoint' * 'nearest' .. versionchanged:: 1.22.0 This argument was previously called "interpolation" and only offered the "linear" default and last four options. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array `a`. interpolation : str, optional Deprecated name for the method keyword argument. .. deprecated:: 1.22.0 Returns ------- quantile : scalar or ndarray If `q` is a single probability and `axis=None`, then the result is a scalar. If multiple probabilies levels are given, first axis of the result corresponds to the quantiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean percentile : equivalent to quantile, but with q in the range [0, 100]. median : equivalent to ``quantile(..., 0.5)`` nanquantile Notes ----- Given a vector ``V`` of length ``n``, the q-th quantile of ``V`` is the value ``q`` of the way from the minimum to the maximum in a sorted copy of ``V``. The values and distances of the two nearest neighbors as well as the `method` parameter will determine the quantile if the normalized ranking does not match the location of ``q`` exactly. This function is the same as the median if ``q=0.5``, the same as the minimum if ``q=0.0`` and the same as the maximum if ``q=1.0``. The optional `method` parameter specifies the method to use when the desired quantile lies between two indexes ``i`` and ``j = i + 1``. In that case, we first determine ``i + g``, a virtual index that lies between ``i`` and ``j``, where ``i`` is the floor and ``g`` is the fractional part of the index. The final result is, then, an interpolation of ``a[i]`` and ``a[j]`` based on ``g``. During the computation of ``g``, ``i`` and ``j`` are modified using correction constants ``alpha`` and ``beta`` whose choices depend on the ``method`` used. Finally, note that since Python uses 0-based indexing, the code subtracts another 1 from the index internally. The following formula determines the virtual index ``i + g``, the location of the quantile in the sorted sample: .. math:: i + g = q * ( n - alpha - beta + 1 ) + alpha The different methods then work as follows inverted_cdf: method 1 of H&F [1]_. This method gives discontinuous results: * if g > 0 ; then take j * if g = 0 ; then take i averaged_inverted_cdf: method 2 of H&F [1]_. This method gives discontinuous results: * if g > 0 ; then take j * if g = 0 ; then average between bounds closest_observation: method 3 of H&F [1]_. This method gives discontinuous results: * if g > 0 ; then take j * if g = 0 and index is odd ; then take j * if g = 0 and index is even ; then take i interpolated_inverted_cdf: method 4 of H&F [1]_. This method gives continuous results using: * alpha = 0 * beta = 1 hazen: method 5 of H&F [1]_. This method gives continuous results using: * alpha = 1/2 * beta = 1/2 weibull: method 6 of H&F [1]_. This method gives continuous results using: * alpha = 0 * beta = 0 linear: method 7 of H&F [1]_. This method gives continuous results using: * alpha = 1 * beta = 1 median_unbiased: method 8 of H&F [1]_. This method is probably the best method if the sample distribution function is unknown (see reference). This method gives continuous results using: * alpha = 1/3 * beta = 1/3 normal_unbiased: method 9 of H&F [1]_. This method is probably the best method if the sample distribution function is known to be normal. This method gives continuous results using: * alpha = 3/8 * beta = 3/8 lower: NumPy method kept for backwards compatibility. Takes ``i`` as the interpolation point. higher: NumPy method kept for backwards compatibility. Takes ``j`` as the interpolation point. nearest: NumPy method kept for backwards compatibility. Takes ``i`` or ``j``, whichever is nearest. midpoint: NumPy method kept for backwards compatibility. Uses ``(i + j) / 2``. Examples -------- >>> a = np.array([[10, 7, 4], [3, 2, 1]]) >>> a array([[10, 7, 4], [ 3, 2, 1]]) >>> np.quantile(a, 0.5) 3.5 >>> np.quantile(a, 0.5, axis=0) array([6.5, 4.5, 2.5]) >>> np.quantile(a, 0.5, axis=1) array([7., 2.]) >>> np.quantile(a, 0.5, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.quantile(a, 0.5, axis=0) >>> out = np.zeros_like(m) >>> np.quantile(a, 0.5, axis=0, out=out) array([6.5, 4.5, 2.5]) >>> m array([6.5, 4.5, 2.5]) >>> b = a.copy() >>> np.quantile(b, 0.5, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a == b) See also `numpy.percentile` for a visualization of most methods. References ---------- .. [1] R. J. Hyndman and Y. Fan, "Sample quantiles in statistical packages," The American Statistician, 50(4), pp. 361-365, 1996 """ if interpolation is not None: method = _check_interpolation_as_method( method, interpolation, "quantile") a = np.asanyarray(a) if a.dtype.kind == "c": raise TypeError("a must be an array of real numbers") q = np.asanyarray(q) if not _quantile_is_valid(q): raise ValueError("Quantiles must be in the range [0, 1]") return _quantile_unchecked( a, q, axis, out, overwrite_input, method, keepdims) def _quantile_unchecked(a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=False): """Assumes that q is in [0, 1], and is an ndarray""" return _ureduce(a, func=_quantile_ureduce_func, q=q, keepdims=keepdims, axis=axis, out=out, overwrite_input=overwrite_input, method=method) def _quantile_is_valid(q): # avoid expensive reductions, relevant for arrays with < O(1000) elements if q.ndim == 1 and q.size < 10: for i in range(q.size): if not (0.0 <= q[i] <= 1.0): return False else: if not (np.all(0 <= q) and np.all(q <= 1)): return False return True def _check_interpolation_as_method(method, interpolation, fname): # Deprecated NumPy 1.22, 2021-11-08 warnings.warn( f"the `interpolation=` argument to {fname} was renamed to " "`method=`, which has additional options.\n" "Users of the modes 'nearest', 'lower', 'higher', or " "'midpoint' are encouraged to review the method they used. " "(Deprecated NumPy 1.22)", DeprecationWarning, stacklevel=4) if method != "linear": # sanity check, we assume this basically never happens raise TypeError( "You shall not pass both `method` and `interpolation`!\n" "(`interpolation` is Deprecated in favor of `method`)") return interpolation def _compute_virtual_index(n, quantiles, alpha: float, beta: float): """ Compute the floating point indexes of an array for the linear interpolation of quantiles. n : array_like The sample sizes. quantiles : array_like The quantiles values. alpha : float A constant used to correct the index computed. beta : float A constant used to correct the index computed. alpha and beta values depend on the chosen method (see quantile documentation) Reference: Hyndman&Fan paper "Sample Quantiles in Statistical Packages", DOI: 10.1080/00031305.1996.10473566 """ return n * quantiles + ( alpha + quantiles * (1 - alpha - beta) ) - 1 def _get_gamma(virtual_indexes, previous_indexes, method): """ Compute gamma (a.k.a 'm' or 'weight') for the linear interpolation of quantiles. virtual_indexes : array_like The indexes where the percentile is supposed to be found in the sorted sample. previous_indexes : array_like The floor values of virtual_indexes. interpolation : dict The interpolation method chosen, which may have a specific rule modifying gamma. gamma is usually the fractional part of virtual_indexes but can be modified by the interpolation method. """ gamma = np.asanyarray(virtual_indexes - previous_indexes) gamma = method["fix_gamma"](gamma, virtual_indexes) return np.asanyarray(gamma) def _lerp(a, b, t, out=None): """ Compute the linear interpolation weighted by gamma on each point of two same shape array. a : array_like Left bound. b : array_like Right bound. t : array_like The interpolation weight. out : array_like Output array. """ diff_b_a = subtract(b, a) # asanyarray is a stop-gap until gh-13105 lerp_interpolation = asanyarray(add(a, diff_b_a * t, out=out)) subtract(b, diff_b_a * (1 - t), out=lerp_interpolation, where=t >= 0.5) if lerp_interpolation.ndim == 0 and out is None: lerp_interpolation = lerp_interpolation[()] # unpack 0d arrays return lerp_interpolation def _get_gamma_mask(shape, default_value, conditioned_value, where): out = np.full(shape, default_value) np.copyto(out, conditioned_value, where=where, casting="unsafe") return out def _discret_interpolation_to_boundaries(index, gamma_condition_fun): previous = np.floor(index) next = previous + 1 gamma = index - previous res = _get_gamma_mask(shape=index.shape, default_value=next, conditioned_value=previous, where=gamma_condition_fun(gamma, index) ).astype(np.intp) # Some methods can lead to out-of-bound integers, clip them: res[res < 0] = 0 return res def _closest_observation(n, quantiles): gamma_fun = lambda gamma, index: (gamma == 0) & (np.floor(index) % 2 == 0) return _discret_interpolation_to_boundaries((n * quantiles) - 1 - 0.5, gamma_fun) def _inverted_cdf(n, quantiles): gamma_fun = lambda gamma, _: (gamma == 0) return _discret_interpolation_to_boundaries((n * quantiles) - 1, gamma_fun) def _quantile_ureduce_func( a: np.array, q: np.array, axis: int = None, out=None, overwrite_input: bool = False, method="linear", ) -> np.array: if q.ndim > 2: # The code below works fine for nd, but it might not have useful # semantics. For now, keep the supported dimensions the same as it was # before. raise ValueError("q must be a scalar or 1d") if overwrite_input: if axis is None: axis = 0 arr = a.ravel() else: arr = a else: if axis is None: axis = 0 arr = a.flatten() else: arr = a.copy() result = _quantile(arr, quantiles=q, axis=axis, method=method, out=out) return result def _get_indexes(arr, virtual_indexes, valid_values_count): """ Get the valid indexes of arr neighbouring virtual_indexes. Note This is a companion function to linear interpolation of Quantiles Returns ------- (previous_indexes, next_indexes): Tuple A Tuple of virtual_indexes neighbouring indexes """ previous_indexes = np.asanyarray(np.floor(virtual_indexes)) next_indexes = np.asanyarray(previous_indexes + 1) indexes_above_bounds = virtual_indexes >= valid_values_count - 1 # When indexes is above max index, take the max value of the array if indexes_above_bounds.any(): previous_indexes[indexes_above_bounds] = -1 next_indexes[indexes_above_bounds] = -1 # When indexes is below min index, take the min value of the array indexes_below_bounds = virtual_indexes < 0 if indexes_below_bounds.any(): previous_indexes[indexes_below_bounds] = 0 next_indexes[indexes_below_bounds] = 0 if np.issubdtype(arr.dtype, np.inexact): # After the sort, slices having NaNs will have for last element a NaN virtual_indexes_nans = np.isnan(virtual_indexes) if virtual_indexes_nans.any(): previous_indexes[virtual_indexes_nans] = -1 next_indexes[virtual_indexes_nans] = -1 previous_indexes = previous_indexes.astype(np.intp) next_indexes = next_indexes.astype(np.intp) return previous_indexes, next_indexes def _quantile( arr: np.array, quantiles: np.array, axis: int = -1, method="linear", out=None, ): """ Private function that doesn't support extended axis or keepdims. These methods are extended to this function using _ureduce See nanpercentile for parameter usage It computes the quantiles of the array for the given axis. A linear interpolation is performed based on the `interpolation`. By default, the method is "linear" where alpha == beta == 1 which performs the 7th method of Hyndman&Fan. With "median_unbiased" we get alpha == beta == 1/3 thus the 8th method of Hyndman&Fan. """ # --- Setup arr = np.asanyarray(arr) values_count = arr.shape[axis] # The dimensions of `q` are prepended to the output shape, so we need the # axis being sampled from `arr` to be last. if axis != 0: # But moveaxis is slow, so only call it if necessary. arr = np.moveaxis(arr, axis, destination=0) # --- Computation of indexes # Index where to find the value in the sorted array. # Virtual because it is a floating point value, not an valid index. # The nearest neighbours are used for interpolation try: method = _QuantileMethods[method] except KeyError: raise ValueError( f"{method!r} is not a valid method. Use one of: " f"{_QuantileMethods.keys()}") from None virtual_indexes = method["get_virtual_index"](values_count, quantiles) virtual_indexes = np.asanyarray(virtual_indexes) supports_nans = ( np.issubdtype(arr.dtype, np.inexact) or arr.dtype.kind in 'Mm') if np.issubdtype(virtual_indexes.dtype, np.integer): # No interpolation needed, take the points along axis if supports_nans: # may contain nan, which would sort to the end arr.partition(concatenate((virtual_indexes.ravel(), [-1])), axis=0) slices_having_nans = np.isnan(arr[-1, ...]) else: # cannot contain nan arr.partition(virtual_indexes.ravel(), axis=0) slices_having_nans = np.array(False, dtype=bool) result = take(arr, virtual_indexes, axis=0, out=out) else: previous_indexes, next_indexes = _get_indexes(arr, virtual_indexes, values_count) # --- Sorting arr.partition( np.unique(np.concatenate(([0, -1], previous_indexes.ravel(), next_indexes.ravel(), ))), axis=0) if supports_nans: slices_having_nans = np.isnan(arr[-1, ...]) else: slices_having_nans = None # --- Get values from indexes previous = arr[previous_indexes] next = arr[next_indexes] # --- Linear interpolation gamma = _get_gamma(virtual_indexes, previous_indexes, method) result_shape = virtual_indexes.shape + (1,) * (arr.ndim - 1) gamma = gamma.reshape(result_shape) result = _lerp(previous, next, gamma, out=out) if np.any(slices_having_nans): if result.ndim == 0 and out is None: # can't write to a scalar, but indexing will be correct result = arr[-1] else: np.copyto(result, arr[-1, ...], where=slices_having_nans) return result def _trapz_dispatcher(y, x=None, dx=None, axis=None): return (y, x) @array_function_dispatch(_trapz_dispatcher) def trapz(y, x=None, dx=1.0, axis=-1): r""" Integrate along the given axis using the composite trapezoidal rule. If `x` is provided, the integration happens in sequence along its elements - they are not sorted. Integrate `y` (`x`) along each 1d slice on the given axis, compute :math:`\int y(x) dx`. When `x` is specified, this integrates along the parametric curve, computing :math:`\int_t y(t) dt = \int_t y(t) \left.\frac{dx}{dt}\right\|_{x=x(t)} dt`. Parameters ---------- y : array_like Input array to integrate. x : array_like, optional The sample points corresponding to the `y` values. If `x` is None, the sample points are assumed to be evenly spaced `dx` apart. The default is None. dx : scalar, optional The spacing between sample points when `x` is None. The default is 1. axis : int, optional The axis along which to integrate. Returns ------- trapz : float or ndarray Definite integral of `y` = n-dimensional array as approximated along a single axis by the trapezoidal rule. If `y` is a 1-dimensional array, then the result is a float. If `n` is greater than 1, then the result is an `n`-1 dimensional array. See Also -------- sum, cumsum Notes ----- Image [2]_ illustrates trapezoidal rule -- y-axis locations of points will be taken from `y` array, by default x-axis distances between points will be 1.0, alternatively they can be provided with `x` array or with `dx` scalar. Return value will be equal to combined area under the red lines. References ---------- .. [1] Wikipedia page: https://en.wikipedia.org/wiki/Trapezoidal_rule .. [2] Illustration image: https://en.wikipedia.org/wiki/File:Composite_trapezoidal_rule_illustration.png Examples -------- Use the trapezoidal rule on evenly spaced points: >>> np.trapz([1, 2, 3]) 4.0 The spacing between sample points can be selected by either the ``x`` or ``dx`` arguments: >>> np.trapz([1, 2, 3], x=[4, 6, 8]) 8.0 >>> np.trapz([1, 2, 3], dx=2) 8.0 Using a decreasing ``x`` corresponds to integrating in reverse: >>> np.trapz([1, 2, 3], x=[8, 6, 4]) -8.0 More generally ``x`` is used to integrate along a parametric curve. We can estimate the integral :math:`\int_0^1 x^2 = 1/3` using: >>> x = np.linspace(0, 1, num=50) >>> y = x*2 >>> np.trapz(y, x) 0.33340274885464394 Or estimate the area of a circle, noting we repeat the sample which closes the curve: >>> theta = np.linspace(0, 2 np.pi, num=1000, endpoint=True) >>> np.trapz(np.cos(theta), x=np.sin(theta)) 3.141571941375841 ``np.trapz`` can be applied along a specified axis to do multiple computations in one call: >>> a = np.arange(6).reshape(2, 3) >>> a array([[0, 1, 2], [3, 4, 5]]) >>> np.trapz(a, axis=0) array([1.5, 2.5, 3.5]) >>> np.trapz(a, axis=1) array([2., 8.]) """ y = asanyarray(y) if x is None: d = dx else: x = asanyarray(x) if x.ndim == 1: d = diff(x) # reshape to correct shape shape = [1]y.ndim shape[axis] = d.shape[0] d = d.reshape(shape) else: d = diff(x, axis=axis) nd = y.ndim slice1 = [slice(None)]nd slice2 = [slice(None)]nd slice1[axis] = slice(1, None) slice2[axis] = slice(None, -1) try: ret = (d (y[tuple(slice1)] + y[tuple(slice2)]) / 2.0).sum(axis) except ValueError: # Operations didn't work, cast to ndarray d = np.asarray(d) y = np.asarray(y) ret = add.reduce(d * (y[tuple(slice1)]+y[tuple(slice2)])/2.0, axis) return ret # __array_function__ has no __code__ or other attributes normal Python funcs we # wrap everything into a C callable. SciPy however, tries to "clone" `trapz` # into a new Python function which requires `__code__` and a few other # attributes. So we create a dummy clone and copy over its attributes allowing # SciPy <= 1.10 to work: https://github.com/scipy/scipy/issues/17811 assert not hasattr(trapz, "__code__") def _fake_trapz(y, x=None, dx=1.0, axis=-1): return trapz(y, x=x, dx=dx, axis=axis) trapz.__code__ = _fake_trapz.__code__ trapz.__globals__ = _fake_trapz.__globals__ trapz.__defaults__ = _fake_trapz.__defaults__ trapz.__closure__ = _fake_trapz.__closure__ trapz.__kwdefaults__ = _fake_trapz.__kwdefaults__ def _meshgrid_dispatcher(xi, copy=None, sparse=None, indexing=None): return xi # Based on scitools meshgrid @array_function_dispatch(_meshgrid_dispatcher) def meshgrid(xi, copy=True, sparse=False, indexing='xy'): """ Return a list of coordinate matrices from coordinate vectors. Make N-D coordinate arrays for vectorized evaluations of N-D scalar/vector fields over N-D grids, given one-dimensional coordinate arrays x1, x2,..., xn. .. versionchanged:: 1.9 1-D and 0-D cases are allowed. Parameters ---------- x1, x2,..., xn : array_like 1-D arrays representing the coordinates of a grid. indexing : {'xy', 'ij'}, optional Cartesian ('xy', default) or matrix ('ij') indexing of output. See Notes for more details. .. versionadded:: 1.7.0 sparse : bool, optional If True the shape of the returned coordinate array for dimension i is reduced from ``(N1, ..., Ni, ... Nn)`` to ``(1, ..., 1, Ni, 1, ..., 1)``. These sparse coordinate grids are intended to be use with :ref:`basics.broadcasting`. When all coordinates are used in an expression, broadcasting still leads to a fully-dimensonal result array. Default is False. .. versionadded:: 1.7.0 copy : bool, optional If False, a view into the original arrays are returned in order to conserve memory. Default is True. Please note that ``sparse=False, copy=False`` will likely return non-contiguous arrays. Furthermore, more than one element of a broadcast array may refer to a single memory location. If you need to write to the arrays, make copies first. .. versionadded:: 1.7.0 Returns ------- X1, X2,..., XN : list of ndarrays For vectors `x1`, `x2`,..., `xn` with lengths ``Ni=len(xi)``, returns ``(N1, N2, N3,..., Nn)`` shaped arrays if indexing='ij' or ``(N2, N1, N3,..., Nn)`` shaped arrays if indexing='xy' with the elements of `xi` repeated to fill the matrix along the first dimension for `x1`, the second for `x2` and so on. Notes ----- This function supports both indexing conventions through the indexing keyword argument. Giving the string 'ij' returns a meshgrid with matrix indexing, while 'xy' returns a meshgrid with Cartesian indexing. In the 2-D case with inputs of length M and N, the outputs are of shape (N, M) for 'xy' indexing and (M, N) for 'ij' indexing. In the 3-D case with inputs of length M, N and P, outputs are of shape (N, M, P) for 'xy' indexing and (M, N, P) for 'ij' indexing. The difference is illustrated by the following code snippet:: xv, yv = np.meshgrid(x, y, indexing='ij') for i in range(nx): for j in range(ny): # treat xv[i,j], yv[i,j] xv, yv = np.meshgrid(x, y, indexing='xy') for i in range(nx): for j in range(ny): # treat xv[j,i], yv[j,i] In the 1-D and 0-D case, the indexing and sparse keywords have no effect. See Also -------- mgrid : Construct a multi-dimensional "meshgrid" using indexing notation. ogrid : Construct an open multi-dimensional "meshgrid" using indexing notation. how-to-index Examples -------- >>> nx, ny = (3, 2) >>> x = np.linspace(0, 1, nx) >>> y = np.linspace(0, 1, ny) >>> xv, yv = np.meshgrid(x, y) >>> xv array([[0. , 0.5, 1. ], [0. , 0.5, 1. ]]) >>> yv array([[0., 0., 0.], [1., 1., 1.]]) The result of `meshgrid` is a coordinate grid: >>> import matplotlib.pyplot as plt >>> plt.plot(xv, yv, marker='o', color='k', linestyle='none') >>> plt.show() You can create sparse output arrays to save memory and computation time. >>> xv, yv = np.meshgrid(x, y, sparse=True) >>> xv array([[0. , 0.5, 1. ]]) >>> yv array([[0.], [1.]]) `meshgrid` is very useful to evaluate functions on a grid. If the function depends on all coordinates, both dense and sparse outputs can be used. >>> x = np.linspace(-5, 5, 101) >>> y = np.linspace(-5, 5, 101) >>> # full coordinate arrays >>> xx, yy = np.meshgrid(x, y) >>> zz = np.sqrt(xx2 + yy2) >>> xx.shape, yy.shape, zz.shape ((101, 101), (101, 101), (101, 101)) >>> # sparse coordinate arrays >>> xs, ys = np.meshgrid(x, y, sparse=True) >>> zs = np.sqrt(xs2 + ys2) >>> xs.shape, ys.shape, zs.shape ((1, 101), (101, 1), (101, 101)) >>> np.array_equal(zz, zs) True >>> h = plt.contourf(x, y, zs) >>> plt.axis('scaled') >>> plt.colorbar() >>> plt.show() """ ndim = len(xi) if indexing not in ['xy', 'ij']: raise ValueError( "Valid values for `indexing` are 'xy' and 'ij'.") s0 = (1,) * ndim output = [np.asanyarray(x).reshape(s0[:i] + (-1,) + s0[i + 1:]) for i, x in enumerate(xi)] if indexing == 'xy' and ndim > 1: # switch first and second axis output[0].shape = (1, -1) + s0[2:] output[1].shape = (-1, 1) + s0[2:] if not sparse: # Return the full N-D matrix (not only the 1-D vector) output = np.broadcast_arrays(output, subok=True) if copy: output = [x.copy() for x in output] return output def _delete_dispatcher(arr, obj, axis=None): return (arr, obj) @array_function_dispatch(_delete_dispatcher) def delete(arr, obj, axis=None): """ Return a new array with sub-arrays along an axis deleted. For a one dimensional array, this returns those entries not returned by `arr[obj]`. Parameters ---------- arr : array_like Input array. obj : slice, int or array of ints Indicate indices of sub-arrays to remove along the specified axis. .. versionchanged:: 1.19.0 Boolean indices are now treated as a mask of elements to remove, rather than being cast to the integers 0 and 1. axis : int, optional The axis along which to delete the subarray defined by `obj`. If `axis` is None, `obj` is applied to the flattened array. Returns ------- out : ndarray A copy of `arr` with the elements specified by `obj` removed. Note that `delete` does not occur in-place. If `axis` is None, `out` is a flattened array. See Also -------- insert : Insert elements into an array. append : Append elements at the end of an array. Notes ----- Often it is preferable to use a boolean mask. For example: >>> arr = np.arange(12) + 1 >>> mask = np.ones(len(arr), dtype=bool) >>> mask[[0,2,4]] = False >>> result = arr[mask,...] Is equivalent to ``np.delete(arr, [0,2,4], axis=0)``, but allows further use of `mask`. Examples -------- >>> arr = np.array([[1,2,3,4], [5,6,7,8], [9,10,11,12]]) >>> arr array([[ 1, 2, 3, 4], [ 5, 6, 7, 8], [ 9, 10, 11, 12]]) >>> np.delete(arr, 1, 0) array([[ 1, 2, 3, 4], [ 9, 10, 11, 12]]) >>> np.delete(arr, np.s_[::2], 1) array([[ 2, 4], [ 6, 8], [10, 12]]) >>> np.delete(arr, [1,3,5], None) array([ 1, 3, 5, 7, 8, 9, 10, 11, 12]) """ wrap = None if type(arr) is not ndarray: try: wrap = arr.__array_wrap__ except AttributeError: pass arr = asarray(arr) ndim = arr.ndim arrorder = 'F' if arr.flags.fnc else 'C' if axis is None: if ndim != 1: arr = arr.ravel() # needed for np.matrix, which is still not 1d after being ravelled ndim = arr.ndim axis = ndim - 1 else: axis = normalize_axis_index(axis, ndim) slobj = [slice(None)]ndim N = arr.shape[axis] newshape = list(arr.shape) if isinstance(obj, slice): start, stop, step = obj.indices(N) xr = range(start, stop, step) numtodel = len(xr) if numtodel <= 0: if wrap: return wrap(arr.copy(order=arrorder)) else: return arr.copy(order=arrorder) # Invert if step is negative: if step < 0: step = -step start = xr[-1] stop = xr[0] + 1 newshape[axis] -= numtodel new = empty(newshape, arr.dtype, arrorder) # copy initial chunk if start == 0: pass else: slobj[axis] = slice(None, start) new[tuple(slobj)] = arr[tuple(slobj)] # copy end chunk if stop == N: pass else: slobj[axis] = slice(stop-numtodel, None) slobj2 = [slice(None)]ndim slobj2[axis] = slice(stop, None) new[tuple(slobj)] = arr[tuple(slobj2)] # copy middle pieces if step == 1: pass else: # use array indexing. keep = ones(stop-start, dtype=bool) keep[:stop-start:step] = False slobj[axis] = slice(start, stop-numtodel) slobj2 = [slice(None)]ndim slobj2[axis] = slice(start, stop) arr = arr[tuple(slobj2)] slobj2[axis] = keep new[tuple(slobj)] = arr[tuple(slobj2)] if wrap: return wrap(new) else: return new if isinstance(obj, (int, integer)) and not isinstance(obj, bool): single_value = True else: single_value = False _obj = obj obj = np.asarray(obj) # `size == 0` to allow empty lists similar to indexing, but (as there) # is really too generic: if obj.size == 0 and not isinstance(_obj, np.ndarray): obj = obj.astype(intp) elif obj.size == 1 and obj.dtype.kind in "ui": # For a size 1 integer array we can use the single-value path # (most dtypes, except boolean, should just fail later). obj = obj.item() single_value = True if single_value: # optimization for a single value if (obj < -N or obj >= N): raise IndexError( "index %i is out of bounds for axis %i with " "size %i" % (obj, axis, N)) if (obj < 0): obj += N newshape[axis] -= 1 new = empty(newshape, arr.dtype, arrorder) slobj[axis] = slice(None, obj) new[tuple(slobj)] = arr[tuple(slobj)] slobj[axis] = slice(obj, None) slobj2 = [slice(None)]ndim slobj2[axis] = slice(obj+1, None) new[tuple(slobj)] = arr[tuple(slobj2)] else: if obj.dtype == bool: if obj.shape != (N,): raise ValueError('boolean array argument obj to delete ' 'must be one dimensional and match the axis ' 'length of {}'.format(N)) # optimization, the other branch is slower keep = ~obj else: keep = ones(N, dtype=bool) keep[obj,] = False slobj[axis] = keep new = arr[tuple(slobj)] if wrap: return wrap(new) else: return new def _insert_dispatcher(arr, obj, values, axis=None): return (arr, obj, values) @array_function_dispatch(_insert_dispatcher) def insert(arr, obj, values, axis=None): """ Insert values along the given axis before the given indices. Parameters ---------- arr : array_like Input array. obj : int, slice or sequence of ints Object that defines the index or indices before which `values` is inserted. .. versionadded:: 1.8.0 Support for multiple insertions when `obj` is a single scalar or a sequence with one element (similar to calling insert multiple times). values : array_like Values to insert into `arr`. If the type of `values` is different from that of `arr`, `values` is converted to the type of `arr`. `values` should be shaped so that ``arr[...,obj,...] = values`` is legal. axis : int, optional Axis along which to insert `values`. If `axis` is None then `arr` is flattened first. Returns ------- out : ndarray A copy of `arr` with `values` inserted. Note that `insert` does not occur in-place: a new array is returned. If `axis` is None, `out` is a flattened array. See Also -------- append : Append elements at the end of an array. concatenate : Join a sequence of arrays along an existing axis. delete : Delete elements from an array. Notes ----- Note that for higher dimensional inserts ``obj=0`` behaves very different from ``obj=[0]`` just like ``arr[:,0,:] = values`` is different from ``arr[:,[0],:] = values``. Examples -------- >>> a = np.array([[1, 1], [2, 2], [3, 3]]) >>> a array([[1, 1], [2, 2], [3, 3]]) >>> np.insert(a, 1, 5) array([1, 5, 1, ..., 2, 3, 3]) >>> np.insert(a, 1, 5, axis=1) array([[1, 5, 1], [2, 5, 2], [3, 5, 3]]) Difference between sequence and scalars: >>> np.insert(a, [1], [[1],[2],[3]], axis=1) array([[1, 1, 1], [2, 2, 2], [3, 3, 3]]) >>> np.array_equal(np.insert(a, 1, [1, 2, 3], axis=1), ... np.insert(a, [1], [[1],[2],[3]], axis=1)) True >>> b = a.flatten() >>> b array([1, 1, 2, 2, 3, 3]) >>> np.insert(b, [2, 2], [5, 6]) array([1, 1, 5, ..., 2, 3, 3]) >>> np.insert(b, slice(2, 4), [5, 6]) array([1, 1, 5, ..., 2, 3, 3]) >>> np.insert(b, [2, 2], [7.13, False]) # type casting array([1, 1, 7, ..., 2, 3, 3]) >>> x = np.arange(8).reshape(2, 4) >>> idx = (1, 3) >>> np.insert(x, idx, 999, axis=1) array([[ 0, 999, 1, 2, 999, 3], [ 4, 999, 5, 6, 999, 7]]) """ wrap = None if type(arr) is not ndarray: try: wrap = arr.__array_wrap__ except AttributeError: pass arr = asarray(arr) ndim = arr.ndim arrorder = 'F' if arr.flags.fnc else 'C' if axis is None: if ndim != 1: arr = arr.ravel() # needed for np.matrix, which is still not 1d after being ravelled ndim = arr.ndim axis = ndim - 1 else: axis = normalize_axis_index(axis, ndim) slobj = [slice(None)]ndim N = arr.shape[axis] newshape = list(arr.shape) if isinstance(obj, slice): # turn it into a range object indices = arange(obj.indices(N), dtype=intp) else: # need to copy obj, because indices will be changed in-place indices = np.array(obj) if indices.dtype == bool: # See also delete # 2012-10-11, NumPy 1.8 warnings.warn( "in the future insert will treat boolean arrays and " "array-likes as a boolean index instead of casting it to " "integer", FutureWarning, stacklevel=2) indices = indices.astype(intp) # Code after warning period: #if obj.ndim != 1: # raise ValueError('boolean array argument obj to insert ' # 'must be one dimensional') #indices = np.flatnonzero(obj) elif indices.ndim > 1: raise ValueError( "index array argument obj to insert must be one dimensional " "or scalar") if indices.size == 1: index = indices.item() if index < -N or index > N: raise IndexError(f"index {obj} is out of bounds for axis {axis} " f"with size {N}") if (index < 0): index += N # There are some object array corner cases here, but we cannot avoid # that: values = array(values, copy=False, ndmin=arr.ndim, dtype=arr.dtype) if indices.ndim == 0: # broadcasting is very different here, since a[:,0,:] = ... behaves # very different from a[:,[0],:] = ...! This changes values so that # it works likes the second case. (here a[:,0:1,:]) values = np.moveaxis(values, 0, axis) numnew = values.shape[axis] newshape[axis] += numnew new = empty(newshape, arr.dtype, arrorder) slobj[axis] = slice(None, index) new[tuple(slobj)] = arr[tuple(slobj)] slobj[axis] = slice(index, index+numnew) new[tuple(slobj)] = values slobj[axis] = slice(index+numnew, None) slobj2 = [slice(None)] ndim slobj2[axis] = slice(index, None) new[tuple(slobj)] = arr[tuple(slobj2)] if wrap: return wrap(new) return new elif indices.size == 0 and not isinstance(obj, np.ndarray): # Can safely cast the empty list to intp indices = indices.astype(intp) indices[indices < 0] += N numnew = len(indices) order = indices.argsort(kind='mergesort') # stable sort indices[order] += np.arange(numnew) newshape[axis] += numnew old_mask = ones(newshape[axis], dtype=bool) old_mask[indices] = False new = empty(newshape, arr.dtype, arrorder) slobj2 = [slice(None)]*ndim slobj[axis] = indices slobj2[axis] = old_mask new[tuple(slobj)] = values new[tuple(slobj2)] = arr if wrap: return wrap(new) return new def _append_dispatcher(arr, values, axis=None): return (arr, values) @array_function_dispatch(_append_dispatcher) def append(arr, values, axis=None): """ Append values to the end of an array. Parameters ---------- arr : array_like Values are appended to a copy of this array. values : array_like These values are appended to a copy of `arr`. It must be of the correct shape (the same shape as `arr`, excluding `axis`). If `axis` is not specified, `values` can be any shape and will be flattened before use. axis : int, optional The axis along which `values` are appended. If `axis` is not given, both `arr` and `values` are flattened before use. Returns ------- append : ndarray A copy of `arr` with `values` appended to `axis`. Note that `append` does not occur in-place: a new array is allocated and filled. If `axis` is None, `out` is a flattened array. See Also -------- insert : Insert elements into an array. delete : Delete elements from an array. Examples -------- >>> np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]]) array([1, 2, 3, ..., 7, 8, 9]) When `axis` is specified, `values` must have the correct shape. >>> np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0) array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]) >>> np.append([[1, 2, 3], [4, 5, 6]], [7, 8, 9], axis=0) Traceback (most recent call last): ... ValueError: all the input arrays must have same number of dimensions, but the array at index 0 has 2 dimension(s) and the array at index 1 has 1 dimension(s) """ arr = asanyarray(arr) if axis is None: if arr.ndim != 1: arr = arr.ravel() values = ravel(values) axis = arr.ndim-1 return concatenate((arr, values), axis=axis) def _digitize_dispatcher(x, bins, right=None): return (x, bins) @array_function_dispatch(_digitize_dispatcher) def digitize(x, bins, right=False): """ Return the indices of the bins to which each value in input array belongs. ========= ============= ============================ `right` order of bins returned index `i` satisfies ========= ============= ============================ ``False`` increasing ``bins[i-1] <= x < bins[i]`` ``True`` increasing ``bins[i-1] < x <= bins[i]`` ``False`` decreasing ``bins[i-1] > x >= bins[i]`` ``True`` decreasing ``bins[i-1] >= x > bins[i]`` ========= ============= ============================ If values in `x` are beyond the bounds of `bins`, 0 or ``len(bins)`` is returned as appropriate. Parameters ---------- x : array_like Input array to be binned. Prior to NumPy 1.10.0, this array had to be 1-dimensional, but can now have any shape. bins : array_like Array of bins. It has to be 1-dimensional and monotonic. right : bool, optional Indicating whether the intervals include the right or the left bin edge. Default behavior is (right==False) indicating that the interval does not include the right edge. The left bin end is open in this case, i.e., bins[i-1] <= x < bins[i] is the default behavior for monotonically increasing bins. Returns ------- indices : ndarray of ints Output array of indices, of same shape as `x`. Raises ------ ValueError If `bins` is not monotonic. TypeError If the type of the input is complex. See Also -------- bincount, histogram, unique, searchsorted Notes ----- If values in `x` are such that they fall outside the bin range, attempting to index `bins` with the indices that `digitize` returns will result in an IndexError. .. versionadded:: 1.10.0 `np.digitize` is implemented in terms of `np.searchsorted`. This means that a binary search is used to bin the values, which scales much better for larger number of bins than the previous linear search. It also removes the requirement for the input array to be 1-dimensional. For monotonically _increasing_ `bins`, the following are equivalent:: np.digitize(x, bins, right=True) np.searchsorted(bins, x, side='left') Note that as the order of the arguments are reversed, the side must be too. The `searchsorted` call is marginally faster, as it does not do any monotonicity checks. Perhaps more importantly, it supports all dtypes. Examples -------- >>> x = np.array([0.2, 6.4, 3.0, 1.6]) >>> bins = np.array([0.0, 1.0, 2.5, 4.0, 10.0]) >>> inds = np.digitize(x, bins) >>> inds array([1, 4, 3, 2]) >>> for n in range(x.size): ... print(bins[inds[n]-1], "<=", x[n], "<", bins[inds[n]]) ... 0.0 <= 0.2 < 1.0 4.0 <= 6.4 < 10.0 2.5 <= 3.0 < 4.0 1.0 <= 1.6 < 2.5 >>> x = np.array([1.2, 10.0, 12.4, 15.5, 20.]) >>> bins = np.array([0, 5, 10, 15, 20]) >>> np.digitize(x,bins,right=True) array([1, 2, 3, 4, 4]) >>> np.digitize(x,bins,right=False) array([1, 3, 3, 4, 5]) """ x = _nx.asarray(x) bins = _nx.asarray(bins) # here for compatibility, searchsorted below is happy to take this if np.issubdtype(x.dtype, _nx.complexfloating): raise TypeError("x may not be complex") mono = _monotonicity(bins) if mono == 0: raise ValueError("bins must be monotonically increasing or decreasing") # this is backwards because the arguments below are swapped side = 'left' if right else 'right' if mono == -1: # reverse the bins, and invert the results return len(bins) - _nx.searchsorted(bins[::-1], x, side=side) else: return _nx.searchsorted(bins, x, side=side)	184.67 KB	2026-01-20 12:58
📄 function_base.pyi import sys from collections.abc import Sequence, Iterator, Callable, Iterable from typing import ( Literal as L, Any, TypeVar, overload, Protocol, SupportsIndex, SupportsInt, ) if sys.version_info >= (3, 10): from typing import TypeGuard else: from typing_extensions import TypeGuard from numpy import ( vectorize as vectorize, ufunc, generic, floating, complexfloating, intp, float64, complex128, timedelta64, datetime64, object_, _OrderKACF, ) from numpy._typing import ( NDArray, ArrayLike, DTypeLike, _ShapeLike, _ScalarLike_co, _DTypeLike, _ArrayLike, _ArrayLikeInt_co, _ArrayLikeFloat_co, _ArrayLikeComplex_co, _ArrayLikeTD64_co, _ArrayLikeDT64_co, _ArrayLikeObject_co, _FloatLike_co, _ComplexLike_co, ) from numpy.core.function_base import ( add_newdoc as add_newdoc, ) from numpy.core.multiarray import ( add_docstring as add_docstring, bincount as bincount, ) from numpy.core.umath import _add_newdoc_ufunc _T = TypeVar("_T") _T_co = TypeVar("_T_co", covariant=True) _SCT = TypeVar("_SCT", bound=generic) _ArrayType = TypeVar("_ArrayType", bound=NDArray[Any]) _2Tuple = tuple[_T, _T] class _TrimZerosSequence(Protocol[_T_co]): def __len__(self) -> int: ... def __getitem__(self, key: slice, /) -> _T_co: ... def __iter__(self) -> Iterator[Any]: ... class _SupportsWriteFlush(Protocol): def write(self, s: str, /) -> object: ... def flush(self) -> object: ... __all__: list[str] # NOTE: This is in reality a re-export of `np.core.umath._add_newdoc_ufunc` def add_newdoc_ufunc(ufunc: ufunc, new_docstring: str, /) -> None: ... @overload def rot90( m: _ArrayLike[_SCT], k: int = ..., axes: tuple[int, int] = ..., ) -> NDArray[_SCT]: ... @overload def rot90( m: ArrayLike, k: int = ..., axes: tuple[int, int] = ..., ) -> NDArray[Any]: ... @overload def flip(m: _SCT, axis: None = ...) -> _SCT: ... @overload def flip(m: _ScalarLike_co, axis: None = ...) -> Any: ... @overload def flip(m: _ArrayLike[_SCT], axis: None \| _ShapeLike = ...) -> NDArray[_SCT]: ... @overload def flip(m: ArrayLike, axis: None \| _ShapeLike = ...) -> NDArray[Any]: ... def iterable(y: object) -> TypeGuard[Iterable[Any]]: ... @overload def average( a: _ArrayLikeFloat_co, axis: None = ..., weights: None \| _ArrayLikeFloat_co= ..., returned: L[False] = ..., keepdims: L[False] = ..., ) -> floating[Any]: ... @overload def average( a: _ArrayLikeComplex_co, axis: None = ..., weights: None \| _ArrayLikeComplex_co = ..., returned: L[False] = ..., keepdims: L[False] = ..., ) -> complexfloating[Any, Any]: ... @overload def average( a: _ArrayLikeObject_co, axis: None = ..., weights: None \| Any = ..., returned: L[False] = ..., keepdims: L[False] = ..., ) -> Any: ... @overload def average( a: _ArrayLikeFloat_co, axis: None = ..., weights: None \| _ArrayLikeFloat_co= ..., returned: L[True] = ..., keepdims: L[False] = ..., ) -> _2Tuple[floating[Any]]: ... @overload def average( a: _ArrayLikeComplex_co, axis: None = ..., weights: None \| _ArrayLikeComplex_co = ..., returned: L[True] = ..., keepdims: L[False] = ..., ) -> _2Tuple[complexfloating[Any, Any]]: ... @overload def average( a: _ArrayLikeObject_co, axis: None = ..., weights: None \| Any = ..., returned: L[True] = ..., keepdims: L[False] = ..., ) -> _2Tuple[Any]: ... @overload def average( a: _ArrayLikeComplex_co \| _ArrayLikeObject_co, axis: None \| _ShapeLike = ..., weights: None \| Any = ..., returned: L[False] = ..., keepdims: bool = ..., ) -> Any: ... @overload def average( a: _ArrayLikeComplex_co \| _ArrayLikeObject_co, axis: None \| _ShapeLike = ..., weights: None \| Any = ..., returned: L[True] = ..., keepdims: bool = ..., ) -> _2Tuple[Any]: ... @overload def asarray_chkfinite( a: _ArrayLike[_SCT], dtype: None = ..., order: _OrderKACF = ..., ) -> NDArray[_SCT]: ... @overload def asarray_chkfinite( a: object, dtype: None = ..., order: _OrderKACF = ..., ) -> NDArray[Any]: ... @overload def asarray_chkfinite( a: Any, dtype: _DTypeLike[_SCT], order: _OrderKACF = ..., ) -> NDArray[_SCT]: ... @overload def asarray_chkfinite( a: Any, dtype: DTypeLike, order: _OrderKACF = ..., ) -> NDArray[Any]: ... # TODO: Use PEP 612 `ParamSpec` once mypy supports `Concatenate` # xref python/mypy#8645 @overload def piecewise( x: _ArrayLike[_SCT], condlist: ArrayLike, funclist: Sequence[Any \| Callable[..., Any]], args: Any, kw: Any, ) -> NDArray[_SCT]: ... @overload def piecewise( x: ArrayLike, condlist: ArrayLike, funclist: Sequence[Any \| Callable[..., Any]], args: Any, *kw: Any, ) -> NDArray[Any]: ... def select( condlist: Sequence[ArrayLike], choicelist: Sequence[ArrayLike], default: ArrayLike = ..., ) -> NDArray[Any]: ... @overload def copy( a: _ArrayType, order: _OrderKACF, subok: L[True], ) -> _ArrayType: ... @overload def copy( a: _ArrayType, order: _OrderKACF = ..., , subok: L[True], ) -> _ArrayType: ... @overload def copy( a: _ArrayLike[_SCT], order: _OrderKACF = ..., subok: L[False] = ..., ) -> NDArray[_SCT]: ... @overload def copy( a: ArrayLike, order: _OrderKACF = ..., subok: L[False] = ..., ) -> NDArray[Any]: ... def gradient( f: ArrayLike, varargs: ArrayLike, axis: None \| _ShapeLike = ..., edge_order: L[1, 2] = ..., ) -> Any: ... @overload def diff( a: _T, n: L[0], axis: SupportsIndex = ..., prepend: ArrayLike = ..., append: ArrayLike = ..., ) -> _T: ... @overload def diff( a: ArrayLike, n: int = ..., axis: SupportsIndex = ..., prepend: ArrayLike = ..., append: ArrayLike = ..., ) -> NDArray[Any]: ... @overload def interp( x: _ArrayLikeFloat_co, xp: _ArrayLikeFloat_co, fp: _ArrayLikeFloat_co, left: None \| _FloatLike_co = ..., right: None \| _FloatLike_co = ..., period: None \| _FloatLike_co = ..., ) -> NDArray[float64]: ... @overload def interp( x: _ArrayLikeFloat_co, xp: _ArrayLikeFloat_co, fp: _ArrayLikeComplex_co, left: None \| _ComplexLike_co = ..., right: None \| _ComplexLike_co = ..., period: None \| _FloatLike_co = ..., ) -> NDArray[complex128]: ... @overload def angle(z: _ComplexLike_co, deg: bool = ...) -> floating[Any]: ... @overload def angle(z: object_, deg: bool = ...) -> Any: ... @overload def angle(z: _ArrayLikeComplex_co, deg: bool = ...) -> NDArray[floating[Any]]: ... @overload def angle(z: _ArrayLikeObject_co, deg: bool = ...) -> NDArray[object_]: ... @overload def unwrap( p: _ArrayLikeFloat_co, discont: None \| float = ..., axis: int = ..., , period: float = ..., ) -> NDArray[floating[Any]]: ... @overload def unwrap( p: _ArrayLikeObject_co, discont: None \| float = ..., axis: int = ..., , period: float = ..., ) -> NDArray[object_]: ... def sort_complex(a: ArrayLike) -> NDArray[complexfloating[Any, Any]]: ... def trim_zeros( filt: _TrimZerosSequence[_T], trim: L["f", "b", "fb", "bf"] = ..., ) -> _T: ... @overload def extract(condition: ArrayLike, arr: _ArrayLike[_SCT]) -> NDArray[_SCT]: ... @overload def extract(condition: ArrayLike, arr: ArrayLike) -> NDArray[Any]: ... def place(arr: NDArray[Any], mask: ArrayLike, vals: Any) -> None: ... def disp( mesg: object, device: None \| _SupportsWriteFlush = ..., linefeed: bool = ..., ) -> None: ... @overload def cov( m: _ArrayLikeFloat_co, y: None \| _ArrayLikeFloat_co = ..., rowvar: bool = ..., bias: bool = ..., ddof: None \| SupportsIndex \| SupportsInt = ..., fweights: None \| ArrayLike = ..., aweights: None \| ArrayLike = ..., , dtype: None = ..., ) -> NDArray[floating[Any]]: ... @overload def cov( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., bias: bool = ..., ddof: None \| SupportsIndex \| SupportsInt = ..., fweights: None \| ArrayLike = ..., aweights: None \| ArrayLike = ..., , dtype: None = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def cov( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., bias: bool = ..., ddof: None \| SupportsIndex \| SupportsInt = ..., fweights: None \| ArrayLike = ..., aweights: None \| ArrayLike = ..., , dtype: _DTypeLike[_SCT], ) -> NDArray[_SCT]: ... @overload def cov( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., bias: bool = ..., ddof: None \| SupportsIndex \| SupportsInt = ..., fweights: None \| ArrayLike = ..., aweights: None \| ArrayLike = ..., , dtype: DTypeLike, ) -> NDArray[Any]: ... # NOTE `bias` and `ddof` have been deprecated @overload def corrcoef( m: _ArrayLikeFloat_co, y: None \| _ArrayLikeFloat_co = ..., rowvar: bool = ..., , dtype: None = ..., ) -> NDArray[floating[Any]]: ... @overload def corrcoef( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., , dtype: None = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def corrcoef( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., , dtype: _DTypeLike[_SCT], ) -> NDArray[_SCT]: ... @overload def corrcoef( m: _ArrayLikeComplex_co, y: None \| _ArrayLikeComplex_co = ..., rowvar: bool = ..., , dtype: DTypeLike, ) -> NDArray[Any]: ... def blackman(M: _FloatLike_co) -> NDArray[floating[Any]]: ... def bartlett(M: _FloatLike_co) -> NDArray[floating[Any]]: ... def hanning(M: _FloatLike_co) -> NDArray[floating[Any]]: ... def hamming(M: _FloatLike_co) -> NDArray[floating[Any]]: ... def i0(x: _ArrayLikeFloat_co) -> NDArray[floating[Any]]: ... def kaiser( M: _FloatLike_co, beta: _FloatLike_co, ) -> NDArray[floating[Any]]: ... @overload def sinc(x: _FloatLike_co) -> floating[Any]: ... @overload def sinc(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def sinc(x: _ArrayLikeFloat_co) -> NDArray[floating[Any]]: ... @overload def sinc(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... # NOTE: Deprecated # def msort(a: ArrayLike) -> NDArray[Any]: ... @overload def median( a: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., keepdims: L[False] = ..., ) -> floating[Any]: ... @overload def median( a: _ArrayLikeComplex_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., keepdims: L[False] = ..., ) -> complexfloating[Any, Any]: ... @overload def median( a: _ArrayLikeTD64_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., keepdims: L[False] = ..., ) -> timedelta64: ... @overload def median( a: _ArrayLikeObject_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., keepdims: L[False] = ..., ) -> Any: ... @overload def median( a: _ArrayLikeFloat_co \| _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co, axis: None \| _ShapeLike = ..., out: None = ..., overwrite_input: bool = ..., keepdims: bool = ..., ) -> Any: ... @overload def median( a: _ArrayLikeFloat_co \| _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co, axis: None \| _ShapeLike = ..., out: _ArrayType = ..., overwrite_input: bool = ..., keepdims: bool = ..., ) -> _ArrayType: ... _MethodKind = L[ "inverted_cdf", "averaged_inverted_cdf", "closest_observation", "interpolated_inverted_cdf", "hazen", "weibull", "linear", "median_unbiased", "normal_unbiased", "lower", "higher", "midpoint", "nearest", ] @overload def percentile( a: _ArrayLikeFloat_co, q: _FloatLike_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> floating[Any]: ... @overload def percentile( a: _ArrayLikeComplex_co, q: _FloatLike_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> complexfloating[Any, Any]: ... @overload def percentile( a: _ArrayLikeTD64_co, q: _FloatLike_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> timedelta64: ... @overload def percentile( a: _ArrayLikeDT64_co, q: _FloatLike_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> datetime64: ... @overload def percentile( a: _ArrayLikeObject_co, q: _FloatLike_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> Any: ... @overload def percentile( a: _ArrayLikeFloat_co, q: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> NDArray[floating[Any]]: ... @overload def percentile( a: _ArrayLikeComplex_co, q: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def percentile( a: _ArrayLikeTD64_co, q: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> NDArray[timedelta64]: ... @overload def percentile( a: _ArrayLikeDT64_co, q: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> NDArray[datetime64]: ... @overload def percentile( a: _ArrayLikeObject_co, q: _ArrayLikeFloat_co, axis: None = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: L[False] = ..., ) -> NDArray[object_]: ... @overload def percentile( a: _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co, q: _ArrayLikeFloat_co, axis: None \| _ShapeLike = ..., out: None = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: bool = ..., ) -> Any: ... @overload def percentile( a: _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co, q: _ArrayLikeFloat_co, axis: None \| _ShapeLike = ..., out: _ArrayType = ..., overwrite_input: bool = ..., method: _MethodKind = ..., keepdims: bool = ..., ) -> _ArrayType: ... # NOTE: Not an alias, but they do have identical signatures # (that we can reuse) quantile = percentile # TODO: Returns a scalar for <= 1D array-likes; returns an ndarray otherwise def trapz( y: _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co, x: None \| _ArrayLikeComplex_co \| _ArrayLikeTD64_co \| _ArrayLikeObject_co = ..., dx: float = ..., axis: SupportsIndex = ..., ) -> Any: ... def meshgrid( xi: ArrayLike, copy: bool = ..., sparse: bool = ..., indexing: L["xy", "ij"] = ..., ) -> list[NDArray[Any]]: ... @overload def delete( arr: _ArrayLike[_SCT], obj: slice \| _ArrayLikeInt_co, axis: None \| SupportsIndex = ..., ) -> NDArray[_SCT]: ... @overload def delete( arr: ArrayLike, obj: slice \| _ArrayLikeInt_co, axis: None \| SupportsIndex = ..., ) -> NDArray[Any]: ... @overload def insert( arr: _ArrayLike[_SCT], obj: slice \| _ArrayLikeInt_co, values: ArrayLike, axis: None \| SupportsIndex = ..., ) -> NDArray[_SCT]: ... @overload def insert( arr: ArrayLike, obj: slice \| _ArrayLikeInt_co, values: ArrayLike, axis: None \| SupportsIndex = ..., ) -> NDArray[Any]: ... def append( arr: ArrayLike, values: ArrayLike, axis: None \| SupportsIndex = ..., ) -> NDArray[Any]: ... @overload def digitize( x: _FloatLike_co, bins: _ArrayLikeFloat_co, right: bool = ..., ) -> intp: ... @overload def digitize( x: _ArrayLikeFloat_co, bins: _ArrayLikeFloat_co, right: bool = ..., ) -> NDArray[intp]: ...	16.2 KB	2026-01-20 12:58
📄 histograms.py """ Histogram-related functions """ import contextlib import functools import operator import warnings import numpy as np from numpy.core import overrides __all__ = ['histogram', 'histogramdd', 'histogram_bin_edges'] array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') # range is a keyword argument to many functions, so save the builtin so they can # use it. _range = range def _ptp(x): """Peak-to-peak value of x. This implementation avoids the problem of signed integer arrays having a peak-to-peak value that cannot be represented with the array's data type. This function returns an unsigned value for signed integer arrays. """ return _unsigned_subtract(x.max(), x.min()) def _hist_bin_sqrt(x, range): """ Square root histogram bin estimator. Bin width is inversely proportional to the data size. Used by many programs for its simplicity. Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused return _ptp(x) / np.sqrt(x.size) def _hist_bin_sturges(x, range): """ Sturges histogram bin estimator. A very simplistic estimator based on the assumption of normality of the data. This estimator has poor performance for non-normal data, which becomes especially obvious for large data sets. The estimate depends only on size of the data. Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused return _ptp(x) / (np.log2(x.size) + 1.0) def _hist_bin_rice(x, range): """ Rice histogram bin estimator. Another simple estimator with no normality assumption. It has better performance for large data than Sturges, but tends to overestimate the number of bins. The number of bins is proportional to the cube root of data size (asymptotically optimal). The estimate depends only on size of the data. Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused return _ptp(x) / (2.0 * x.size ** (1.0 / 3)) def _hist_bin_scott(x, range): """ Scott histogram bin estimator. The binwidth is proportional to the standard deviation of the data and inversely proportional to the cube root of data size (asymptotically optimal). Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused return (24.0 * np.pi0.5 / x.size)(1.0 / 3.0) * np.std(x) def _hist_bin_stone(x, range): """ Histogram bin estimator based on minimizing the estimated integrated squared error (ISE). The number of bins is chosen by minimizing the estimated ISE against the unknown true distribution. The ISE is estimated using cross-validation and can be regarded as a generalization of Scott's rule. https://en.wikipedia.org/wiki/Histogram#Scott.27s_normal_reference_rule This paper by Stone appears to be the origination of this rule. http://digitalassets.lib.berkeley.edu/sdtr/ucb/text/34.pdf Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. range : (float, float) The lower and upper range of the bins. Returns ------- h : An estimate of the optimal bin width for the given data. """ n = x.size ptp_x = _ptp(x) if n <= 1 or ptp_x == 0: return 0 def jhat(nbins): hh = ptp_x / nbins p_k = np.histogram(x, bins=nbins, range=range)[0] / n return (2 - (n + 1) * p_k.dot(p_k)) / hh nbins_upper_bound = max(100, int(np.sqrt(n))) nbins = min(_range(1, nbins_upper_bound + 1), key=jhat) if nbins == nbins_upper_bound: warnings.warn("The number of bins estimated may be suboptimal.", RuntimeWarning, stacklevel=3) return ptp_x / nbins def _hist_bin_doane(x, range): """ Doane's histogram bin estimator. Improved version of Sturges' formula which works better for non-normal data. See stats.stackexchange.com/questions/55134/doanes-formula-for-histogram-binning Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused if x.size > 2: sg1 = np.sqrt(6.0 * (x.size - 2) / ((x.size + 1.0) * (x.size + 3))) sigma = np.std(x) if sigma > 0.0: # These three operations add up to # g1 = np.mean(((x - np.mean(x)) / sigma)*3) # but use only one temp array instead of three temp = x - np.mean(x) np.true_divide(temp, sigma, temp) np.power(temp, 3, temp) g1 = np.mean(temp) return _ptp(x) / (1.0 + np.log2(x.size) + np.log2(1.0 + np.absolute(g1) / sg1)) return 0.0 def _hist_bin_fd(x, range): """ The Freedman-Diaconis histogram bin estimator. The Freedman-Diaconis rule uses interquartile range (IQR) to estimate binwidth. It is considered a variation of the Scott rule with more robustness as the IQR is less affected by outliers than the standard deviation. However, the IQR depends on fewer points than the standard deviation, so it is less accurate, especially for long tailed distributions. If the IQR is 0, this function returns 0 for the bin width. Binwidth is inversely proportional to the cube root of data size (asymptotically optimal). Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. """ del range # unused iqr = np.subtract(np.percentile(x, [75, 25])) return 2.0 * iqr * x.size ** (-1.0 / 3.0) def _hist_bin_auto(x, range): """ Histogram bin estimator that uses the minimum width of the Freedman-Diaconis and Sturges estimators if the FD bin width is non-zero. If the bin width from the FD estimator is 0, the Sturges estimator is used. The FD estimator is usually the most robust method, but its width estimate tends to be too large for small `x` and bad for data with limited variance. The Sturges estimator is quite good for small (<1000) datasets and is the default in the R language. This method gives good off-the-shelf behaviour. .. versionchanged:: 1.15.0 If there is limited variance the IQR can be 0, which results in the FD bin width being 0 too. This is not a valid bin width, so ``np.histogram_bin_edges`` chooses 1 bin instead, which may not be optimal. If the IQR is 0, it's unlikely any variance-based estimators will be of use, so we revert to the Sturges estimator, which only uses the size of the dataset in its calculation. Parameters ---------- x : array_like Input data that is to be histogrammed, trimmed to range. May not be empty. Returns ------- h : An estimate of the optimal bin width for the given data. See Also -------- _hist_bin_fd, _hist_bin_sturges """ fd_bw = _hist_bin_fd(x, range) sturges_bw = _hist_bin_sturges(x, range) del range # unused if fd_bw: return min(fd_bw, sturges_bw) else: # limited variance, so we return a len dependent bw estimator return sturges_bw # Private dict initialized at module load time _hist_bin_selectors = {'stone': _hist_bin_stone, 'auto': _hist_bin_auto, 'doane': _hist_bin_doane, 'fd': _hist_bin_fd, 'rice': _hist_bin_rice, 'scott': _hist_bin_scott, 'sqrt': _hist_bin_sqrt, 'sturges': _hist_bin_sturges} def _ravel_and_check_weights(a, weights): """ Check a and weights have matching shapes, and ravel both """ a = np.asarray(a) # Ensure that the array is a "subtractable" dtype if a.dtype == np.bool_: warnings.warn("Converting input from {} to {} for compatibility." .format(a.dtype, np.uint8), RuntimeWarning, stacklevel=3) a = a.astype(np.uint8) if weights is not None: weights = np.asarray(weights) if weights.shape != a.shape: raise ValueError( 'weights should have the same shape as a.') weights = weights.ravel() a = a.ravel() return a, weights def _get_outer_edges(a, range): """ Determine the outer bin edges to use, from either the data or the range argument """ if range is not None: first_edge, last_edge = range if first_edge > last_edge: raise ValueError( 'max must be larger than min in range parameter.') if not (np.isfinite(first_edge) and np.isfinite(last_edge)): raise ValueError( "supplied range of [{}, {}] is not finite".format(first_edge, last_edge)) elif a.size == 0: # handle empty arrays. Can't determine range, so use 0-1. first_edge, last_edge = 0, 1 else: first_edge, last_edge = a.min(), a.max() if not (np.isfinite(first_edge) and np.isfinite(last_edge)): raise ValueError( "autodetected range of [{}, {}] is not finite".format(first_edge, last_edge)) # expand empty range to avoid divide by zero if first_edge == last_edge: first_edge = first_edge - 0.5 last_edge = last_edge + 0.5 return first_edge, last_edge def _unsigned_subtract(a, b): """ Subtract two values where a >= b, and produce an unsigned result This is needed when finding the difference between the upper and lower bound of an int16 histogram """ # coerce to a single type signed_to_unsigned = { np.byte: np.ubyte, np.short: np.ushort, np.intc: np.uintc, np.int_: np.uint, np.longlong: np.ulonglong } dt = np.result_type(a, b) try: dt = signed_to_unsigned[dt.type] except KeyError: return np.subtract(a, b, dtype=dt) else: # we know the inputs are integers, and we are deliberately casting # signed to unsigned return np.subtract(a, b, casting='unsafe', dtype=dt) def _get_bin_edges(a, bins, range, weights): """ Computes the bins used internally by `histogram`. Parameters ========== a : ndarray Ravelled data array bins, range Forwarded arguments from `histogram`. weights : ndarray, optional Ravelled weights array, or None Returns ======= bin_edges : ndarray Array of bin edges uniform_bins : (Number, Number, int): The upper bound, lowerbound, and number of bins, used in the optimized implementation of `histogram` that works on uniform bins. """ # parse the overloaded bins argument n_equal_bins = None bin_edges = None if isinstance(bins, str): bin_name = bins # if `bins` is a string for an automatic method, # this will replace it with the number of bins calculated if bin_name not in _hist_bin_selectors: raise ValueError( "{!r} is not a valid estimator for `bins`".format(bin_name)) if weights is not None: raise TypeError("Automated estimation of the number of " "bins is not supported for weighted data") first_edge, last_edge = _get_outer_edges(a, range) # truncate the range if needed if range is not None: keep = (a >= first_edge) keep &= (a <= last_edge) if not np.logical_and.reduce(keep): a = a[keep] if a.size == 0: n_equal_bins = 1 else: # Do not call selectors on empty arrays width = _hist_bin_selectors[bin_name](a, (first_edge, last_edge)) if width: n_equal_bins = int(np.ceil(_unsigned_subtract(last_edge, first_edge) / width)) else: # Width can be zero for some estimators, e.g. FD when # the IQR of the data is zero. n_equal_bins = 1 elif np.ndim(bins) == 0: try: n_equal_bins = operator.index(bins) except TypeError as e: raise TypeError( '`bins` must be an integer, a string, or an array') from e if n_equal_bins < 1: raise ValueError('`bins` must be positive, when an integer') first_edge, last_edge = _get_outer_edges(a, range) elif np.ndim(bins) == 1: bin_edges = np.asarray(bins) if np.any(bin_edges[:-1] > bin_edges[1:]): raise ValueError( '`bins` must increase monotonically, when an array') else: raise ValueError('`bins` must be 1d, when an array') if n_equal_bins is not None: # gh-10322 means that type resolution rules are dependent on array # shapes. To avoid this causing problems, we pick a type now and stick # with it throughout. bin_type = np.result_type(first_edge, last_edge, a) if np.issubdtype(bin_type, np.integer): bin_type = np.result_type(bin_type, float) # bin edges must be computed bin_edges = np.linspace( first_edge, last_edge, n_equal_bins + 1, endpoint=True, dtype=bin_type) return bin_edges, (first_edge, last_edge, n_equal_bins) else: return bin_edges, None def _search_sorted_inclusive(a, v): """ Like `searchsorted`, but where the last item in `v` is placed on the right. In the context of a histogram, this makes the last bin edge inclusive """ return np.concatenate(( a.searchsorted(v[:-1], 'left'), a.searchsorted(v[-1:], 'right') )) def _histogram_bin_edges_dispatcher(a, bins=None, range=None, weights=None): return (a, bins, weights) @array_function_dispatch(_histogram_bin_edges_dispatcher) def histogram_bin_edges(a, bins=10, range=None, weights=None): r""" Function to calculate only the edges of the bins used by the `histogram` function. Parameters ---------- a : array_like Input data. The histogram is computed over the flattened array. bins : int or sequence of scalars or str, optional If `bins` is an int, it defines the number of equal-width bins in the given range (10, by default). If `bins` is a sequence, it defines the bin edges, including the rightmost edge, allowing for non-uniform bin widths. If `bins` is a string from the list below, `histogram_bin_edges` will use the method chosen to calculate the optimal bin width and consequently the number of bins (see `Notes` for more detail on the estimators) from the data that falls within the requested range. While the bin width will be optimal for the actual data in the range, the number of bins will be computed to fill the entire range, including the empty portions. For visualisation, using the 'auto' option is suggested. Weighted data is not supported for automated bin size selection. 'auto' Maximum of the 'sturges' and 'fd' estimators. Provides good all around performance. 'fd' (Freedman Diaconis Estimator) Robust (resilient to outliers) estimator that takes into account data variability and data size. 'doane' An improved version of Sturges' estimator that works better with non-normal datasets. 'scott' Less robust estimator that takes into account data variability and data size. 'stone' Estimator based on leave-one-out cross-validation estimate of the integrated squared error. Can be regarded as a generalization of Scott's rule. 'rice' Estimator does not take variability into account, only data size. Commonly overestimates number of bins required. 'sturges' R's default method, only accounts for data size. Only optimal for gaussian data and underestimates number of bins for large non-gaussian datasets. 'sqrt' Square root (of data size) estimator, used by Excel and other programs for its speed and simplicity. range : (float, float), optional The lower and upper range of the bins. If not provided, range is simply ``(a.min(), a.max())``. Values outside the range are ignored. The first element of the range must be less than or equal to the second. `range` affects the automatic bin computation as well. While bin width is computed to be optimal based on the actual data within `range`, the bin count will fill the entire range including portions containing no data. weights : array_like, optional An array of weights, of the same shape as `a`. Each value in `a` only contributes its associated weight towards the bin count (instead of 1). This is currently not used by any of the bin estimators, but may be in the future. Returns ------- bin_edges : array of dtype float The edges to pass into `histogram` See Also -------- histogram Notes ----- The methods to estimate the optimal number of bins are well founded in literature, and are inspired by the choices R provides for histogram visualisation. Note that having the number of bins proportional to :math:`n^{1/3}` is asymptotically optimal, which is why it appears in most estimators. These are simply plug-in methods that give good starting points for number of bins. In the equations below, :math:`h` is the binwidth and :math:`n_h` is the number of bins. All estimators that compute bin counts are recast to bin width using the `ptp` of the data. The final bin count is obtained from ``np.round(np.ceil(range / h))``. The final bin width is often less than what is returned by the estimators below. 'auto' (maximum of the 'sturges' and 'fd' estimators) A compromise to get a good value. For small datasets the Sturges value will usually be chosen, while larger datasets will usually default to FD. Avoids the overly conservative behaviour of FD and Sturges for small and large datasets respectively. Switchover point is usually :math:`a.size \approx 1000`. 'fd' (Freedman Diaconis Estimator) .. math:: h = 2 \frac{IQR}{n^{1/3}} The binwidth is proportional to the interquartile range (IQR) and inversely proportional to cube root of a.size. Can be too conservative for small datasets, but is quite good for large datasets. The IQR is very robust to outliers. 'scott' .. math:: h = \sigma \sqrt[3]{\frac{24 \sqrt{\pi}}{n}} The binwidth is proportional to the standard deviation of the data and inversely proportional to cube root of ``x.size``. Can be too conservative for small datasets, but is quite good for large datasets. The standard deviation is not very robust to outliers. Values are very similar to the Freedman-Diaconis estimator in the absence of outliers. 'rice' .. math:: n_h = 2n^{1/3} The number of bins is only proportional to cube root of ``a.size``. It tends to overestimate the number of bins and it does not take into account data variability. 'sturges' .. math:: n_h = \log _{2}(n) + 1 The number of bins is the base 2 log of ``a.size``. This estimator assumes normality of data and is too conservative for larger, non-normal datasets. This is the default method in R's ``hist`` method. 'doane' .. math:: n_h = 1 + \log_{2}(n) + \log_{2}\left(1 + \frac{\|g_1\|}{\sigma_{g_1}}\right) g_1 = mean\left[\left(\frac{x - \mu}{\sigma}\right)^3\right] \sigma_{g_1} = \sqrt{\frac{6(n - 2)}{(n + 1)(n + 3)}} An improved version of Sturges' formula that produces better estimates for non-normal datasets. This estimator attempts to account for the skew of the data. 'sqrt' .. math:: n_h = \sqrt n The simplest and fastest estimator. Only takes into account the data size. Examples -------- >>> arr = np.array([0, 0, 0, 1, 2, 3, 3, 4, 5]) >>> np.histogram_bin_edges(arr, bins='auto', range=(0, 1)) array([0. , 0.25, 0.5 , 0.75, 1. ]) >>> np.histogram_bin_edges(arr, bins=2) array([0. , 2.5, 5. ]) For consistency with histogram, an array of pre-computed bins is passed through unmodified: >>> np.histogram_bin_edges(arr, [1, 2]) array([1, 2]) This function allows one set of bins to be computed, and reused across multiple histograms: >>> shared_bins = np.histogram_bin_edges(arr, bins='auto') >>> shared_bins array([0., 1., 2., 3., 4., 5.]) >>> group_id = np.array([0, 1, 1, 0, 1, 1, 0, 1, 1]) >>> hist_0, _ = np.histogram(arr[group_id == 0], bins=shared_bins) >>> hist_1, _ = np.histogram(arr[group_id == 1], bins=shared_bins) >>> hist_0; hist_1 array([1, 1, 0, 1, 0]) array([2, 0, 1, 1, 2]) Which gives more easily comparable results than using separate bins for each histogram: >>> hist_0, bins_0 = np.histogram(arr[group_id == 0], bins='auto') >>> hist_1, bins_1 = np.histogram(arr[group_id == 1], bins='auto') >>> hist_0; hist_1 array([1, 1, 1]) array([2, 1, 1, 2]) >>> bins_0; bins_1 array([0., 1., 2., 3.]) array([0. , 1.25, 2.5 , 3.75, 5. ]) """ a, weights = _ravel_and_check_weights(a, weights) bin_edges, _ = _get_bin_edges(a, bins, range, weights) return bin_edges def _histogram_dispatcher( a, bins=None, range=None, density=None, weights=None): return (a, bins, weights) @array_function_dispatch(_histogram_dispatcher) def histogram(a, bins=10, range=None, density=None, weights=None): r""" Compute the histogram of a dataset. Parameters ---------- a : array_like Input data. The histogram is computed over the flattened array. bins : int or sequence of scalars or str, optional If `bins` is an int, it defines the number of equal-width bins in the given range (10, by default). If `bins` is a sequence, it defines a monotonically increasing array of bin edges, including the rightmost edge, allowing for non-uniform bin widths. .. versionadded:: 1.11.0 If `bins` is a string, it defines the method used to calculate the optimal bin width, as defined by `histogram_bin_edges`. range : (float, float), optional The lower and upper range of the bins. If not provided, range is simply ``(a.min(), a.max())``. Values outside the range are ignored. The first element of the range must be less than or equal to the second. `range` affects the automatic bin computation as well. While bin width is computed to be optimal based on the actual data within `range`, the bin count will fill the entire range including portions containing no data. weights : array_like, optional An array of weights, of the same shape as `a`. Each value in `a` only contributes its associated weight towards the bin count (instead of 1). If `density` is True, the weights are normalized, so that the integral of the density over the range remains 1. density : bool, optional If ``False``, the result will contain the number of samples in each bin. If ``True``, the result is the value of the probability density function at the bin, normalized such that the integral over the range is 1. Note that the sum of the histogram values will not be equal to 1 unless bins of unity width are chosen; it is not a probability mass function. Returns ------- hist : array The values of the histogram. See `density` and `weights` for a description of the possible semantics. bin_edges : array of dtype float Return the bin edges ``(length(hist)+1)``. See Also -------- histogramdd, bincount, searchsorted, digitize, histogram_bin_edges Notes ----- All but the last (righthand-most) bin is half-open. In other words, if `bins` is:: [1, 2, 3, 4] then the first bin is ``[1, 2)`` (including 1, but excluding 2) and the second ``[2, 3)``. The last bin, however, is ``[3, 4]``, which includes 4. Examples -------- >>> np.histogram([1, 2, 1], bins=[0, 1, 2, 3]) (array([0, 2, 1]), array([0, 1, 2, 3])) >>> np.histogram(np.arange(4), bins=np.arange(5), density=True) (array([0.25, 0.25, 0.25, 0.25]), array([0, 1, 2, 3, 4])) >>> np.histogram([[1, 2, 1], [1, 0, 1]], bins=[0,1,2,3]) (array([1, 4, 1]), array([0, 1, 2, 3])) >>> a = np.arange(5) >>> hist, bin_edges = np.histogram(a, density=True) >>> hist array([0.5, 0. , 0.5, 0. , 0. , 0.5, 0. , 0.5, 0. , 0.5]) >>> hist.sum() 2.4999999999999996 >>> np.sum(hist * np.diff(bin_edges)) 1.0 .. versionadded:: 1.11.0 Automated Bin Selection Methods example, using 2 peak random data with 2000 points: >>> import matplotlib.pyplot as plt >>> rng = np.random.RandomState(10) # deterministic random data >>> a = np.hstack((rng.normal(size=1000), ... rng.normal(loc=5, scale=2, size=1000))) >>> _ = plt.hist(a, bins='auto') # arguments are passed to np.histogram >>> plt.title("Histogram with 'auto' bins") Text(0.5, 1.0, "Histogram with 'auto' bins") >>> plt.show() """ a, weights = _ravel_and_check_weights(a, weights) bin_edges, uniform_bins = _get_bin_edges(a, bins, range, weights) # Histogram is an integer or a float array depending on the weights. if weights is None: ntype = np.dtype(np.intp) else: ntype = weights.dtype # We set a block size, as this allows us to iterate over chunks when # computing histograms, to minimize memory usage. BLOCK = 65536 # The fast path uses bincount, but that only works for certain types # of weight simple_weights = ( weights is None or np.can_cast(weights.dtype, np.double) or np.can_cast(weights.dtype, complex) ) if uniform_bins is not None and simple_weights: # Fast algorithm for equal bins # We now convert values of a to bin indices, under the assumption of # equal bin widths (which is valid here). first_edge, last_edge, n_equal_bins = uniform_bins # Initialize empty histogram n = np.zeros(n_equal_bins, ntype) # Pre-compute histogram scaling factor norm = n_equal_bins / _unsigned_subtract(last_edge, first_edge) # We iterate over blocks here for two reasons: the first is that for # large arrays, it is actually faster (for example for a 10^8 array it # is 2x as fast) and it results in a memory footprint 3x lower in the # limit of large arrays. for i in _range(0, len(a), BLOCK): tmp_a = a[i:i+BLOCK] if weights is None: tmp_w = None else: tmp_w = weights[i:i + BLOCK] # Only include values in the right range keep = (tmp_a >= first_edge) keep &= (tmp_a <= last_edge) if not np.logical_and.reduce(keep): tmp_a = tmp_a[keep] if tmp_w is not None: tmp_w = tmp_w[keep] # This cast ensures no type promotions occur below, which gh-10322 # make unpredictable. Getting it wrong leads to precision errors # like gh-8123. tmp_a = tmp_a.astype(bin_edges.dtype, copy=False) # Compute the bin indices, and for values that lie exactly on # last_edge we need to subtract one f_indices = _unsigned_subtract(tmp_a, first_edge) * norm indices = f_indices.astype(np.intp) indices[indices == n_equal_bins] -= 1 # The index computation is not guaranteed to give exactly # consistent results within ~1 ULP of the bin edges. decrement = tmp_a < bin_edges[indices] indices[decrement] -= 1 # The last bin includes the right edge. The other bins do not. increment = ((tmp_a >= bin_edges[indices + 1]) & (indices != n_equal_bins - 1)) indices[increment] += 1 # We now compute the histogram using bincount if ntype.kind == 'c': n.real += np.bincount(indices, weights=tmp_w.real, minlength=n_equal_bins) n.imag += np.bincount(indices, weights=tmp_w.imag, minlength=n_equal_bins) else: n += np.bincount(indices, weights=tmp_w, minlength=n_equal_bins).astype(ntype) else: # Compute via cumulative histogram cum_n = np.zeros(bin_edges.shape, ntype) if weights is None: for i in _range(0, len(a), BLOCK): sa = np.sort(a[i:i+BLOCK]) cum_n += _search_sorted_inclusive(sa, bin_edges) else: zero = np.zeros(1, dtype=ntype) for i in _range(0, len(a), BLOCK): tmp_a = a[i:i+BLOCK] tmp_w = weights[i:i+BLOCK] sorting_index = np.argsort(tmp_a) sa = tmp_a[sorting_index] sw = tmp_w[sorting_index] cw = np.concatenate((zero, sw.cumsum())) bin_index = _search_sorted_inclusive(sa, bin_edges) cum_n += cw[bin_index] n = np.diff(cum_n) if density: db = np.array(np.diff(bin_edges), float) return n/db/n.sum(), bin_edges return n, bin_edges def _histogramdd_dispatcher(sample, bins=None, range=None, density=None, weights=None): if hasattr(sample, 'shape'): # same condition as used in histogramdd yield sample else: yield from sample with contextlib.suppress(TypeError): yield from bins yield weights @array_function_dispatch(_histogramdd_dispatcher) def histogramdd(sample, bins=10, range=None, density=None, weights=None): """ Compute the multidimensional histogram of some data. Parameters ---------- sample : (N, D) array, or (N, D) array_like The data to be histogrammed. Note the unusual interpretation of sample when an array_like: * When an array, each row is a coordinate in a D-dimensional space - such as ``histogramdd(np.array([p1, p2, p3]))``. * When an array_like, each element is the list of values for single coordinate - such as ``histogramdd((X, Y, Z))``. The first form should be preferred. bins : sequence or int, optional The bin specification: * A sequence of arrays describing the monotonically increasing bin edges along each dimension. * The number of bins for each dimension (nx, ny, ... =bins) * The number of bins for all dimensions (nx=ny=...=bins). range : sequence, optional A sequence of length D, each an optional (lower, upper) tuple giving the outer bin edges to be used if the edges are not given explicitly in `bins`. An entry of None in the sequence results in the minimum and maximum values being used for the corresponding dimension. The default, None, is equivalent to passing a tuple of D None values. density : bool, optional If False, the default, returns the number of samples in each bin. If True, returns the probability density function at the bin, ``bin_count / sample_count / bin_volume``. weights : (N,) array_like, optional An array of values `w_i` weighing each sample `(x_i, y_i, z_i, ...)`. Weights are normalized to 1 if density is True. If density is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin. Returns ------- H : ndarray The multidimensional histogram of sample x. See density and weights for the different possible semantics. edges : list A list of D arrays describing the bin edges for each dimension. See Also -------- histogram: 1-D histogram histogram2d: 2-D histogram Examples -------- >>> r = np.random.randn(100,3) >>> H, edges = np.histogramdd(r, bins = (5, 8, 4)) >>> H.shape, edges[0].size, edges[1].size, edges[2].size ((5, 8, 4), 6, 9, 5) """ try: # Sample is an ND-array. N, D = sample.shape except (AttributeError, ValueError): # Sample is a sequence of 1D arrays. sample = np.atleast_2d(sample).T N, D = sample.shape nbin = np.empty(D, np.intp) edges = D[None] dedges = D[None] if weights is not None: weights = np.asarray(weights) try: M = len(bins) if M != D: raise ValueError( 'The dimension of bins must be equal to the dimension of the ' 'sample x.') except TypeError: # bins is an integer bins = D[bins] # normalize the range argument if range is None: range = (None,) D elif len(range) != D: raise ValueError('range argument must have one entry per dimension') # Create edge arrays for i in _range(D): if np.ndim(bins[i]) == 0: if bins[i] < 1: raise ValueError( '`bins[{}]` must be positive, when an integer'.format(i)) smin, smax = _get_outer_edges(sample[:,i], range[i]) try: n = operator.index(bins[i]) except TypeError as e: raise TypeError( "`bins[{}]` must be an integer, when a scalar".format(i) ) from e edges[i] = np.linspace(smin, smax, n + 1) elif np.ndim(bins[i]) == 1: edges[i] = np.asarray(bins[i]) if np.any(edges[i][:-1] > edges[i][1:]): raise ValueError( '`bins[{}]` must be monotonically increasing, when an array' .format(i)) else: raise ValueError( '`bins[{}]` must be a scalar or 1d array'.format(i)) nbin[i] = len(edges[i]) + 1 # includes an outlier on each end dedges[i] = np.diff(edges[i]) # Compute the bin number each sample falls into. Ncount = tuple( # avoid np.digitize to work around gh-11022 np.searchsorted(edges[i], sample[:, i], side='right') for i in _range(D) ) # Using digitize, values that fall on an edge are put in the right bin. # For the rightmost bin, we want values equal to the right edge to be # counted in the last bin, and not as an outlier. for i in _range(D): # Find which points are on the rightmost edge. on_edge = (sample[:, i] == edges[i][-1]) # Shift these points one bin to the left. Ncount[i][on_edge] -= 1 # Compute the sample indices in the flattened histogram matrix. # This raises an error if the array is too large. xy = np.ravel_multi_index(Ncount, nbin) # Compute the number of repetitions in xy and assign it to the # flattened histmat. hist = np.bincount(xy, weights, minlength=nbin.prod()) # Shape into a proper matrix hist = hist.reshape(nbin) # This preserves the (bad) behavior observed in gh-7845, for now. hist = hist.astype(float, casting='safe') # Remove outliers (indices 0 and -1 for each dimension). core = D*(slice(1, -1),) hist = hist[core] if density: # calculate the probability density function s = hist.sum() for i in _range(D): shape = np.ones(D, int) shape[i] = nbin[i] - 2 hist = hist / dedges[i].reshape(shape) hist /= s if (hist.shape != nbin - 2).any(): raise RuntimeError( "Internal Shape Error") return hist, edges	36.81 KB	2026-01-20 12:58
📄 histograms.pyi from collections.abc import Sequence from typing import ( Literal as L, Any, SupportsIndex, ) from numpy._typing import ( NDArray, ArrayLike, ) _BinKind = L[ "stone", "auto", "doane", "fd", "rice", "scott", "sqrt", "sturges", ] __all__: list[str] def histogram_bin_edges( a: ArrayLike, bins: _BinKind \| SupportsIndex \| ArrayLike = ..., range: None \| tuple[float, float] = ..., weights: None \| ArrayLike = ..., ) -> NDArray[Any]: ... def histogram( a: ArrayLike, bins: _BinKind \| SupportsIndex \| ArrayLike = ..., range: None \| tuple[float, float] = ..., density: bool = ..., weights: None \| ArrayLike = ..., ) -> tuple[NDArray[Any], NDArray[Any]]: ... def histogramdd( sample: ArrayLike, bins: SupportsIndex \| ArrayLike = ..., range: Sequence[tuple[float, float]] = ..., density: None \| bool = ..., weights: None \| ArrayLike = ..., ) -> tuple[NDArray[Any], list[NDArray[Any]]]: ...	995 B	2026-01-20 12:58
📄 index_tricks.py import functools import sys import math import warnings import numpy as np from .._utils import set_module import numpy.core.numeric as _nx from numpy.core.numeric import ScalarType, array from numpy.core.numerictypes import issubdtype import numpy.matrixlib as matrixlib from .function_base import diff from numpy.core.multiarray import ravel_multi_index, unravel_index from numpy.core import overrides, linspace from numpy.lib.stride_tricks import as_strided array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') __all__ = [ 'ravel_multi_index', 'unravel_index', 'mgrid', 'ogrid', 'r_', 'c_', 's_', 'index_exp', 'ix_', 'ndenumerate', 'ndindex', 'fill_diagonal', 'diag_indices', 'diag_indices_from' ] def _ix__dispatcher(args): return args @array_function_dispatch(_ix__dispatcher) def ix_(args): """ Construct an open mesh from multiple sequences. This function takes N 1-D sequences and returns N outputs with N dimensions each, such that the shape is 1 in all but one dimension and the dimension with the non-unit shape value cycles through all N dimensions. Using `ix_` one can quickly construct index arrays that will index the cross product. ``a[np.ix_([1,3],[2,5])]`` returns the array ``[[a[1,2] a[1,5]], [a[3,2] a[3,5]]]``. Parameters ---------- args : 1-D sequences Each sequence should be of integer or boolean type. Boolean sequences will be interpreted as boolean masks for the corresponding dimension (equivalent to passing in ``np.nonzero(boolean_sequence)``). Returns ------- out : tuple of ndarrays N arrays with N dimensions each, with N the number of input sequences. Together these arrays form an open mesh. See Also -------- ogrid, mgrid, meshgrid Examples -------- >>> a = np.arange(10).reshape(2, 5) >>> a array([[0, 1, 2, 3, 4], [5, 6, 7, 8, 9]]) >>> ixgrid = np.ix_([0, 1], [2, 4]) >>> ixgrid (array([[0], [1]]), array([[2, 4]])) >>> ixgrid[0].shape, ixgrid[1].shape ((2, 1), (1, 2)) >>> a[ixgrid] array([[2, 4], [7, 9]]) >>> ixgrid = np.ix_([True, True], [2, 4]) >>> a[ixgrid] array([[2, 4], [7, 9]]) >>> ixgrid = np.ix_([True, True], [False, False, True, False, True]) >>> a[ixgrid] array([[2, 4], [7, 9]]) """ out = [] nd = len(args) for k, new in enumerate(args): if not isinstance(new, _nx.ndarray): new = np.asarray(new) if new.size == 0: # Explicitly type empty arrays to avoid float default new = new.astype(_nx.intp) if new.ndim != 1: raise ValueError("Cross index must be 1 dimensional") if issubdtype(new.dtype, _nx.bool_): new, = new.nonzero() new = new.reshape((1,)k + (new.size,) + (1,)(nd-k-1)) out.append(new) return tuple(out) class nd_grid: """ Construct a multi-dimensional "meshgrid". ``grid = nd_grid()`` creates an instance which will return a mesh-grid when indexed. The dimension and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive. However, if the step length is a complex number (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value is inclusive. If instantiated with an argument of ``sparse=True``, the mesh-grid is open (or not fleshed out) so that only one-dimension of each returned argument is greater than 1. Parameters ---------- sparse : bool, optional Whether the grid is sparse or not. Default is False. Notes ----- Two instances of `nd_grid` are made available in the NumPy namespace, `mgrid` and `ogrid`, approximately defined as:: mgrid = nd_grid(sparse=False) ogrid = nd_grid(sparse=True) Users should use these pre-defined instances instead of using `nd_grid` directly. """ def __init__(self, sparse=False): self.sparse = sparse def __getitem__(self, key): try: size = [] # Mimic the behavior of `np.arange` and use a data type # which is at least as large as `np.int_` num_list = [0] for k in range(len(key)): step = key[k].step start = key[k].start stop = key[k].stop if start is None: start = 0 if step is None: step = 1 if isinstance(step, (_nx.complexfloating, complex)): step = abs(step) size.append(int(step)) else: size.append( int(math.ceil((stop - start) / (step1.0)))) num_list += [start, stop, step] typ = _nx.result_type(num_list) if self.sparse: nn = [_nx.arange(_x, dtype=_t) for _x, _t in zip(size, (typ,)len(size))] else: nn = _nx.indices(size, typ) for k, kk in enumerate(key): step = kk.step start = kk.start if start is None: start = 0 if step is None: step = 1 if isinstance(step, (_nx.complexfloating, complex)): step = int(abs(step)) if step != 1: step = (kk.stop - start) / float(step - 1) nn[k] = (nn[k]step+start) if self.sparse: slobj = [_nx.newaxis]len(size) for k in range(len(size)): slobj[k] = slice(None, None) nn[k] = nn[k][tuple(slobj)] slobj[k] = _nx.newaxis return nn except (IndexError, TypeError): step = key.step stop = key.stop start = key.start if start is None: start = 0 if isinstance(step, (_nx.complexfloating, complex)): # Prevent the (potential) creation of integer arrays step_float = abs(step) step = length = int(step_float) if step != 1: step = (key.stop-start)/float(step-1) typ = _nx.result_type(start, stop, step_float) return _nx.arange(0, length, 1, dtype=typ)step + start else: return _nx.arange(start, stop, step) class MGridClass(nd_grid): """ An instance which returns a dense multi-dimensional "meshgrid". An instance which returns a dense (or fleshed out) mesh-grid when indexed, so that each returned argument has the same shape. The dimensions and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive. However, if the step length is a complex number (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value is inclusive. Returns ------- mesh-grid `ndarrays` all of the same dimensions See Also -------- ogrid : like `mgrid` but returns open (not fleshed out) mesh grids meshgrid: return coordinate matrices from coordinate vectors r_ : array concatenator :ref:`how-to-partition` Examples -------- >>> np.mgrid[0:5, 0:5] array([[[0, 0, 0, 0, 0], [1, 1, 1, 1, 1], [2, 2, 2, 2, 2], [3, 3, 3, 3, 3], [4, 4, 4, 4, 4]], [[0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4], [0, 1, 2, 3, 4]]]) >>> np.mgrid[-1:1:5j] array([-1. , -0.5, 0. , 0.5, 1. ]) """ def __init__(self): super().__init__(sparse=False) mgrid = MGridClass() class OGridClass(nd_grid): """ An instance which returns an open multi-dimensional "meshgrid". An instance which returns an open (i.e. not fleshed out) mesh-grid when indexed, so that only one dimension of each returned array is greater than 1. The dimension and number of the output arrays are equal to the number of indexing dimensions. If the step length is not a complex number, then the stop is not inclusive. However, if the step length is a complex number (e.g. 5j), then the integer part of its magnitude is interpreted as specifying the number of points to create between the start and stop values, where the stop value is inclusive. Returns ------- mesh-grid `ndarrays` with only one dimension not equal to 1 See Also -------- mgrid : like `ogrid` but returns dense (or fleshed out) mesh grids meshgrid: return coordinate matrices from coordinate vectors r_ : array concatenator :ref:`how-to-partition` Examples -------- >>> from numpy import ogrid >>> ogrid[-1:1:5j] array([-1. , -0.5, 0. , 0.5, 1. ]) >>> ogrid[0:5,0:5] [array([[0], [1], [2], [3], [4]]), array([[0, 1, 2, 3, 4]])] """ def __init__(self): super().__init__(sparse=True) ogrid = OGridClass() class AxisConcatenator: """ Translates slice objects to concatenation along an axis. For detailed documentation on usage, see `r_`. """ # allow ma.mr_ to override this concatenate = staticmethod(_nx.concatenate) makemat = staticmethod(matrixlib.matrix) def __init__(self, axis=0, matrix=False, ndmin=1, trans1d=-1): self.axis = axis self.matrix = matrix self.trans1d = trans1d self.ndmin = ndmin def __getitem__(self, key): # handle matrix builder syntax if isinstance(key, str): frame = sys._getframe().f_back mymat = matrixlib.bmat(key, frame.f_globals, frame.f_locals) return mymat if not isinstance(key, tuple): key = (key,) # copy attributes, since they can be overridden in the first argument trans1d = self.trans1d ndmin = self.ndmin matrix = self.matrix axis = self.axis objs = [] # dtypes or scalars for weak scalar handling in result_type result_type_objs = [] for k, item in enumerate(key): scalar = False if isinstance(item, slice): step = item.step start = item.start stop = item.stop if start is None: start = 0 if step is None: step = 1 if isinstance(step, (_nx.complexfloating, complex)): size = int(abs(step)) newobj = linspace(start, stop, num=size) else: newobj = _nx.arange(start, stop, step) if ndmin > 1: newobj = array(newobj, copy=False, ndmin=ndmin) if trans1d != -1: newobj = newobj.swapaxes(-1, trans1d) elif isinstance(item, str): if k != 0: raise ValueError("special directives must be the " "first entry.") if item in ('r', 'c'): matrix = True col = (item == 'c') continue if ',' in item: vec = item.split(',') try: axis, ndmin = [int(x) for x in vec[:2]] if len(vec) == 3: trans1d = int(vec[2]) continue except Exception as e: raise ValueError( "unknown special directive {!r}".format(item) ) from e try: axis = int(item) continue except (ValueError, TypeError) as e: raise ValueError("unknown special directive") from e elif type(item) in ScalarType: scalar = True newobj = item else: item_ndim = np.ndim(item) newobj = array(item, copy=False, subok=True, ndmin=ndmin) if trans1d != -1 and item_ndim < ndmin: k2 = ndmin - item_ndim k1 = trans1d if k1 < 0: k1 += k2 + 1 defaxes = list(range(ndmin)) axes = defaxes[:k1] + defaxes[k2:] + defaxes[k1:k2] newobj = newobj.transpose(axes) objs.append(newobj) if scalar: result_type_objs.append(item) else: result_type_objs.append(newobj.dtype) # Ensure that scalars won't up-cast unless warranted, for 0, drops # through to error in concatenate. if len(result_type_objs) != 0: final_dtype = _nx.result_type(result_type_objs) # concatenate could do cast, but that can be overriden: objs = [array(obj, copy=False, subok=True, ndmin=ndmin, dtype=final_dtype) for obj in objs] res = self.concatenate(tuple(objs), axis=axis) if matrix: oldndim = res.ndim res = self.makemat(res) if oldndim == 1 and col: res = res.T return res def __len__(self): return 0 # separate classes are used here instead of just making r_ = concatentor(0), # etc. because otherwise we couldn't get the doc string to come out right # in help(r_) class RClass(AxisConcatenator): """ Translates slice objects to concatenation along the first axis. This is a simple way to build up arrays quickly. There are two use cases. 1. If the index expression contains comma separated arrays, then stack them along their first axis. 2. If the index expression contains slice notation or scalars then create a 1-D array with a range indicated by the slice notation. If slice notation is used, the syntax ``start:stop:step`` is equivalent to ``np.arange(start, stop, step)`` inside of the brackets. However, if ``step`` is an imaginary number (i.e. 100j) then its integer portion is interpreted as a number-of-points desired and the start and stop are inclusive. In other words ``start:stop:stepj`` is interpreted as ``np.linspace(start, stop, step, endpoint=1)`` inside of the brackets. After expansion of slice notation, all comma separated sequences are concatenated together. Optional character strings placed as the first element of the index expression can be used to change the output. The strings 'r' or 'c' result in matrix output. If the result is 1-D and 'r' is specified a 1 x N (row) matrix is produced. If the result is 1-D and 'c' is specified, then a N x 1 (column) matrix is produced. If the result is 2-D then both provide the same matrix result. A string integer specifies which axis to stack multiple comma separated arrays along. A string of two comma-separated integers allows indication of the minimum number of dimensions to force each entry into as the second integer (the axis to concatenate along is still the first integer). A string with three comma-separated integers allows specification of the axis to concatenate along, the minimum number of dimensions to force the entries to, and which axis should contain the start of the arrays which are less than the specified number of dimensions. In other words the third integer allows you to specify where the 1's should be placed in the shape of the arrays that have their shapes upgraded. By default, they are placed in the front of the shape tuple. The third argument allows you to specify where the start of the array should be instead. Thus, a third argument of '0' would place the 1's at the end of the array shape. Negative integers specify where in the new shape tuple the last dimension of upgraded arrays should be placed, so the default is '-1'. Parameters ---------- Not a function, so takes no parameters Returns ------- A concatenated ndarray or matrix. See Also -------- concatenate : Join a sequence of arrays along an existing axis. c_ : Translates slice objects to concatenation along the second axis. Examples -------- >>> np.r_[np.array([1,2,3]), 0, 0, np.array([4,5,6])] array([1, 2, 3, ..., 4, 5, 6]) >>> np.r_[-1:1:6j, [0]3, 5, 6] array([-1. , -0.6, -0.2, 0.2, 0.6, 1. , 0. , 0. , 0. , 5. , 6. ]) String integers specify the axis to concatenate along or the minimum number of dimensions to force entries into. >>> a = np.array([[0, 1, 2], [3, 4, 5]]) >>> np.r_['-1', a, a] # concatenate along last axis array([[0, 1, 2, 0, 1, 2], [3, 4, 5, 3, 4, 5]]) >>> np.r_['0,2', [1,2,3], [4,5,6]] # concatenate along first axis, dim>=2 array([[1, 2, 3], [4, 5, 6]]) >>> np.r_['0,2,0', [1,2,3], [4,5,6]] array([[1], [2], [3], [4], [5], [6]]) >>> np.r_['1,2,0', [1,2,3], [4,5,6]] array([[1, 4], [2, 5], [3, 6]]) Using 'r' or 'c' as a first string argument creates a matrix. >>> np.r_['r',[1,2,3], [4,5,6]] matrix([[1, 2, 3, 4, 5, 6]]) """ def __init__(self): AxisConcatenator.__init__(self, 0) r_ = RClass() class CClass(AxisConcatenator): """ Translates slice objects to concatenation along the second axis. This is short-hand for ``np.r_['-1,2,0', index expression]``, which is useful because of its common occurrence. In particular, arrays will be stacked along their last axis after being upgraded to at least 2-D with 1's post-pended to the shape (column vectors made out of 1-D arrays). See Also -------- column_stack : Stack 1-D arrays as columns into a 2-D array. r_ : For more detailed documentation. Examples -------- >>> np.c_[np.array([1,2,3]), np.array([4,5,6])] array([[1, 4], [2, 5], [3, 6]]) >>> np.c_[np.array([[1,2,3]]), 0, 0, np.array([[4,5,6]])] array([[1, 2, 3, ..., 4, 5, 6]]) """ def __init__(self): AxisConcatenator.__init__(self, -1, ndmin=2, trans1d=0) c_ = CClass() @set_module('numpy') class ndenumerate: """ Multidimensional index iterator. Return an iterator yielding pairs of array coordinates and values. Parameters ---------- arr : ndarray Input array. See Also -------- ndindex, flatiter Examples -------- >>> a = np.array([[1, 2], [3, 4]]) >>> for index, x in np.ndenumerate(a): ... print(index, x) (0, 0) 1 (0, 1) 2 (1, 0) 3 (1, 1) 4 """ def __init__(self, arr): self.iter = np.asarray(arr).flat def __next__(self): """ Standard iterator method, returns the index tuple and array value. Returns ------- coords : tuple of ints The indices of the current iteration. val : scalar The array element of the current iteration. """ return self.iter.coords, next(self.iter) def __iter__(self): return self @set_module('numpy') class ndindex: """ An N-dimensional iterator object to index arrays. Given the shape of an array, an `ndindex` instance iterates over the N-dimensional index of the array. At each iteration a tuple of indices is returned, the last dimension is iterated over first. Parameters ---------- shape : ints, or a single tuple of ints The size of each dimension of the array can be passed as individual parameters or as the elements of a tuple. See Also -------- ndenumerate, flatiter Examples -------- Dimensions as individual arguments >>> for index in np.ndindex(3, 2, 1): ... print(index) (0, 0, 0) (0, 1, 0) (1, 0, 0) (1, 1, 0) (2, 0, 0) (2, 1, 0) Same dimensions - but in a tuple ``(3, 2, 1)`` >>> for index in np.ndindex((3, 2, 1)): ... print(index) (0, 0, 0) (0, 1, 0) (1, 0, 0) (1, 1, 0) (2, 0, 0) (2, 1, 0) """ def __init__(self, shape): if len(shape) == 1 and isinstance(shape[0], tuple): shape = shape[0] x = as_strided(_nx.zeros(1), shape=shape, strides=_nx.zeros_like(shape)) self._it = _nx.nditer(x, flags=['multi_index', 'zerosize_ok'], order='C') def __iter__(self): return self def ndincr(self): """ Increment the multi-dimensional index by one. This method is for backward compatibility only: do not use. .. deprecated:: 1.20.0 This method has been advised against since numpy 1.8.0, but only started emitting DeprecationWarning as of this version. """ # NumPy 1.20.0, 2020-09-08 warnings.warn( "`ndindex.ndincr()` is deprecated, use `next(ndindex)` instead", DeprecationWarning, stacklevel=2) next(self) def __next__(self): """ Standard iterator method, updates the index and returns the index tuple. Returns ------- val : tuple of ints Returns a tuple containing the indices of the current iteration. """ next(self._it) return self._it.multi_index # You can do all this with slice() plus a few special objects, # but there's a lot to remember. This version is simpler because # it uses the standard array indexing syntax. # # Written by Konrad Hinsen <hinsen@cnrs-orleans.fr> # last revision: 1999-7-23 # # Cosmetic changes by T. Oliphant 2001 # # class IndexExpression: """ A nicer way to build up index tuples for arrays. .. note:: Use one of the two predefined instances `index_exp` or `s_` rather than directly using `IndexExpression`. For any index combination, including slicing and axis insertion, ``a[indices]`` is the same as ``a[np.index_exp[indices]]`` for any array `a`. However, ``np.index_exp[indices]`` can be used anywhere in Python code and returns a tuple of slice objects that can be used in the construction of complex index expressions. Parameters ---------- maketuple : bool If True, always returns a tuple. See Also -------- index_exp : Predefined instance that always returns a tuple: `index_exp = IndexExpression(maketuple=True)`. s_ : Predefined instance without tuple conversion: `s_ = IndexExpression(maketuple=False)`. Notes ----- You can do all this with `slice()` plus a few special objects, but there's a lot to remember and this version is simpler because it uses the standard array indexing syntax. Examples -------- >>> np.s_[2::2] slice(2, None, 2) >>> np.index_exp[2::2] (slice(2, None, 2),) >>> np.array([0, 1, 2, 3, 4])[np.s_[2::2]] array([2, 4]) """ def __init__(self, maketuple): self.maketuple = maketuple def __getitem__(self, item): if self.maketuple and not isinstance(item, tuple): return (item,) else: return item index_exp = IndexExpression(maketuple=True) s_ = IndexExpression(maketuple=False) # End contribution from Konrad. # The following functions complement those in twodim_base, but are # applicable to N-dimensions. def _fill_diagonal_dispatcher(a, val, wrap=None): return (a,) @array_function_dispatch(_fill_diagonal_dispatcher) def fill_diagonal(a, val, wrap=False): """Fill the main diagonal of the given array of any dimensionality. For an array `a` with ``a.ndim >= 2``, the diagonal is the list of locations with indices ``a[i, ..., i]`` all identical. This function modifies the input array in-place, it does not return a value. Parameters ---------- a : array, at least 2-D. Array whose diagonal is to be filled, it gets modified in-place. val : scalar or array_like Value(s) to write on the diagonal. If `val` is scalar, the value is written along the diagonal. If array-like, the flattened `val` is written along the diagonal, repeating if necessary to fill all diagonal entries. wrap : bool For tall matrices in NumPy version up to 1.6.2, the diagonal "wrapped" after N columns. You can have this behavior with this option. This affects only tall matrices. See also -------- diag_indices, diag_indices_from Notes ----- .. versionadded:: 1.4.0 This functionality can be obtained via `diag_indices`, but internally this version uses a much faster implementation that never constructs the indices and uses simple slicing. Examples -------- >>> a = np.zeros((3, 3), int) >>> np.fill_diagonal(a, 5) >>> a array([[5, 0, 0], [0, 5, 0], [0, 0, 5]]) The same function can operate on a 4-D array: >>> a = np.zeros((3, 3, 3, 3), int) >>> np.fill_diagonal(a, 4) We only show a few blocks for clarity: >>> a[0, 0] array([[4, 0, 0], [0, 0, 0], [0, 0, 0]]) >>> a[1, 1] array([[0, 0, 0], [0, 4, 0], [0, 0, 0]]) >>> a[2, 2] array([[0, 0, 0], [0, 0, 0], [0, 0, 4]]) The wrap option affects only tall matrices: >>> # tall matrices no wrap >>> a = np.zeros((5, 3), int) >>> np.fill_diagonal(a, 4) >>> a array([[4, 0, 0], [0, 4, 0], [0, 0, 4], [0, 0, 0], [0, 0, 0]]) >>> # tall matrices wrap >>> a = np.zeros((5, 3), int) >>> np.fill_diagonal(a, 4, wrap=True) >>> a array([[4, 0, 0], [0, 4, 0], [0, 0, 4], [0, 0, 0], [4, 0, 0]]) >>> # wide matrices >>> a = np.zeros((3, 5), int) >>> np.fill_diagonal(a, 4, wrap=True) >>> a array([[4, 0, 0, 0, 0], [0, 4, 0, 0, 0], [0, 0, 4, 0, 0]]) The anti-diagonal can be filled by reversing the order of elements using either `numpy.flipud` or `numpy.fliplr`. >>> a = np.zeros((3, 3), int); >>> np.fill_diagonal(np.fliplr(a), [1,2,3]) # Horizontal flip >>> a array([[0, 0, 1], [0, 2, 0], [3, 0, 0]]) >>> np.fill_diagonal(np.flipud(a), [1,2,3]) # Vertical flip >>> a array([[0, 0, 3], [0, 2, 0], [1, 0, 0]]) Note that the order in which the diagonal is filled varies depending on the flip function. """ if a.ndim < 2: raise ValueError("array must be at least 2-d") end = None if a.ndim == 2: # Explicit, fast formula for the common case. For 2-d arrays, we # accept rectangular ones. step = a.shape[1] + 1 # This is needed to don't have tall matrix have the diagonal wrap. if not wrap: end = a.shape[1] a.shape[1] else: # For more than d=2, the strided formula is only valid for arrays with # all dimensions equal, so we check first. if not np.all(diff(a.shape) == 0): raise ValueError("All dimensions of input must be of equal length") step = 1 + (np.cumprod(a.shape[:-1])).sum() # Write the value out into the diagonal. a.flat[:end:step] = val @set_module('numpy') def diag_indices(n, ndim=2): """ Return the indices to access the main diagonal of an array. This returns a tuple of indices that can be used to access the main diagonal of an array `a` with ``a.ndim >= 2`` dimensions and shape (n, n, ..., n). For ``a.ndim = 2`` this is the usual diagonal, for ``a.ndim > 2`` this is the set of indices to access ``a[i, i, ..., i]`` for ``i = [0..n-1]``. Parameters ---------- n : int The size, along each dimension, of the arrays for which the returned indices can be used. ndim : int, optional The number of dimensions. See Also -------- diag_indices_from Notes ----- .. versionadded:: 1.4.0 Examples -------- Create a set of indices to access the diagonal of a (4, 4) array: >>> di = np.diag_indices(4) >>> di (array([0, 1, 2, 3]), array([0, 1, 2, 3])) >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) >>> a[di] = 100 >>> a array([[100, 1, 2, 3], [ 4, 100, 6, 7], [ 8, 9, 100, 11], [ 12, 13, 14, 100]]) Now, we create indices to manipulate a 3-D array: >>> d3 = np.diag_indices(2, 3) >>> d3 (array([0, 1]), array([0, 1]), array([0, 1])) And use it to set the diagonal of an array of zeros to 1: >>> a = np.zeros((2, 2, 2), dtype=int) >>> a[d3] = 1 >>> a array([[[1, 0], [0, 0]], [[0, 0], [0, 1]]]) """ idx = np.arange(n) return (idx,) * ndim def _diag_indices_from(arr): return (arr,) @array_function_dispatch(_diag_indices_from) def diag_indices_from(arr): """ Return the indices to access the main diagonal of an n-dimensional array. See `diag_indices` for full details. Parameters ---------- arr : array, at least 2-D See Also -------- diag_indices Notes ----- .. versionadded:: 1.4.0 Examples -------- Create a 4 by 4 array. >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Get the indices of the diagonal elements. >>> di = np.diag_indices_from(a) >>> di (array([0, 1, 2, 3]), array([0, 1, 2, 3])) >>> a[di] array([ 0, 5, 10, 15]) This is simply syntactic sugar for diag_indices. >>> np.diag_indices(a.shape[0]) (array([0, 1, 2, 3]), array([0, 1, 2, 3])) """ if not arr.ndim >= 2: raise ValueError("input array must be at least 2-d") # For more than d=2, the strided formula is only valid for arrays with # all dimensions equal, so we check first. if not np.all(diff(arr.shape) == 0): raise ValueError("All dimensions of input must be of equal length") return diag_indices(arr.shape[0], arr.ndim)	30.61 KB	2026-01-20 12:58
📄 index_tricks.pyi from collections.abc import Sequence from typing import ( Any, TypeVar, Generic, overload, Literal, SupportsIndex, ) from numpy import ( # Circumvent a naming conflict with `AxisConcatenator.matrix` matrix as _Matrix, ndenumerate as ndenumerate, ndindex as ndindex, ndarray, dtype, integer, str_, bytes_, bool_, int_, float_, complex_, intp, _OrderCF, _ModeKind, ) from numpy._typing import ( # Arrays ArrayLike, _NestedSequence, _FiniteNestedSequence, NDArray, _ArrayLikeInt, # DTypes DTypeLike, _SupportsDType, # Shapes _ShapeLike, ) from numpy.core.multiarray import ( unravel_index as unravel_index, ravel_multi_index as ravel_multi_index, ) _T = TypeVar("_T") _DType = TypeVar("_DType", bound=dtype[Any]) _BoolType = TypeVar("_BoolType", Literal[True], Literal[False]) _TupType = TypeVar("_TupType", bound=tuple[Any, ...]) _ArrayType = TypeVar("_ArrayType", bound=ndarray[Any, Any]) __all__: list[str] @overload def ix_(args: _FiniteNestedSequence[_SupportsDType[_DType]]) -> tuple[ndarray[Any, _DType], ...]: ... @overload def ix_(args: str \| _NestedSequence[str]) -> tuple[NDArray[str_], ...]: ... @overload def ix_(args: bytes \| _NestedSequence[bytes]) -> tuple[NDArray[bytes_], ...]: ... @overload def ix_(args: bool \| _NestedSequence[bool]) -> tuple[NDArray[bool_], ...]: ... @overload def ix_(args: int \| _NestedSequence[int]) -> tuple[NDArray[int_], ...]: ... @overload def ix_(args: float \| _NestedSequence[float]) -> tuple[NDArray[float_], ...]: ... @overload def ix_(args: complex \| _NestedSequence[complex]) -> tuple[NDArray[complex_], ...]: ... class nd_grid(Generic[_BoolType]): sparse: _BoolType def __init__(self, sparse: _BoolType = ...) -> None: ... @overload def __getitem__( self: nd_grid[Literal[False]], key: slice \| Sequence[slice], ) -> NDArray[Any]: ... @overload def __getitem__( self: nd_grid[Literal[True]], key: slice \| Sequence[slice], ) -> list[NDArray[Any]]: ... class MGridClass(nd_grid[Literal[False]]): def __init__(self) -> None: ... mgrid: MGridClass class OGridClass(nd_grid[Literal[True]]): def __init__(self) -> None: ... ogrid: OGridClass class AxisConcatenator: axis: int matrix: bool ndmin: int trans1d: int def __init__( self, axis: int = ..., matrix: bool = ..., ndmin: int = ..., trans1d: int = ..., ) -> None: ... @staticmethod @overload def concatenate( # type: ignore[misc] a: ArrayLike, axis: SupportsIndex = ..., out: None = ... ) -> NDArray[Any]: ... @staticmethod @overload def concatenate( *a: ArrayLike, axis: SupportsIndex = ..., out: _ArrayType = ... ) -> _ArrayType: ... @staticmethod def makemat( data: ArrayLike, dtype: DTypeLike = ..., copy: bool = ... ) -> _Matrix[Any, Any]: ... # TODO: Sort out this `__getitem__` method def __getitem__(self, key: Any) -> Any: ... class RClass(AxisConcatenator): axis: Literal[0] matrix: Literal[False] ndmin: Literal[1] trans1d: Literal[-1] def __init__(self) -> None: ... r_: RClass class CClass(AxisConcatenator): axis: Literal[-1] matrix: Literal[False] ndmin: Literal[2] trans1d: Literal[0] def __init__(self) -> None: ... c_: CClass class IndexExpression(Generic[_BoolType]): maketuple: _BoolType def __init__(self, maketuple: _BoolType) -> None: ... @overload def __getitem__(self, item: _TupType) -> _TupType: ... # type: ignore[misc] @overload def __getitem__(self: IndexExpression[Literal[True]], item: _T) -> tuple[_T]: ... @overload def __getitem__(self: IndexExpression[Literal[False]], item: _T) -> _T: ... index_exp: IndexExpression[Literal[True]] s_: IndexExpression[Literal[False]] def fill_diagonal(a: ndarray[Any, Any], val: Any, wrap: bool = ...) -> None: ... def diag_indices(n: int, ndim: int = ...) -> tuple[NDArray[int_], ...]: ... def diag_indices_from(arr: ArrayLike) -> tuple[NDArray[int_], ...]: ... # NOTE: see `numpy/__init__.pyi` for `ndenumerate` and `ndindex`	4.15 KB	2026-01-20 12:58
📄 mixins.py """Mixin classes for custom array types that don't inherit from ndarray.""" from numpy.core import umath as um __all__ = ['NDArrayOperatorsMixin'] def _disables_array_ufunc(obj): """True when __array_ufunc__ is set to None.""" try: return obj.__array_ufunc__ is None except AttributeError: return False def _binary_method(ufunc, name): """Implement a forward binary method with a ufunc, e.g., __add__.""" def func(self, other): if _disables_array_ufunc(other): return NotImplemented return ufunc(self, other) func.__name__ = '__{}__'.format(name) return func def _reflected_binary_method(ufunc, name): """Implement a reflected binary method with a ufunc, e.g., __radd__.""" def func(self, other): if _disables_array_ufunc(other): return NotImplemented return ufunc(other, self) func.__name__ = '__r{}__'.format(name) return func def _inplace_binary_method(ufunc, name): """Implement an in-place binary method with a ufunc, e.g., __iadd__.""" def func(self, other): return ufunc(self, other, out=(self,)) func.__name__ = '__i{}__'.format(name) return func def _numeric_methods(ufunc, name): """Implement forward, reflected and inplace binary methods with a ufunc.""" return (_binary_method(ufunc, name), _reflected_binary_method(ufunc, name), _inplace_binary_method(ufunc, name)) def _unary_method(ufunc, name): """Implement a unary special method with a ufunc.""" def func(self): return ufunc(self) func.__name__ = '__{}__'.format(name) return func class NDArrayOperatorsMixin: """Mixin defining all operator special methods using __array_ufunc__. This class implements the special methods for almost all of Python's builtin operators defined in the `operator` module, including comparisons (``==``, ``>``, etc.) and arithmetic (``+``, ````, ``-``, etc.), by deferring to the ``__array_ufunc__`` method, which subclasses must implement. It is useful for writing classes that do not inherit from `numpy.ndarray`, but that should support arithmetic and numpy universal functions like arrays as described in `A Mechanism for Overriding Ufuncs <https://numpy.org/neps/nep-0013-ufunc-overrides.html>`_. As an trivial example, consider this implementation of an ``ArrayLike`` class that simply wraps a NumPy array and ensures that the result of any arithmetic operation is also an ``ArrayLike`` object:: class ArrayLike(np.lib.mixins.NDArrayOperatorsMixin): def __init__(self, value): self.value = np.asarray(value) # One might also consider adding the built-in list type to this # list, to support operations like np.add(array_like, list) _HANDLED_TYPES = (np.ndarray, numbers.Number) def __array_ufunc__(self, ufunc, method, inputs, *kwargs): out = kwargs.get('out', ()) for x in inputs + out: # Only support operations with instances of _HANDLED_TYPES. # Use ArrayLike instead of type(self) for isinstance to # allow subclasses that don't override __array_ufunc__ to # handle ArrayLike objects. if not isinstance(x, self._HANDLED_TYPES + (ArrayLike,)): return NotImplemented # Defer to the implementation of the ufunc on unwrapped values. inputs = tuple(x.value if isinstance(x, ArrayLike) else x for x in inputs) if out: kwargs['out'] = tuple( x.value if isinstance(x, ArrayLike) else x for x in out) result = getattr(ufunc, method)(inputs, **kwargs) if type(result) is tuple: # multiple return values return tuple(type(self)(x) for x in result) elif method == 'at': # no return value return None else: # one return value return type(self)(result) def __repr__(self): return '%s(%r)' % (type(self).__name__, self.value) In interactions between ``ArrayLike`` objects and numbers or numpy arrays, the result is always another ``ArrayLike``: >>> x = ArrayLike([1, 2, 3]) >>> x - 1 ArrayLike(array([0, 1, 2])) >>> 1 - x ArrayLike(array([ 0, -1, -2])) >>> np.arange(3) - x ArrayLike(array([-1, -1, -1])) >>> x - np.arange(3) ArrayLike(array([1, 1, 1])) Note that unlike ``numpy.ndarray``, ``ArrayLike`` does not allow operations with arbitrary, unrecognized types. This ensures that interactions with ArrayLike preserve a well-defined casting hierarchy. .. versionadded:: 1.13 """ __slots__ = () # Like np.ndarray, this mixin class implements "Option 1" from the ufunc # overrides NEP. # comparisons don't have reflected and in-place versions __lt__ = _binary_method(um.less, 'lt') __le__ = _binary_method(um.less_equal, 'le') __eq__ = _binary_method(um.equal, 'eq') __ne__ = _binary_method(um.not_equal, 'ne') __gt__ = _binary_method(um.greater, 'gt') __ge__ = _binary_method(um.greater_equal, 'ge') # numeric methods __add__, __radd__, __iadd__ = _numeric_methods(um.add, 'add') __sub__, __rsub__, __isub__ = _numeric_methods(um.subtract, 'sub') __mul__, __rmul__, __imul__ = _numeric_methods(um.multiply, 'mul') __matmul__, __rmatmul__, __imatmul__ = _numeric_methods( um.matmul, 'matmul') # Python 3 does not use __div__, __rdiv__, or __idiv__ __truediv__, __rtruediv__, __itruediv__ = _numeric_methods( um.true_divide, 'truediv') __floordiv__, __rfloordiv__, __ifloordiv__ = _numeric_methods( um.floor_divide, 'floordiv') __mod__, __rmod__, __imod__ = _numeric_methods(um.remainder, 'mod') __divmod__ = _binary_method(um.divmod, 'divmod') __rdivmod__ = _reflected_binary_method(um.divmod, 'divmod') # __idivmod__ does not exist # TODO: handle the optional third argument for __pow__? __pow__, __rpow__, __ipow__ = _numeric_methods(um.power, 'pow') __lshift__, __rlshift__, __ilshift__ = _numeric_methods( um.left_shift, 'lshift') __rshift__, __rrshift__, __irshift__ = _numeric_methods( um.right_shift, 'rshift') __and__, __rand__, __iand__ = _numeric_methods(um.bitwise_and, 'and') __xor__, __rxor__, __ixor__ = _numeric_methods(um.bitwise_xor, 'xor') __or__, __ror__, __ior__ = _numeric_methods(um.bitwise_or, 'or') # unary methods __neg__ = _unary_method(um.negative, 'neg') __pos__ = _unary_method(um.positive, 'pos') __abs__ = _unary_method(um.absolute, 'abs') __invert__ = _unary_method(um.invert, 'invert')	6.91 KB	2026-01-20 12:58
📄 mixins.pyi from abc import ABCMeta, abstractmethod from typing import Literal as L, Any from numpy import ufunc __all__: list[str] # NOTE: `NDArrayOperatorsMixin` is not formally an abstract baseclass, # even though it's reliant on subclasses implementing `__array_ufunc__` # NOTE: The accepted input- and output-types of the various dunders are # completely dependent on how `__array_ufunc__` is implemented. # As such, only little type safety can be provided here. class NDArrayOperatorsMixin(metaclass=ABCMeta): @abstractmethod def __array_ufunc__( self, ufunc: ufunc, method: L["__call__", "reduce", "reduceat", "accumulate", "outer", "inner"], inputs: Any, *kwargs: Any, ) -> Any: ... def __lt__(self, other: Any) -> Any: ... def __le__(self, other: Any) -> Any: ... def __eq__(self, other: Any) -> Any: ... def __ne__(self, other: Any) -> Any: ... def __gt__(self, other: Any) -> Any: ... def __ge__(self, other: Any) -> Any: ... def __add__(self, other: Any) -> Any: ... def __radd__(self, other: Any) -> Any: ... def __iadd__(self, other: Any) -> Any: ... def __sub__(self, other: Any) -> Any: ... def __rsub__(self, other: Any) -> Any: ... def __isub__(self, other: Any) -> Any: ... def __mul__(self, other: Any) -> Any: ... def __rmul__(self, other: Any) -> Any: ... def __imul__(self, other: Any) -> Any: ... def __matmul__(self, other: Any) -> Any: ... def __rmatmul__(self, other: Any) -> Any: ... def __imatmul__(self, other: Any) -> Any: ... def __truediv__(self, other: Any) -> Any: ... def __rtruediv__(self, other: Any) -> Any: ... def __itruediv__(self, other: Any) -> Any: ... def __floordiv__(self, other: Any) -> Any: ... def __rfloordiv__(self, other: Any) -> Any: ... def __ifloordiv__(self, other: Any) -> Any: ... def __mod__(self, other: Any) -> Any: ... def __rmod__(self, other: Any) -> Any: ... def __imod__(self, other: Any) -> Any: ... def __divmod__(self, other: Any) -> Any: ... def __rdivmod__(self, other: Any) -> Any: ... def __pow__(self, other: Any) -> Any: ... def __rpow__(self, other: Any) -> Any: ... def __ipow__(self, other: Any) -> Any: ... def __lshift__(self, other: Any) -> Any: ... def __rlshift__(self, other: Any) -> Any: ... def __ilshift__(self, other: Any) -> Any: ... def __rshift__(self, other: Any) -> Any: ... def __rrshift__(self, other: Any) -> Any: ... def __irshift__(self, other: Any) -> Any: ... def __and__(self, other: Any) -> Any: ... def __rand__(self, other: Any) -> Any: ... def __iand__(self, other: Any) -> Any: ... def __xor__(self, other: Any) -> Any: ... def __rxor__(self, other: Any) -> Any: ... def __ixor__(self, other: Any) -> Any: ... def __or__(self, other: Any) -> Any: ... def __ror__(self, other: Any) -> Any: ... def __ior__(self, other: Any) -> Any: ... def __neg__(self) -> Any: ... def __pos__(self) -> Any: ... def __abs__(self) -> Any: ... def __invert__(self) -> Any: ...	3.04 KB	2026-01-20 12:58
📄 nanfunctions.py """ Functions that ignore NaN. Functions --------- - `nanmin` -- minimum non-NaN value - `nanmax` -- maximum non-NaN value - `nanargmin` -- index of minimum non-NaN value - `nanargmax` -- index of maximum non-NaN value - `nansum` -- sum of non-NaN values - `nanprod` -- product of non-NaN values - `nancumsum` -- cumulative sum of non-NaN values - `nancumprod` -- cumulative product of non-NaN values - `nanmean` -- mean of non-NaN values - `nanvar` -- variance of non-NaN values - `nanstd` -- standard deviation of non-NaN values - `nanmedian` -- median of non-NaN values - `nanquantile` -- qth quantile of non-NaN values - `nanpercentile` -- qth percentile of non-NaN values """ import functools import warnings import numpy as np from numpy.lib import function_base from numpy.core import overrides array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') __all__ = [ 'nansum', 'nanmax', 'nanmin', 'nanargmax', 'nanargmin', 'nanmean', 'nanmedian', 'nanpercentile', 'nanvar', 'nanstd', 'nanprod', 'nancumsum', 'nancumprod', 'nanquantile' ] def _nan_mask(a, out=None): """ Parameters ---------- a : array-like Input array with at least 1 dimension. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output and will prevent the allocation of a new array. Returns ------- y : bool ndarray or True A bool array where ``np.nan`` positions are marked with ``False`` and other positions are marked with ``True``. If the type of ``a`` is such that it can't possibly contain ``np.nan``, returns ``True``. """ # we assume that a is an array for this private function if a.dtype.kind not in 'fc': return True y = np.isnan(a, out=out) y = np.invert(y, out=y) return y def _replace_nan(a, val): """ If `a` is of inexact type, make a copy of `a`, replace NaNs with the `val` value, and return the copy together with a boolean mask marking the locations where NaNs were present. If `a` is not of inexact type, do nothing and return `a` together with a mask of None. Note that scalars will end up as array scalars, which is important for using the result as the value of the out argument in some operations. Parameters ---------- a : array-like Input array. val : float NaN values are set to val before doing the operation. Returns ------- y : ndarray If `a` is of inexact type, return a copy of `a` with the NaNs replaced by the fill value, otherwise return `a`. mask: {bool, None} If `a` is of inexact type, return a boolean mask marking locations of NaNs, otherwise return None. """ a = np.asanyarray(a) if a.dtype == np.object_: # object arrays do not support `isnan` (gh-9009), so make a guess mask = np.not_equal(a, a, dtype=bool) elif issubclass(a.dtype.type, np.inexact): mask = np.isnan(a) else: mask = None if mask is not None: a = np.array(a, subok=True, copy=True) np.copyto(a, val, where=mask) return a, mask def _copyto(a, val, mask): """ Replace values in `a` with NaN where `mask` is True. This differs from copyto in that it will deal with the case where `a` is a numpy scalar. Parameters ---------- a : ndarray or numpy scalar Array or numpy scalar some of whose values are to be replaced by val. val : numpy scalar Value used a replacement. mask : ndarray, scalar Boolean array. Where True the corresponding element of `a` is replaced by `val`. Broadcasts. Returns ------- res : ndarray, scalar Array with elements replaced or scalar `val`. """ if isinstance(a, np.ndarray): np.copyto(a, val, where=mask, casting='unsafe') else: a = a.dtype.type(val) return a def _remove_nan_1d(arr1d, overwrite_input=False): """ Equivalent to arr1d[~arr1d.isnan()], but in a different order Presumably faster as it incurs fewer copies Parameters ---------- arr1d : ndarray Array to remove nans from overwrite_input : bool True if `arr1d` can be modified in place Returns ------- res : ndarray Array with nan elements removed overwrite_input : bool True if `res` can be modified in place, given the constraint on the input """ if arr1d.dtype == object: # object arrays do not support `isnan` (gh-9009), so make a guess c = np.not_equal(arr1d, arr1d, dtype=bool) else: c = np.isnan(arr1d) s = np.nonzero(c)[0] if s.size == arr1d.size: warnings.warn("All-NaN slice encountered", RuntimeWarning, stacklevel=6) return arr1d[:0], True elif s.size == 0: return arr1d, overwrite_input else: if not overwrite_input: arr1d = arr1d.copy() # select non-nans at end of array enonan = arr1d[-s.size:][~c[-s.size:]] # fill nans in beginning of array with non-nans of end arr1d[s[:enonan.size]] = enonan return arr1d[:-s.size], True def _divide_by_count(a, b, out=None): """ Compute a/b ignoring invalid results. If `a` is an array the division is done in place. If `a` is a scalar, then its type is preserved in the output. If out is None, then a is used instead so that the division is in place. Note that this is only called with `a` an inexact type. Parameters ---------- a : {ndarray, numpy scalar} Numerator. Expected to be of inexact type but not checked. b : {ndarray, numpy scalar} Denominator. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. Returns ------- ret : {ndarray, numpy scalar} The return value is a/b. If `a` was an ndarray the division is done in place. If `a` is a numpy scalar, the division preserves its type. """ with np.errstate(invalid='ignore', divide='ignore'): if isinstance(a, np.ndarray): if out is None: return np.divide(a, b, out=a, casting='unsafe') else: return np.divide(a, b, out=out, casting='unsafe') else: if out is None: # Precaution against reduced object arrays try: return a.dtype.type(a / b) except AttributeError: return a / b else: # This is questionable, but currently a numpy scalar can # be output to a zero dimensional array. return np.divide(a, b, out=out, casting='unsafe') def _nanmin_dispatcher(a, axis=None, out=None, keepdims=None, initial=None, where=None): return (a, out) @array_function_dispatch(_nanmin_dispatcher) def nanmin(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue, where=np._NoValue): """ Return minimum of an array or minimum along an axis, ignoring any NaNs. When all-NaN slices are encountered a ``RuntimeWarning`` is raised and Nan is returned for that slice. Parameters ---------- a : array_like Array containing numbers whose minimum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the minimum is computed. The default is to compute the minimum of the flattened array. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. .. versionadded:: 1.8.0 keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If the value is anything but the default, then `keepdims` will be passed through to the `min` method of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 initial : scalar, optional The maximum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 where : array_like of bool, optional Elements to compare for the minimum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- nanmin : ndarray An array with the same shape as `a`, with the specified axis removed. If `a` is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as `a` is returned. See Also -------- nanmax : The maximum value of an array along a given axis, ignoring any NaNs. amin : The minimum value of an array along a given axis, propagating any NaNs. fmin : Element-wise minimum of two arrays, ignoring any NaNs. minimum : Element-wise minimum of two arrays, propagating any NaNs. isnan : Shows which elements are Not a Number (NaN). isfinite: Shows which elements are neither NaN nor infinity. amax, fmax, maximum Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number. If the input has a integer type the function is equivalent to np.min. Examples -------- >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanmin(a) 1.0 >>> np.nanmin(a, axis=0) array([1., 2.]) >>> np.nanmin(a, axis=1) array([1., 3.]) When positive infinity and negative infinity are present: >>> np.nanmin([1, 2, np.nan, np.inf]) 1.0 >>> np.nanmin([1, 2, np.nan, np.NINF]) -inf """ kwargs = {} if keepdims is not np._NoValue: kwargs['keepdims'] = keepdims if initial is not np._NoValue: kwargs['initial'] = initial if where is not np._NoValue: kwargs['where'] = where if type(a) is np.ndarray and a.dtype != np.object_: # Fast, but not safe for subclasses of ndarray, or object arrays, # which do not implement isnan (gh-9009), or fmin correctly (gh-8975) res = np.fmin.reduce(a, axis=axis, out=out, kwargs) if np.isnan(res).any(): warnings.warn("All-NaN slice encountered", RuntimeWarning, stacklevel=2) else: # Slow, but safe for subclasses of ndarray a, mask = _replace_nan(a, +np.inf) res = np.amin(a, axis=axis, out=out, kwargs) if mask is None: return res # Check for all-NaN axis kwargs.pop("initial", None) mask = np.all(mask, axis=axis, kwargs) if np.any(mask): res = _copyto(res, np.nan, mask) warnings.warn("All-NaN axis encountered", RuntimeWarning, stacklevel=2) return res def _nanmax_dispatcher(a, axis=None, out=None, keepdims=None, initial=None, where=None): return (a, out) @array_function_dispatch(_nanmax_dispatcher) def nanmax(a, axis=None, out=None, keepdims=np._NoValue, initial=np._NoValue, where=np._NoValue): """ Return the maximum of an array or maximum along an axis, ignoring any NaNs. When all-NaN slices are encountered a ``RuntimeWarning`` is raised and NaN is returned for that slice. Parameters ---------- a : array_like Array containing numbers whose maximum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the maximum is computed. The default is to compute the maximum of the flattened array. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. .. versionadded:: 1.8.0 keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If the value is anything but the default, then `keepdims` will be passed through to the `max` method of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 initial : scalar, optional The minimum value of an output element. Must be present to allow computation on empty slice. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 where : array_like of bool, optional Elements to compare for the maximum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- nanmax : ndarray An array with the same shape as `a`, with the specified axis removed. If `a` is a 0-d array, or if axis is None, an ndarray scalar is returned. The same dtype as `a` is returned. See Also -------- nanmin : The minimum value of an array along a given axis, ignoring any NaNs. amax : The maximum value of an array along a given axis, propagating any NaNs. fmax : Element-wise maximum of two arrays, ignoring any NaNs. maximum : Element-wise maximum of two arrays, propagating any NaNs. isnan : Shows which elements are Not a Number (NaN). isfinite: Shows which elements are neither NaN nor infinity. amin, fmin, minimum Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Positive infinity is treated as a very large number and negative infinity is treated as a very small (i.e. negative) number. If the input has a integer type the function is equivalent to np.max. Examples -------- >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanmax(a) 3.0 >>> np.nanmax(a, axis=0) array([3., 2.]) >>> np.nanmax(a, axis=1) array([2., 3.]) When positive infinity and negative infinity are present: >>> np.nanmax([1, 2, np.nan, np.NINF]) 2.0 >>> np.nanmax([1, 2, np.nan, np.inf]) inf """ kwargs = {} if keepdims is not np._NoValue: kwargs['keepdims'] = keepdims if initial is not np._NoValue: kwargs['initial'] = initial if where is not np._NoValue: kwargs['where'] = where if type(a) is np.ndarray and a.dtype != np.object_: # Fast, but not safe for subclasses of ndarray, or object arrays, # which do not implement isnan (gh-9009), or fmax correctly (gh-8975) res = np.fmax.reduce(a, axis=axis, out=out, kwargs) if np.isnan(res).any(): warnings.warn("All-NaN slice encountered", RuntimeWarning, stacklevel=2) else: # Slow, but safe for subclasses of ndarray a, mask = _replace_nan(a, -np.inf) res = np.amax(a, axis=axis, out=out, kwargs) if mask is None: return res # Check for all-NaN axis kwargs.pop("initial", None) mask = np.all(mask, axis=axis, kwargs) if np.any(mask): res = _copyto(res, np.nan, mask) warnings.warn("All-NaN axis encountered", RuntimeWarning, stacklevel=2) return res def _nanargmin_dispatcher(a, axis=None, out=None, , keepdims=None): return (a,) @array_function_dispatch(_nanargmin_dispatcher) def nanargmin(a, axis=None, out=None, , keepdims=np._NoValue): """ Return the indices of the minimum values in the specified axis ignoring NaNs. For all-NaN slices ``ValueError`` is raised. Warning: the results cannot be trusted if a slice contains only NaNs and Infs. Parameters ---------- a : array_like Input data. axis : int, optional Axis along which to operate. By default flattened input is used. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. .. versionadded:: 1.22.0 keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the array. .. versionadded:: 1.22.0 Returns ------- index_array : ndarray An array of indices or a single index value. See Also -------- argmin, nanargmax Examples -------- >>> a = np.array([[np.nan, 4], [2, 3]]) >>> np.argmin(a) 0 >>> np.nanargmin(a) 2 >>> np.nanargmin(a, axis=0) array([1, 1]) >>> np.nanargmin(a, axis=1) array([1, 0]) """ a, mask = _replace_nan(a, np.inf) if mask is not None: mask = np.all(mask, axis=axis) if np.any(mask): raise ValueError("All-NaN slice encountered") res = np.argmin(a, axis=axis, out=out, keepdims=keepdims) return res def _nanargmax_dispatcher(a, axis=None, out=None, , keepdims=None): return (a,) @array_function_dispatch(_nanargmax_dispatcher) def nanargmax(a, axis=None, out=None, , keepdims=np._NoValue): """ Return the indices of the maximum values in the specified axis ignoring NaNs. For all-NaN slices ``ValueError`` is raised. Warning: the results cannot be trusted if a slice contains only NaNs and -Infs. Parameters ---------- a : array_like Input data. axis : int, optional Axis along which to operate. By default flattened input is used. out : array, optional If provided, the result will be inserted into this array. It should be of the appropriate shape and dtype. .. versionadded:: 1.22.0 keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the array. .. versionadded:: 1.22.0 Returns ------- index_array : ndarray An array of indices or a single index value. See Also -------- argmax, nanargmin Examples -------- >>> a = np.array([[np.nan, 4], [2, 3]]) >>> np.argmax(a) 0 >>> np.nanargmax(a) 1 >>> np.nanargmax(a, axis=0) array([1, 0]) >>> np.nanargmax(a, axis=1) array([1, 1]) """ a, mask = _replace_nan(a, -np.inf) if mask is not None: mask = np.all(mask, axis=axis) if np.any(mask): raise ValueError("All-NaN slice encountered") res = np.argmax(a, axis=axis, out=out, keepdims=keepdims) return res def _nansum_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None, initial=None, where=None): return (a, out) @array_function_dispatch(_nansum_dispatcher) def nansum(a, axis=None, dtype=None, out=None, keepdims=np._NoValue, initial=np._NoValue, where=np._NoValue): """ Return the sum of array elements over a given axis treating Not a Numbers (NaNs) as zero. In NumPy versions <= 1.9.0 Nan is returned for slices that are all-NaN or empty. In later versions zero is returned. Parameters ---------- a : array_like Array containing numbers whose sum is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the sum is computed. The default is to compute the sum of the flattened array. dtype : data-type, optional The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of `a` is used. An exception is when `a` has an integer type with less precision than the platform (u)intp. In that case, the default will be either (u)int32 or (u)int64 depending on whether the platform is 32 or 64 bits. For inexact inputs, dtype must be inexact. .. versionadded:: 1.8.0 out : ndarray, optional Alternate output array in which to place the result. The default is ``None``. If provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. The casting of NaN to integer can yield unexpected results. .. versionadded:: 1.8.0 keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If the value is anything but the default, then `keepdims` will be passed through to the `mean` or `sum` methods of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. .. versionadded:: 1.8.0 initial : scalar, optional Starting value for the sum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 where : array_like of bool, optional Elements to include in the sum. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- nansum : ndarray. A new array holding the result is returned unless `out` is specified, in which it is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. See Also -------- numpy.sum : Sum across array propagating NaNs. isnan : Show which elements are NaN. isfinite : Show which elements are not NaN or +/-inf. Notes ----- If both positive and negative infinity are present, the sum will be Not A Number (NaN). Examples -------- >>> np.nansum(1) 1 >>> np.nansum([1]) 1 >>> np.nansum([1, np.nan]) 1.0 >>> a = np.array([[1, 1], [1, np.nan]]) >>> np.nansum(a) 3.0 >>> np.nansum(a, axis=0) array([2., 1.]) >>> np.nansum([1, np.nan, np.inf]) inf >>> np.nansum([1, np.nan, np.NINF]) -inf >>> from numpy.testing import suppress_warnings >>> with suppress_warnings() as sup: ... sup.filter(RuntimeWarning) ... np.nansum([1, np.nan, np.inf, -np.inf]) # both +/- infinity present nan """ a, mask = _replace_nan(a, 0) return np.sum(a, axis=axis, dtype=dtype, out=out, keepdims=keepdims, initial=initial, where=where) def _nanprod_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None, initial=None, where=None): return (a, out) @array_function_dispatch(_nanprod_dispatcher) def nanprod(a, axis=None, dtype=None, out=None, keepdims=np._NoValue, initial=np._NoValue, where=np._NoValue): """ Return the product of array elements over a given axis treating Not a Numbers (NaNs) as ones. One is returned for slices that are all-NaN or empty. .. versionadded:: 1.10.0 Parameters ---------- a : array_like Array containing numbers whose product is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the product is computed. The default is to compute the product of the flattened array. dtype : data-type, optional The type of the returned array and of the accumulator in which the elements are summed. By default, the dtype of `a` is used. An exception is when `a` has an integer type with less precision than the platform (u)intp. In that case, the default will be either (u)int32 or (u)int64 depending on whether the platform is 32 or 64 bits. For inexact inputs, dtype must be inexact. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``. If provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. The casting of NaN to integer can yield unexpected results. keepdims : bool, optional If True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `arr`. initial : scalar, optional The starting value for this product. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 where : array_like of bool, optional Elements to include in the product. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- nanprod : ndarray A new array holding the result is returned unless `out` is specified, in which case it is returned. See Also -------- numpy.prod : Product across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nanprod(1) 1 >>> np.nanprod([1]) 1 >>> np.nanprod([1, np.nan]) 1.0 >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nanprod(a) 6.0 >>> np.nanprod(a, axis=0) array([3., 2.]) """ a, mask = _replace_nan(a, 1) return np.prod(a, axis=axis, dtype=dtype, out=out, keepdims=keepdims, initial=initial, where=where) def _nancumsum_dispatcher(a, axis=None, dtype=None, out=None): return (a, out) @array_function_dispatch(_nancumsum_dispatcher) def nancumsum(a, axis=None, dtype=None, out=None): """ Return the cumulative sum of array elements over a given axis treating Not a Numbers (NaNs) as zero. The cumulative sum does not change when NaNs are encountered and leading NaNs are replaced by zeros. Zeros are returned for slices that are all-NaN or empty. .. versionadded:: 1.12.0 Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative sum is computed. The default (None) is to compute the cumsum over the flattened array. dtype : dtype, optional Type of the returned array and of the accumulator in which the elements are summed. If `dtype` is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. Returns ------- nancumsum : ndarray. A new array holding the result is returned unless `out` is specified, in which it is returned. The result has the same size as `a`, and the same shape as `a` if `axis` is not None or `a` is a 1-d array. See Also -------- numpy.cumsum : Cumulative sum across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nancumsum(1) array([1]) >>> np.nancumsum([1]) array([1]) >>> np.nancumsum([1, np.nan]) array([1., 1.]) >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nancumsum(a) array([1., 3., 6., 6.]) >>> np.nancumsum(a, axis=0) array([[1., 2.], [4., 2.]]) >>> np.nancumsum(a, axis=1) array([[1., 3.], [3., 3.]]) """ a, mask = _replace_nan(a, 0) return np.cumsum(a, axis=axis, dtype=dtype, out=out) def _nancumprod_dispatcher(a, axis=None, dtype=None, out=None): return (a, out) @array_function_dispatch(_nancumprod_dispatcher) def nancumprod(a, axis=None, dtype=None, out=None): """ Return the cumulative product of array elements over a given axis treating Not a Numbers (NaNs) as one. The cumulative product does not change when NaNs are encountered and leading NaNs are replaced by ones. Ones are returned for slices that are all-NaN or empty. .. versionadded:: 1.12.0 Parameters ---------- a : array_like Input array. axis : int, optional Axis along which the cumulative product is computed. By default the input is flattened. dtype : dtype, optional Type of the returned array, as well as of the accumulator in which the elements are multiplied. If dtype is not specified, it defaults to the dtype of `a`, unless `a` has an integer dtype with a precision less than that of the default platform integer. In that case, the default platform integer is used instead. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output but the type of the resulting values will be cast if necessary. Returns ------- nancumprod : ndarray A new array holding the result is returned unless `out` is specified, in which case it is returned. See Also -------- numpy.cumprod : Cumulative product across array propagating NaNs. isnan : Show which elements are NaN. Examples -------- >>> np.nancumprod(1) array([1]) >>> np.nancumprod([1]) array([1]) >>> np.nancumprod([1, np.nan]) array([1., 1.]) >>> a = np.array([[1, 2], [3, np.nan]]) >>> np.nancumprod(a) array([1., 2., 6., 6.]) >>> np.nancumprod(a, axis=0) array([[1., 2.], [3., 2.]]) >>> np.nancumprod(a, axis=1) array([[1., 2.], [3., 3.]]) """ a, mask = _replace_nan(a, 1) return np.cumprod(a, axis=axis, dtype=dtype, out=out) def _nanmean_dispatcher(a, axis=None, dtype=None, out=None, keepdims=None, , where=None): return (a, out) @array_function_dispatch(_nanmean_dispatcher) def nanmean(a, axis=None, dtype=None, out=None, keepdims=np._NoValue, , where=np._NoValue): """ Compute the arithmetic mean along the specified axis, ignoring NaNs. Returns the average of the array elements. The average is taken over the flattened array by default, otherwise over the specified axis. `float64` intermediate and return values are used for integer inputs. For all-NaN slices, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Array containing numbers whose mean is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the means are computed. The default is to compute the mean of the flattened array. dtype : data-type, optional Type to use in computing the mean. For integer inputs, the default is `float64`; for inexact inputs, it is the same as the input dtype. out : ndarray, optional Alternate output array in which to place the result. The default is ``None``; if provided, it must have the same shape as the expected output, but the type will be cast if necessary. See :ref:`ufuncs-output-type` for more details. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If the value is anything but the default, then `keepdims` will be passed through to the `mean` or `sum` methods of sub-classes of `ndarray`. If the sub-classes methods does not implement `keepdims` any exceptions will be raised. where : array_like of bool, optional Elements to include in the mean. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- m : ndarray, see dtype parameter above If `out=None`, returns a new array containing the mean values, otherwise a reference to the output array is returned. Nan is returned for slices that contain only NaNs. See Also -------- average : Weighted average mean : Arithmetic mean taken while not ignoring NaNs var, nanvar Notes ----- The arithmetic mean is the sum of the non-NaN elements along the axis divided by the number of non-NaN elements. Note that for floating-point input, the mean is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32`. Specifying a higher-precision accumulator using the `dtype` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanmean(a) 2.6666666666666665 >>> np.nanmean(a, axis=0) array([2., 4.]) >>> np.nanmean(a, axis=1) array([1., 3.5]) # may vary """ arr, mask = _replace_nan(a, 0) if mask is None: return np.mean(arr, axis=axis, dtype=dtype, out=out, keepdims=keepdims, where=where) if dtype is not None: dtype = np.dtype(dtype) if dtype is not None and not issubclass(dtype.type, np.inexact): raise TypeError("If a is inexact, then dtype must be inexact") if out is not None and not issubclass(out.dtype.type, np.inexact): raise TypeError("If a is inexact, then out must be inexact") cnt = np.sum(~mask, axis=axis, dtype=np.intp, keepdims=keepdims, where=where) tot = np.sum(arr, axis=axis, dtype=dtype, out=out, keepdims=keepdims, where=where) avg = _divide_by_count(tot, cnt, out=out) isbad = (cnt == 0) if isbad.any(): warnings.warn("Mean of empty slice", RuntimeWarning, stacklevel=2) # NaN is the only possible bad value, so no further # action is needed to handle bad results. return avg def _nanmedian1d(arr1d, overwrite_input=False): """ Private function for rank 1 arrays. Compute the median ignoring NaNs. See nanmedian for parameter usage """ arr1d_parsed, overwrite_input = _remove_nan_1d( arr1d, overwrite_input=overwrite_input, ) if arr1d_parsed.size == 0: # Ensure that a nan-esque scalar of the appropriate type (and unit) # is returned for `timedelta64` and `complexfloating` return arr1d[-1] return np.median(arr1d_parsed, overwrite_input=overwrite_input) def _nanmedian(a, axis=None, out=None, overwrite_input=False): """ Private function that doesn't support extended axis or keepdims. These methods are extended to this function using _ureduce See nanmedian for parameter usage """ if axis is None or a.ndim == 1: part = a.ravel() if out is None: return _nanmedian1d(part, overwrite_input) else: out[...] = _nanmedian1d(part, overwrite_input) return out else: # for small medians use sort + indexing which is still faster than # apply_along_axis # benchmarked with shuffled (50, 50, x) containing a few NaN if a.shape[axis] < 600: return _nanmedian_small(a, axis, out, overwrite_input) result = np.apply_along_axis(_nanmedian1d, axis, a, overwrite_input) if out is not None: out[...] = result return result def _nanmedian_small(a, axis=None, out=None, overwrite_input=False): """ sort + indexing median, faster for small medians along multiple dimensions due to the high overhead of apply_along_axis see nanmedian for parameter usage """ a = np.ma.masked_array(a, np.isnan(a)) m = np.ma.median(a, axis=axis, overwrite_input=overwrite_input) for i in range(np.count_nonzero(m.mask.ravel())): warnings.warn("All-NaN slice encountered", RuntimeWarning, stacklevel=5) fill_value = np.timedelta64("NaT") if m.dtype.kind == "m" else np.nan if out is not None: out[...] = m.filled(fill_value) return out return m.filled(fill_value) def _nanmedian_dispatcher( a, axis=None, out=None, overwrite_input=None, keepdims=None): return (a, out) @array_function_dispatch(_nanmedian_dispatcher) def nanmedian(a, axis=None, out=None, overwrite_input=False, keepdims=np._NoValue): """ Compute the median along the specified axis, while ignoring NaNs. Returns the median of the array elements. .. versionadded:: 1.9.0 Parameters ---------- a : array_like Input array or object that can be converted to an array. axis : {int, sequence of int, None}, optional Axis or axes along which the medians are computed. The default is to compute the median along a flattened version of the array. A sequence of axes is supported since version 1.9.0. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow use of memory of input array `a` for calculations. The input array will be modified by the call to `median`. This will save memory when you do not need to preserve the contents of the input array. Treat the input as undefined, but it will probably be fully or partially sorted. Default is False. If `overwrite_input` is ``True`` and `a` is not already an `ndarray`, an error will be raised. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. Returns ------- median : ndarray A new array holding the result. If the input contains integers or floats smaller than ``float64``, then the output data-type is ``np.float64``. Otherwise, the data-type of the output is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- mean, median, percentile Notes ----- Given a vector ``V`` of length ``N``, the median of ``V`` is the middle value of a sorted copy of ``V``, ``V_sorted`` - i.e., ``V_sorted[(N-1)/2]``, when ``N`` is odd and the average of the two middle values of ``V_sorted`` when ``N`` is even. Examples -------- >>> a = np.array([[10.0, 7, 4], [3, 2, 1]]) >>> a[0, 1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.median(a) nan >>> np.nanmedian(a) 3.0 >>> np.nanmedian(a, axis=0) array([6.5, 2. , 2.5]) >>> np.median(a, axis=1) array([nan, 2.]) >>> b = a.copy() >>> np.nanmedian(b, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) >>> b = a.copy() >>> np.nanmedian(b, axis=None, overwrite_input=True) 3.0 >>> assert not np.all(a==b) """ a = np.asanyarray(a) # apply_along_axis in _nanmedian doesn't handle empty arrays well, # so deal them upfront if a.size == 0: return np.nanmean(a, axis, out=out, keepdims=keepdims) return function_base._ureduce(a, func=_nanmedian, keepdims=keepdims, axis=axis, out=out, overwrite_input=overwrite_input) def _nanpercentile_dispatcher( a, q, axis=None, out=None, overwrite_input=None, method=None, keepdims=None, , interpolation=None): return (a, q, out) @array_function_dispatch(_nanpercentile_dispatcher) def nanpercentile( a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=np._NoValue, , interpolation=None, ): """ Compute the qth percentile of the data along the specified axis, while ignoring nan values. Returns the qth percentile(s) of the array elements. .. versionadded:: 1.9.0 Parameters ---------- a : array_like Input array or object that can be converted to an array, containing nan values to be ignored. q : array_like of float Percentile or sequence of percentiles to compute, which must be between 0 and 100 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the percentiles are computed. The default is to compute the percentile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. method : str, optional This parameter specifies the method to use for estimating the percentile. There are many different methods, some unique to NumPy. See the notes for explanation. The options sorted by their R type as summarized in the H&F paper [1]_ are: 1. 'inverted_cdf' 2. 'averaged_inverted_cdf' 3. 'closest_observation' 4. 'interpolated_inverted_cdf' 5. 'hazen' 6. 'weibull' 7. 'linear' (default) 8. 'median_unbiased' 9. 'normal_unbiased' The first three methods are discontinuous. NumPy further defines the following discontinuous variations of the default 'linear' (7.) option: * 'lower' * 'higher', * 'midpoint' * 'nearest' .. versionchanged:: 1.22.0 This argument was previously called "interpolation" and only offered the "linear" default and last four options. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. interpolation : str, optional Deprecated name for the method keyword argument. .. deprecated:: 1.22.0 Returns ------- percentile : scalar or ndarray If `q` is a single percentile and `axis=None`, then the result is a scalar. If multiple percentiles are given, first axis of the result corresponds to the percentiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- nanmean nanmedian : equivalent to ``nanpercentile(..., 50)`` percentile, median, mean nanquantile : equivalent to nanpercentile, except q in range [0, 1]. Notes ----- For more information please see `numpy.percentile` Examples -------- >>> a = np.array([[10., 7., 4.], [3., 2., 1.]]) >>> a[0][1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.percentile(a, 50) nan >>> np.nanpercentile(a, 50) 3.0 >>> np.nanpercentile(a, 50, axis=0) array([6.5, 2. , 2.5]) >>> np.nanpercentile(a, 50, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.nanpercentile(a, 50, axis=0) >>> out = np.zeros_like(m) >>> np.nanpercentile(a, 50, axis=0, out=out) array([6.5, 2. , 2.5]) >>> m array([6.5, 2. , 2.5]) >>> b = a.copy() >>> np.nanpercentile(b, 50, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) References ---------- .. [1] R. J. Hyndman and Y. Fan, "Sample quantiles in statistical packages," The American Statistician, 50(4), pp. 361-365, 1996 """ if interpolation is not None: method = function_base._check_interpolation_as_method( method, interpolation, "nanpercentile") a = np.asanyarray(a) if a.dtype.kind == "c": raise TypeError("a must be an array of real numbers") q = np.true_divide(q, 100.0) # undo any decay that the ufunc performed (see gh-13105) q = np.asanyarray(q) if not function_base._quantile_is_valid(q): raise ValueError("Percentiles must be in the range [0, 100]") return _nanquantile_unchecked( a, q, axis, out, overwrite_input, method, keepdims) def _nanquantile_dispatcher(a, q, axis=None, out=None, overwrite_input=None, method=None, keepdims=None, , interpolation=None): return (a, q, out) @array_function_dispatch(_nanquantile_dispatcher) def nanquantile( a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=np._NoValue, , interpolation=None, ): """ Compute the qth quantile of the data along the specified axis, while ignoring nan values. Returns the qth quantile(s) of the array elements. .. versionadded:: 1.15.0 Parameters ---------- a : array_like Input array or object that can be converted to an array, containing nan values to be ignored q : array_like of float Probability or sequence of probabilities for the quantiles to compute. Values must be between 0 and 1 inclusive. axis : {int, tuple of int, None}, optional Axis or axes along which the quantiles are computed. The default is to compute the quantile(s) along a flattened version of the array. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape and buffer length as the expected output, but the type (of the output) will be cast if necessary. overwrite_input : bool, optional If True, then allow the input array `a` to be modified by intermediate calculations, to save memory. In this case, the contents of the input `a` after this function completes is undefined. method : str, optional This parameter specifies the method to use for estimating the quantile. There are many different methods, some unique to NumPy. See the notes for explanation. The options sorted by their R type as summarized in the H&F paper [1]_ are: 1. 'inverted_cdf' 2. 'averaged_inverted_cdf' 3. 'closest_observation' 4. 'interpolated_inverted_cdf' 5. 'hazen' 6. 'weibull' 7. 'linear' (default) 8. 'median_unbiased' 9. 'normal_unbiased' The first three methods are discontinuous. NumPy further defines the following discontinuous variations of the default 'linear' (7.) option: * 'lower' * 'higher', * 'midpoint' * 'nearest' .. versionchanged:: 1.22.0 This argument was previously called "interpolation" and only offered the "linear" default and last four options. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original array `a`. If this is anything but the default value it will be passed through (in the special case of an empty array) to the `mean` function of the underlying array. If the array is a sub-class and `mean` does not have the kwarg `keepdims` this will raise a RuntimeError. interpolation : str, optional Deprecated name for the method keyword argument. .. deprecated:: 1.22.0 Returns ------- quantile : scalar or ndarray If `q` is a single probability and `axis=None`, then the result is a scalar. If multiple probability levels are given, first axis of the result corresponds to the quantiles. The other axes are the axes that remain after the reduction of `a`. If the input contains integers or floats smaller than ``float64``, the output data-type is ``float64``. Otherwise, the output data-type is the same as that of the input. If `out` is specified, that array is returned instead. See Also -------- quantile nanmean, nanmedian nanmedian : equivalent to ``nanquantile(..., 0.5)`` nanpercentile : same as nanquantile, but with q in the range [0, 100]. Notes ----- For more information please see `numpy.quantile` Examples -------- >>> a = np.array([[10., 7., 4.], [3., 2., 1.]]) >>> a[0][1] = np.nan >>> a array([[10., nan, 4.], [ 3., 2., 1.]]) >>> np.quantile(a, 0.5) nan >>> np.nanquantile(a, 0.5) 3.0 >>> np.nanquantile(a, 0.5, axis=0) array([6.5, 2. , 2.5]) >>> np.nanquantile(a, 0.5, axis=1, keepdims=True) array([[7.], [2.]]) >>> m = np.nanquantile(a, 0.5, axis=0) >>> out = np.zeros_like(m) >>> np.nanquantile(a, 0.5, axis=0, out=out) array([6.5, 2. , 2.5]) >>> m array([6.5, 2. , 2.5]) >>> b = a.copy() >>> np.nanquantile(b, 0.5, axis=1, overwrite_input=True) array([7., 2.]) >>> assert not np.all(a==b) References ---------- .. [1] R. J. Hyndman and Y. Fan, "Sample quantiles in statistical packages," The American Statistician, 50(4), pp. 361-365, 1996 """ if interpolation is not None: method = function_base._check_interpolation_as_method( method, interpolation, "nanquantile") a = np.asanyarray(a) if a.dtype.kind == "c": raise TypeError("a must be an array of real numbers") q = np.asanyarray(q) if not function_base._quantile_is_valid(q): raise ValueError("Quantiles must be in the range [0, 1]") return _nanquantile_unchecked( a, q, axis, out, overwrite_input, method, keepdims) def _nanquantile_unchecked( a, q, axis=None, out=None, overwrite_input=False, method="linear", keepdims=np._NoValue, ): """Assumes that q is in [0, 1], and is an ndarray""" # apply_along_axis in _nanpercentile doesn't handle empty arrays well, # so deal them upfront if a.size == 0: return np.nanmean(a, axis, out=out, keepdims=keepdims) return function_base._ureduce(a, func=_nanquantile_ureduce_func, q=q, keepdims=keepdims, axis=axis, out=out, overwrite_input=overwrite_input, method=method) def _nanquantile_ureduce_func(a, q, axis=None, out=None, overwrite_input=False, method="linear"): """ Private function that doesn't support extended axis or keepdims. These methods are extended to this function using _ureduce See nanpercentile for parameter usage """ if axis is None or a.ndim == 1: part = a.ravel() result = _nanquantile_1d(part, q, overwrite_input, method) else: result = np.apply_along_axis(_nanquantile_1d, axis, a, q, overwrite_input, method) # apply_along_axis fills in collapsed axis with results. # Move that axis to the beginning to match percentile's # convention. if q.ndim != 0: result = np.moveaxis(result, axis, 0) if out is not None: out[...] = result return result def _nanquantile_1d(arr1d, q, overwrite_input=False, method="linear"): """ Private function for rank 1 arrays. Compute quantile ignoring NaNs. See nanpercentile for parameter usage """ arr1d, overwrite_input = _remove_nan_1d(arr1d, overwrite_input=overwrite_input) if arr1d.size == 0: # convert to scalar return np.full(q.shape, np.nan, dtype=arr1d.dtype)[()] return function_base._quantile_unchecked( arr1d, q, overwrite_input=overwrite_input, method=method) def _nanvar_dispatcher(a, axis=None, dtype=None, out=None, ddof=None, keepdims=None, , where=None): return (a, out) @array_function_dispatch(_nanvar_dispatcher) def nanvar(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, , where=np._NoValue): """ Compute the variance along the specified axis, while ignoring NaNs. Returns the variance of the array elements, a measure of the spread of a distribution. The variance is computed for the flattened array by default, otherwise over the specified axis. For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Array containing numbers whose variance is desired. If `a` is not an array, a conversion is attempted. axis : {int, tuple of int, None}, optional Axis or axes along which the variance is computed. The default is to compute the variance of the flattened array. dtype : data-type, optional Type to use in computing the variance. For arrays of integer type the default is `float64`; for arrays of float types it is the same as the array type. out : ndarray, optional Alternate output array in which to place the result. It must have the same shape as the expected output, but the type is cast if necessary. ddof : int, optional "Delta Degrees of Freedom": the divisor used in the calculation is ``N - ddof``, where ``N`` represents the number of non-NaN elements. By default `ddof` is zero. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. where : array_like of bool, optional Elements to include in the variance. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- variance : ndarray, see dtype parameter above If `out` is None, return a new array containing the variance, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN. See Also -------- std : Standard deviation mean : Average var : Variance while not ignoring NaNs nanstd, nanmean :ref:`ufuncs-output-type` Notes ----- The variance is the average of the squared deviations from the mean, i.e., ``var = mean(abs(x - x.mean())*2)``. The mean is normally calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of a hypothetical infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. Note that for complex numbers, the absolute value is taken before squaring, so that the result is always real and nonnegative. For floating-point input, the variance is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for `float32` (see example below). Specifying a higher-accuracy accumulator using the ``dtype`` keyword can alleviate this issue. For this function to work on sub-classes of ndarray, they must define `sum` with the kwarg `keepdims` Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanvar(a) 1.5555555555555554 >>> np.nanvar(a, axis=0) array([1., 0.]) >>> np.nanvar(a, axis=1) array([0., 0.25]) # may vary """ arr, mask = _replace_nan(a, 0) if mask is None: return np.var(arr, axis=axis, dtype=dtype, out=out, ddof=ddof, keepdims=keepdims, where=where) if dtype is not None: dtype = np.dtype(dtype) if dtype is not None and not issubclass(dtype.type, np.inexact): raise TypeError("If a is inexact, then dtype must be inexact") if out is not None and not issubclass(out.dtype.type, np.inexact): raise TypeError("If a is inexact, then out must be inexact") # Compute mean if type(arr) is np.matrix: _keepdims = np._NoValue else: _keepdims = True # we need to special case matrix for reverse compatibility # in order for this to work, these sums need to be called with # keepdims=True, however matrix now raises an error in this case, but # the reason that it drops the keepdims kwarg is to force keepdims=True # so this used to work by serendipity. cnt = np.sum(~mask, axis=axis, dtype=np.intp, keepdims=_keepdims, where=where) avg = np.sum(arr, axis=axis, dtype=dtype, keepdims=_keepdims, where=where) avg = _divide_by_count(avg, cnt) # Compute squared deviation from mean. np.subtract(arr, avg, out=arr, casting='unsafe', where=where) arr = _copyto(arr, 0, mask) if issubclass(arr.dtype.type, np.complexfloating): sqr = np.multiply(arr, arr.conj(), out=arr, where=where).real else: sqr = np.multiply(arr, arr, out=arr, where=where) # Compute variance. var = np.sum(sqr, axis=axis, dtype=dtype, out=out, keepdims=keepdims, where=where) # Precaution against reduced object arrays try: var_ndim = var.ndim except AttributeError: var_ndim = np.ndim(var) if var_ndim < cnt.ndim: # Subclasses of ndarray may ignore keepdims, so check here. cnt = cnt.squeeze(axis) dof = cnt - ddof var = _divide_by_count(var, dof) isbad = (dof <= 0) if np.any(isbad): warnings.warn("Degrees of freedom <= 0 for slice.", RuntimeWarning, stacklevel=2) # NaN, inf, or negative numbers are all possible bad # values, so explicitly replace them with NaN. var = _copyto(var, np.nan, isbad) return var def _nanstd_dispatcher(a, axis=None, dtype=None, out=None, ddof=None, keepdims=None, , where=None): return (a, out) @array_function_dispatch(_nanstd_dispatcher) def nanstd(a, axis=None, dtype=None, out=None, ddof=0, keepdims=np._NoValue, , where=np._NoValue): """ Compute the standard deviation along the specified axis, while ignoring NaNs. Returns the standard deviation, a measure of the spread of a distribution, of the non-NaN array elements. The standard deviation is computed for the flattened array by default, otherwise over the specified axis. For all-NaN slices or slices with zero degrees of freedom, NaN is returned and a `RuntimeWarning` is raised. .. versionadded:: 1.8.0 Parameters ---------- a : array_like Calculate the standard deviation of the non-NaN values. axis : {int, tuple of int, None}, optional Axis or axes along which the standard deviation is computed. The default is to compute the standard deviation of the flattened array. dtype : dtype, optional Type to use in computing the standard deviation. For arrays of integer type the default is float64, for arrays of float types it is the same as the array type. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output but the type (of the calculated values) will be cast if necessary. ddof : int, optional Means Delta Degrees of Freedom. The divisor used in calculations is ``N - ddof``, where ``N`` represents the number of non-NaN elements. By default `ddof` is zero. keepdims : bool, optional If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the original `a`. If this value is anything but the default it is passed through as-is to the relevant functions of the sub-classes. If these functions do not have a `keepdims` kwarg, a RuntimeError will be raised. where : array_like of bool, optional Elements to include in the standard deviation. See `~numpy.ufunc.reduce` for details. .. versionadded:: 1.22.0 Returns ------- standard_deviation : ndarray, see dtype parameter above. If `out` is None, return a new array containing the standard deviation, otherwise return a reference to the output array. If ddof is >= the number of non-NaN elements in a slice or the slice contains only NaNs, then the result for that slice is NaN. See Also -------- var, mean, std nanvar, nanmean :ref:`ufuncs-output-type` Notes ----- The standard deviation is the square root of the average of the squared deviations from the mean: ``std = sqrt(mean(abs(x - x.mean())2))``. The average squared deviation is normally calculated as ``x.sum() / N``, where ``N = len(x)``. If, however, `ddof` is specified, the divisor ``N - ddof`` is used instead. In standard statistical practice, ``ddof=1`` provides an unbiased estimator of the variance of the infinite population. ``ddof=0`` provides a maximum likelihood estimate of the variance for normally distributed variables. The standard deviation computed in this function is the square root of the estimated variance, so even with ``ddof=1``, it will not be an unbiased estimate of the standard deviation per se. Note that, for complex numbers, `std` takes the absolute value before squaring, so that the result is always real and nonnegative. For floating-point input, the std* is computed using the same precision the input has. Depending on the input data, this can cause the results to be inaccurate, especially for float32 (see example below). Specifying a higher-accuracy accumulator using the `dtype` keyword can alleviate this issue. Examples -------- >>> a = np.array([[1, np.nan], [3, 4]]) >>> np.nanstd(a) 1.247219128924647 >>> np.nanstd(a, axis=0) array([1., 0.]) >>> np.nanstd(a, axis=1) array([0., 0.5]) # may vary """ var = nanvar(a, axis=axis, dtype=dtype, out=out, ddof=ddof, keepdims=keepdims, where=where) if isinstance(var, np.ndarray): std = np.sqrt(var, out=var) elif hasattr(var, 'dtype'): std = var.dtype.type(np.sqrt(var)) else: std = np.sqrt(var) return std	64.23 KB	2026-01-20 12:58
📄 nanfunctions.pyi from numpy.core.fromnumeric import ( amin, amax, argmin, argmax, sum, prod, cumsum, cumprod, mean, var, std ) from numpy.lib.function_base import ( median, percentile, quantile, ) __all__: list[str] # NOTE: In reaility these functions are not aliases but distinct functions # with identical signatures. nanmin = amin nanmax = amax nanargmin = argmin nanargmax = argmax nansum = sum nanprod = prod nancumsum = cumsum nancumprod = cumprod nanmean = mean nanvar = var nanstd = std nanmedian = median nanpercentile = percentile nanquantile = quantile	606 B	2026-01-20 12:58
📄 npyio.py import os import re import functools import itertools import warnings import weakref import contextlib import operator from operator import itemgetter, index as opindex, methodcaller from collections.abc import Mapping import numpy as np from . import format from ._datasource import DataSource from numpy.core import overrides from numpy.core.multiarray import packbits, unpackbits from numpy.core._multiarray_umath import _load_from_filelike from numpy.core.overrides import set_array_function_like_doc, set_module from ._iotools import ( LineSplitter, NameValidator, StringConverter, ConverterError, ConverterLockError, ConversionWarning, _is_string_like, has_nested_fields, flatten_dtype, easy_dtype, _decode_line ) from numpy.compat import ( asbytes, asstr, asunicode, os_fspath, os_PathLike, pickle ) __all__ = [ 'savetxt', 'loadtxt', 'genfromtxt', 'recfromtxt', 'recfromcsv', 'load', 'save', 'savez', 'savez_compressed', 'packbits', 'unpackbits', 'fromregex', 'DataSource' ] array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') class BagObj: """ BagObj(obj) Convert attribute look-ups to getitems on the object passed in. Parameters ---------- obj : class instance Object on which attribute look-up is performed. Examples -------- >>> from numpy.lib.npyio import BagObj as BO >>> class BagDemo: ... def __getitem__(self, key): # An instance of BagObj(BagDemo) ... # will call this method when any ... # attribute look-up is required ... result = "Doesn't matter what you want, " ... return result + "you're gonna get this" ... >>> demo_obj = BagDemo() >>> bagobj = BO(demo_obj) >>> bagobj.hello_there "Doesn't matter what you want, you're gonna get this" >>> bagobj.I_can_be_anything "Doesn't matter what you want, you're gonna get this" """ def __init__(self, obj): # Use weakref to make NpzFile objects collectable by refcount self._obj = weakref.proxy(obj) def __getattribute__(self, key): try: return object.__getattribute__(self, '_obj')[key] except KeyError: raise AttributeError(key) from None def __dir__(self): """ Enables dir(bagobj) to list the files in an NpzFile. This also enables tab-completion in an interpreter or IPython. """ return list(object.__getattribute__(self, '_obj').keys()) def zipfile_factory(file, args, kwargs): """ Create a ZipFile. Allows for Zip64, and the `file` argument can accept file, str, or pathlib.Path objects. `args` and `kwargs` are passed to the zipfile.ZipFile constructor. """ if not hasattr(file, 'read'): file = os_fspath(file) import zipfile kwargs['allowZip64'] = True return zipfile.ZipFile(file, args, *kwargs) class NpzFile(Mapping): """ NpzFile(fid) A dictionary-like object with lazy-loading of files in the zipped archive provided on construction. `NpzFile` is used to load files in the NumPy ``.npz`` data archive format. It assumes that files in the archive have a ``.npy`` extension, other files are ignored. The arrays and file strings are lazily loaded on either getitem access using ``obj['key']`` or attribute lookup using ``obj.f.key``. A list of all files (without ``.npy`` extensions) can be obtained with ``obj.files`` and the ZipFile object itself using ``obj.zip``. Attributes ---------- files : list of str List of all files in the archive with a ``.npy`` extension. zip : ZipFile instance The ZipFile object initialized with the zipped archive. f : BagObj instance An object on which attribute can be performed as an alternative to getitem access on the `NpzFile` instance itself. allow_pickle : bool, optional Allow loading pickled data. Default: False .. versionchanged:: 1.16.3 Made default False in response to CVE-2019-6446. pickle_kwargs : dict, optional Additional keyword arguments to pass on to pickle.load. These are only useful when loading object arrays saved on Python 2 when using Python 3. max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. This option is ignored when `allow_pickle` is passed. In that case the file is by definition trusted and the limit is unnecessary. Parameters ---------- fid : file or str The zipped archive to open. This is either a file-like object or a string containing the path to the archive. own_fid : bool, optional Whether NpzFile should close the file handle. Requires that `fid` is a file-like object. Examples -------- >>> from tempfile import TemporaryFile >>> outfile = TemporaryFile() >>> x = np.arange(10) >>> y = np.sin(x) >>> np.savez(outfile, x=x, y=y) >>> _ = outfile.seek(0) >>> npz = np.load(outfile) >>> isinstance(npz, np.lib.npyio.NpzFile) True >>> npz NpzFile 'object' with keys x, y >>> sorted(npz.files) ['x', 'y'] >>> npz['x'] # getitem access array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> npz.f.x # attribute lookup array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) """ # Make __exit__ safe if zipfile_factory raises an exception zip = None fid = None _MAX_REPR_ARRAY_COUNT = 5 def __init__(self, fid, own_fid=False, allow_pickle=False, pickle_kwargs=None, , max_header_size=format._MAX_HEADER_SIZE): # Import is postponed to here since zipfile depends on gzip, an # optional component of the so-called standard library. _zip = zipfile_factory(fid) self._files = _zip.namelist() self.files = [] self.allow_pickle = allow_pickle self.max_header_size = max_header_size self.pickle_kwargs = pickle_kwargs for x in self._files: if x.endswith('.npy'): self.files.append(x[:-4]) else: self.files.append(x) self.zip = _zip self.f = BagObj(self) if own_fid: self.fid = fid def __enter__(self): return self def __exit__(self, exc_type, exc_value, traceback): self.close() def close(self): """ Close the file. """ if self.zip is not None: self.zip.close() self.zip = None if self.fid is not None: self.fid.close() self.fid = None self.f = None # break reference cycle def __del__(self): self.close() # Implement the Mapping ABC def __iter__(self): return iter(self.files) def __len__(self): return len(self.files) def __getitem__(self, key): # FIXME: This seems like it will copy strings around # more than is strictly necessary. The zipfile # will read the string and then # the format.read_array will copy the string # to another place in memory. # It would be better if the zipfile could read # (or at least uncompress) the data # directly into the array memory. member = False if key in self._files: member = True elif key in self.files: member = True key += '.npy' if member: bytes = self.zip.open(key) magic = bytes.read(len(format.MAGIC_PREFIX)) bytes.close() if magic == format.MAGIC_PREFIX: bytes = self.zip.open(key) return format.read_array(bytes, allow_pickle=self.allow_pickle, pickle_kwargs=self.pickle_kwargs, max_header_size=self.max_header_size) else: return self.zip.read(key) else: raise KeyError(f"{key} is not a file in the archive") def __contains__(self, key): return (key in self._files or key in self.files) def __repr__(self): # Get filename or default to `object` if isinstance(self.fid, str): filename = self.fid else: filename = getattr(self.fid, "name", "object") # Get the name of arrays array_names = ', '.join(self.files[:self._MAX_REPR_ARRAY_COUNT]) if len(self.files) > self._MAX_REPR_ARRAY_COUNT: array_names += "..." return f"NpzFile {filename!r} with keys: {array_names}" @set_module('numpy') def load(file, mmap_mode=None, allow_pickle=False, fix_imports=True, encoding='ASCII', , max_header_size=format._MAX_HEADER_SIZE): """ Load arrays or pickled objects from ``.npy``, ``.npz`` or pickled files. .. warning:: Loading files that contain object arrays uses the ``pickle`` module, which is not secure against erroneous or maliciously constructed data. Consider passing ``allow_pickle=False`` to load data that is known not to contain object arrays for the safer handling of untrusted sources. Parameters ---------- file : file-like object, string, or pathlib.Path The file to read. File-like objects must support the ``seek()`` and ``read()`` methods and must always be opened in binary mode. Pickled files require that the file-like object support the ``readline()`` method as well. mmap_mode : {None, 'r+', 'r', 'w+', 'c'}, optional If not None, then memory-map the file, using the given mode (see `numpy.memmap` for a detailed description of the modes). A memory-mapped array is kept on disk. However, it can be accessed and sliced like any ndarray. Memory mapping is especially useful for accessing small fragments of large files without reading the entire file into memory. allow_pickle : bool, optional Allow loading pickled object arrays stored in npy files. Reasons for disallowing pickles include security, as loading pickled data can execute arbitrary code. If pickles are disallowed, loading object arrays will fail. Default: False .. versionchanged:: 1.16.3 Made default False in response to CVE-2019-6446. fix_imports : bool, optional Only useful when loading Python 2 generated pickled files on Python 3, which includes npy/npz files containing object arrays. If `fix_imports` is True, pickle will try to map the old Python 2 names to the new names used in Python 3. encoding : str, optional What encoding to use when reading Python 2 strings. Only useful when loading Python 2 generated pickled files in Python 3, which includes npy/npz files containing object arrays. Values other than 'latin1', 'ASCII', and 'bytes' are not allowed, as they can corrupt numerical data. Default: 'ASCII' max_header_size : int, optional Maximum allowed size of the header. Large headers may not be safe to load securely and thus require explicitly passing a larger value. See :py:func:`ast.literal_eval()` for details. This option is ignored when `allow_pickle` is passed. In that case the file is by definition trusted and the limit is unnecessary. Returns ------- result : array, tuple, dict, etc. Data stored in the file. For ``.npz`` files, the returned instance of NpzFile class must be closed to avoid leaking file descriptors. Raises ------ OSError If the input file does not exist or cannot be read. UnpicklingError If ``allow_pickle=True``, but the file cannot be loaded as a pickle. ValueError The file contains an object array, but ``allow_pickle=False`` given. EOFError When calling ``np.load`` multiple times on the same file handle, if all data has already been read See Also -------- save, savez, savez_compressed, loadtxt memmap : Create a memory-map to an array stored in a file on disk. lib.format.open_memmap : Create or load a memory-mapped ``.npy`` file. Notes ----- - If the file contains pickle data, then whatever object is stored in the pickle is returned. - If the file is a ``.npy`` file, then a single array is returned. - If the file is a ``.npz`` file, then a dictionary-like object is returned, containing ``{filename: array}`` key-value pairs, one for each file in the archive. - If the file is a ``.npz`` file, the returned value supports the context manager protocol in a similar fashion to the open function:: with load('foo.npz') as data: a = data['a'] The underlying file descriptor is closed when exiting the 'with' block. Examples -------- Store data to disk, and load it again: >>> np.save('/tmp/123', np.array([[1, 2, 3], [4, 5, 6]])) >>> np.load('/tmp/123.npy') array([[1, 2, 3], [4, 5, 6]]) Store compressed data to disk, and load it again: >>> a=np.array([[1, 2, 3], [4, 5, 6]]) >>> b=np.array([1, 2]) >>> np.savez('/tmp/123.npz', a=a, b=b) >>> data = np.load('/tmp/123.npz') >>> data['a'] array([[1, 2, 3], [4, 5, 6]]) >>> data['b'] array([1, 2]) >>> data.close() Mem-map the stored array, and then access the second row directly from disk: >>> X = np.load('/tmp/123.npy', mmap_mode='r') >>> X[1, :] memmap([4, 5, 6]) """ if encoding not in ('ASCII', 'latin1', 'bytes'): # The 'encoding' value for pickle also affects what encoding # the serialized binary data of NumPy arrays is loaded # in. Pickle does not pass on the encoding information to # NumPy. The unpickling code in numpy.core.multiarray is # written to assume that unicode data appearing where binary # should be is in 'latin1'. 'bytes' is also safe, as is 'ASCII'. # # Other encoding values can corrupt binary data, and we # purposefully disallow them. For the same reason, the errors= # argument is not exposed, as values other than 'strict' # result can similarly silently corrupt numerical data. raise ValueError("encoding must be 'ASCII', 'latin1', or 'bytes'") pickle_kwargs = dict(encoding=encoding, fix_imports=fix_imports) with contextlib.ExitStack() as stack: if hasattr(file, 'read'): fid = file own_fid = False else: fid = stack.enter_context(open(os_fspath(file), "rb")) own_fid = True # Code to distinguish from NumPy binary files and pickles. _ZIP_PREFIX = b'PK\x03\x04' _ZIP_SUFFIX = b'PK\x05\x06' # empty zip files start with this N = len(format.MAGIC_PREFIX) magic = fid.read(N) if not magic: raise EOFError("No data left in file") # If the file size is less than N, we need to make sure not # to seek past the beginning of the file fid.seek(-min(N, len(magic)), 1) # back-up if magic.startswith(_ZIP_PREFIX) or magic.startswith(_ZIP_SUFFIX): # zip-file (assume .npz) # Potentially transfer file ownership to NpzFile stack.pop_all() ret = NpzFile(fid, own_fid=own_fid, allow_pickle=allow_pickle, pickle_kwargs=pickle_kwargs, max_header_size=max_header_size) return ret elif magic == format.MAGIC_PREFIX: # .npy file if mmap_mode: if allow_pickle: max_header_size = 264 return format.open_memmap(file, mode=mmap_mode, max_header_size=max_header_size) else: return format.read_array(fid, allow_pickle=allow_pickle, pickle_kwargs=pickle_kwargs, max_header_size=max_header_size) else: # Try a pickle if not allow_pickle: raise ValueError("Cannot load file containing pickled data " "when allow_pickle=False") try: return pickle.load(fid, pickle_kwargs) except Exception as e: raise pickle.UnpicklingError( f"Failed to interpret file {file!r} as a pickle") from e def _save_dispatcher(file, arr, allow_pickle=None, fix_imports=None): return (arr,) @array_function_dispatch(_save_dispatcher) def save(file, arr, allow_pickle=True, fix_imports=True): """ Save an array to a binary file in NumPy ``.npy`` format. Parameters ---------- file : file, str, or pathlib.Path File or filename to which the data is saved. If file is a file-object, then the filename is unchanged. If file is a string or Path, a ``.npy`` extension will be appended to the filename if it does not already have one. arr : array_like Array data to be saved. allow_pickle : bool, optional Allow saving object arrays using Python pickles. Reasons for disallowing pickles include security (loading pickled data can execute arbitrary code) and portability (pickled objects may not be loadable on different Python installations, for example if the stored objects require libraries that are not available, and not all pickled data is compatible between Python 2 and Python 3). Default: True fix_imports : bool, optional Only useful in forcing objects in object arrays on Python 3 to be pickled in a Python 2 compatible way. If `fix_imports` is True, pickle will try to map the new Python 3 names to the old module names used in Python 2, so that the pickle data stream is readable with Python 2. See Also -------- savez : Save several arrays into a ``.npz`` archive savetxt, load Notes ----- For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. Any data saved to the file is appended to the end of the file. Examples -------- >>> from tempfile import TemporaryFile >>> outfile = TemporaryFile() >>> x = np.arange(10) >>> np.save(outfile, x) >>> _ = outfile.seek(0) # Only needed here to simulate closing & reopening file >>> np.load(outfile) array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) >>> with open('test.npy', 'wb') as f: ... np.save(f, np.array([1, 2])) ... np.save(f, np.array([1, 3])) >>> with open('test.npy', 'rb') as f: ... a = np.load(f) ... b = np.load(f) >>> print(a, b) # [1 2] [1 3] """ if hasattr(file, 'write'): file_ctx = contextlib.nullcontext(file) else: file = os_fspath(file) if not file.endswith('.npy'): file = file + '.npy' file_ctx = open(file, "wb") with file_ctx as fid: arr = np.asanyarray(arr) format.write_array(fid, arr, allow_pickle=allow_pickle, pickle_kwargs=dict(fix_imports=fix_imports)) def _savez_dispatcher(file, args, *kwds): yield from args yield from kwds.values() @array_function_dispatch(_savez_dispatcher) def savez(file, args, *kwds): """Save several arrays into a single file in uncompressed ``.npz`` format. Provide arrays as keyword arguments to store them under the corresponding name in the output file: ``savez(fn, x=x, y=y)``. If arrays are specified as positional arguments, i.e., ``savez(fn, x, y)``, their names will be `arr_0`, `arr_1`, etc. Parameters ---------- file : str or file Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the ``.npz`` extension will be appended to the filename if it is not already there. args : Arguments, optional Arrays to save to the file. Please use keyword arguments (see `kwds` below) to assign names to arrays. Arrays specified as args will be named "arr_0", "arr_1", and so on. kwds : Keyword arguments, optional Arrays to save to the file. Each array will be saved to the output file with its corresponding keyword name. Returns ------- None See Also -------- save : Save a single array to a binary file in NumPy format. savetxt : Save an array to a file as plain text. savez_compressed : Save several arrays into a compressed ``.npz`` archive Notes ----- The ``.npz`` file format is a zipped archive of files named after the variables they contain. The archive is not compressed and each file in the archive contains one variable in ``.npy`` format. For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. When opening the saved ``.npz`` file with `load` a `NpzFile` object is returned. This is a dictionary-like object which can be queried for its list of arrays (with the ``.files`` attribute), and for the arrays themselves. Keys passed in `kwds` are used as filenames inside the ZIP archive. Therefore, keys should be valid filenames; e.g., avoid keys that begin with ``/`` or contain ``.``. When naming variables with keyword arguments, it is not possible to name a variable ``file``, as this would cause the ``file`` argument to be defined twice in the call to ``savez``. Examples -------- >>> from tempfile import TemporaryFile >>> outfile = TemporaryFile() >>> x = np.arange(10) >>> y = np.sin(x) Using `savez` with \\args, the arrays are saved with default names. >>> np.savez(outfile, x, y) >>> _ = outfile.seek(0) # Only needed here to simulate closing & reopening file >>> npzfile = np.load(outfile) >>> npzfile.files ['arr_0', 'arr_1'] >>> npzfile['arr_0'] array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) Using `savez` with \\*kwds, the arrays are saved with the keyword names. >>> outfile = TemporaryFile() >>> np.savez(outfile, x=x, y=y) >>> _ = outfile.seek(0) >>> npzfile = np.load(outfile) >>> sorted(npzfile.files) ['x', 'y'] >>> npzfile['x'] array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]) """ _savez(file, args, kwds, False) def _savez_compressed_dispatcher(file, args, *kwds): yield from args yield from kwds.values() @array_function_dispatch(_savez_compressed_dispatcher) def savez_compressed(file, args, *kwds): """ Save several arrays into a single file in compressed ``.npz`` format. Provide arrays as keyword arguments to store them under the corresponding name in the output file: ``savez(fn, x=x, y=y)``. If arrays are specified as positional arguments, i.e., ``savez(fn, x, y)``, their names will be `arr_0`, `arr_1`, etc. Parameters ---------- file : str or file Either the filename (string) or an open file (file-like object) where the data will be saved. If file is a string or a Path, the ``.npz`` extension will be appended to the filename if it is not already there. args : Arguments, optional Arrays to save to the file. Please use keyword arguments (see `kwds` below) to assign names to arrays. Arrays specified as args will be named "arr_0", "arr_1", and so on. kwds : Keyword arguments, optional Arrays to save to the file. Each array will be saved to the output file with its corresponding keyword name. Returns ------- None See Also -------- numpy.save : Save a single array to a binary file in NumPy format. numpy.savetxt : Save an array to a file as plain text. numpy.savez : Save several arrays into an uncompressed ``.npz`` file format numpy.load : Load the files created by savez_compressed. Notes ----- The ``.npz`` file format is a zipped archive of files named after the variables they contain. The archive is compressed with ``zipfile.ZIP_DEFLATED`` and each file in the archive contains one variable in ``.npy`` format. For a description of the ``.npy`` format, see :py:mod:`numpy.lib.format`. When opening the saved ``.npz`` file with `load` a `NpzFile` object is returned. This is a dictionary-like object which can be queried for its list of arrays (with the ``.files`` attribute), and for the arrays themselves. Examples -------- >>> test_array = np.random.rand(3, 2) >>> test_vector = np.random.rand(4) >>> np.savez_compressed('/tmp/123', a=test_array, b=test_vector) >>> loaded = np.load('/tmp/123.npz') >>> print(np.array_equal(test_array, loaded['a'])) True >>> print(np.array_equal(test_vector, loaded['b'])) True """ _savez(file, args, kwds, True) def _savez(file, args, kwds, compress, allow_pickle=True, pickle_kwargs=None): # Import is postponed to here since zipfile depends on gzip, an optional # component of the so-called standard library. import zipfile if not hasattr(file, 'write'): file = os_fspath(file) if not file.endswith('.npz'): file = file + '.npz' namedict = kwds for i, val in enumerate(args): key = 'arr_%d' % i if key in namedict.keys(): raise ValueError( "Cannot use un-named variables and keyword %s" % key) namedict[key] = val if compress: compression = zipfile.ZIP_DEFLATED else: compression = zipfile.ZIP_STORED zipf = zipfile_factory(file, mode="w", compression=compression) for key, val in namedict.items(): fname = key + '.npy' val = np.asanyarray(val) # always force zip64, gh-10776 with zipf.open(fname, 'w', force_zip64=True) as fid: format.write_array(fid, val, allow_pickle=allow_pickle, pickle_kwargs=pickle_kwargs) zipf.close() def _ensure_ndmin_ndarray_check_param(ndmin): """Just checks if the param ndmin is supported on _ensure_ndmin_ndarray. It is intended to be used as verification before running anything expensive. e.g. loadtxt, genfromtxt """ # Check correctness of the values of `ndmin` if ndmin not in [0, 1, 2]: raise ValueError(f"Illegal value of ndmin keyword: {ndmin}") def _ensure_ndmin_ndarray(a, , ndmin: int): """This is a helper function of loadtxt and genfromtxt to ensure proper minimum dimension as requested ndim : int. Supported values 1, 2, 3 ^^ whenever this changes, keep in sync with _ensure_ndmin_ndarray_check_param """ # Verify that the array has at least dimensions `ndmin`. # Tweak the size and shape of the arrays - remove extraneous dimensions if a.ndim > ndmin: a = np.squeeze(a) # and ensure we have the minimum number of dimensions asked for # - has to be in this order for the odd case ndmin=1, a.squeeze().ndim=0 if a.ndim < ndmin: if ndmin == 1: a = np.atleast_1d(a) elif ndmin == 2: a = np.atleast_2d(a).T return a # amount of lines loadtxt reads in one chunk, can be overridden for testing _loadtxt_chunksize = 50000 def _check_nonneg_int(value, name="argument"): try: operator.index(value) except TypeError: raise TypeError(f"{name} must be an integer") from None if value < 0: raise ValueError(f"{name} must be nonnegative") def _preprocess_comments(iterable, comments, encoding): """ Generator that consumes a line iterated iterable and strips out the multiple (or multi-character) comments from lines. This is a pre-processing step to achieve feature parity with loadtxt (we assume that this feature is a nieche feature). """ for line in iterable: if isinstance(line, bytes): # Need to handle conversion here, or the splitting would fail line = line.decode(encoding) for c in comments: line = line.split(c, 1)[0] yield line # The number of rows we read in one go if confronted with a parametric dtype _loadtxt_chunksize = 50000 def _read(fname, , delimiter=',', comment='#', quote='"', imaginary_unit='j', usecols=None, skiplines=0, max_rows=None, converters=None, ndmin=None, unpack=False, dtype=np.float64, encoding="bytes"): r""" Read a NumPy array from a text file. Parameters ---------- fname : str or file object The filename or the file to be read. delimiter : str, optional Field delimiter of the fields in line of the file. Default is a comma, ','. If None any sequence of whitespace is considered a delimiter. comment : str or sequence of str or None, optional Character that begins a comment. All text from the comment character to the end of the line is ignored. Multiple comments or multiple-character comment strings are supported, but may be slower and `quote` must be empty if used. Use None to disable all use of comments. quote : str or None, optional Character that is used to quote string fields. Default is '"' (a double quote). Use None to disable quote support. imaginary_unit : str, optional Character that represent the imaginay unit `sqrt(-1)`. Default is 'j'. usecols : array_like, optional A one-dimensional array of integer column numbers. These are the columns from the file to be included in the array. If this value is not given, all the columns are used. skiplines : int, optional Number of lines to skip before interpreting the data in the file. max_rows : int, optional Maximum number of rows of data to read. Default is to read the entire file. converters : dict or callable, optional A function to parse all columns strings into the desired value, or a dictionary mapping column number to a parser function. E.g. if column 0 is a date string: ``converters = {0: datestr2num}``. Converters can also be used to provide a default value for missing data, e.g. ``converters = lambda s: float(s.strip() or 0)`` will convert empty fields to 0. Default: None ndmin : int, optional Minimum dimension of the array returned. Allowed values are 0, 1 or 2. Default is 0. unpack : bool, optional If True, the returned array is transposed, so that arguments may be unpacked using ``x, y, z = read(...)``. When used with a structured data-type, arrays are returned for each field. Default is False. dtype : numpy data type A NumPy dtype instance, can be a structured dtype to map to the columns of the file. encoding : str, optional Encoding used to decode the inputfile. The special value 'bytes' (the default) enables backwards-compatible behavior for `converters`, ensuring that inputs to the converter functions are encoded bytes objects. The special value 'bytes' has no additional effect if ``converters=None``. If encoding is ``'bytes'`` or ``None``, the default system encoding is used. Returns ------- ndarray NumPy array. Examples -------- First we create a file for the example. >>> s1 = '1.0,2.0,3.0\n4.0,5.0,6.0\n' >>> with open('example1.csv', 'w') as f: ... f.write(s1) >>> a1 = read_from_filename('example1.csv') >>> a1 array([[1., 2., 3.], [4., 5., 6.]]) The second example has columns with different data types, so a one-dimensional array with a structured data type is returned. The tab character is used as the field delimiter. >>> s2 = '1.0\t10\talpha\n2.3\t25\tbeta\n4.5\t16\tgamma\n' >>> with open('example2.tsv', 'w') as f: ... f.write(s2) >>> a2 = read_from_filename('example2.tsv', delimiter='\t') >>> a2 array([(1. , 10, b'alpha'), (2.3, 25, b'beta'), (4.5, 16, b'gamma')], dtype=[('f0', '<f8'), ('f1', 'u1'), ('f2', 'S5')]) """ # Handle special 'bytes' keyword for encoding byte_converters = False if encoding == 'bytes': encoding = None byte_converters = True if dtype is None: raise TypeError("a dtype must be provided.") dtype = np.dtype(dtype) read_dtype_via_object_chunks = None if dtype.kind in 'SUM' and ( dtype == "S0" or dtype == "U0" or dtype == "M8" or dtype == 'm8'): # This is a legacy "flexible" dtype. We do not truly support # parametric dtypes currently (no dtype discovery step in the core), # but have to support these for backward compatibility. read_dtype_via_object_chunks = dtype dtype = np.dtype(object) if usecols is not None: # Allow usecols to be a single int or a sequence of ints, the C-code # handles the rest try: usecols = list(usecols) except TypeError: usecols = [usecols] _ensure_ndmin_ndarray_check_param(ndmin) if comment is None: comments = None else: # assume comments are a sequence of strings if "" in comment: raise ValueError( "comments cannot be an empty string. Use comments=None to " "disable comments." ) comments = tuple(comment) comment = None if len(comments) == 0: comments = None # No comments at all elif len(comments) == 1: # If there is only one comment, and that comment has one character, # the normal parsing can deal with it just fine. if isinstance(comments[0], str) and len(comments[0]) == 1: comment = comments[0] comments = None else: # Input validation if there are multiple comment characters if delimiter in comments: raise TypeError( f"Comment characters '{comments}' cannot include the " f"delimiter '{delimiter}'" ) # comment is now either a 1 or 0 character string or a tuple: if comments is not None: # Note: An earlier version support two character comments (and could # have been extended to multiple characters, we assume this is # rare enough to not optimize for. if quote is not None: raise ValueError( "when multiple comments or a multi-character comment is " "given, quotes are not supported. In this case quotechar " "must be set to None.") if len(imaginary_unit) != 1: raise ValueError('len(imaginary_unit) must be 1.') _check_nonneg_int(skiplines) if max_rows is not None: _check_nonneg_int(max_rows) else: # Passing -1 to the C code means "read the entire file". max_rows = -1 fh_closing_ctx = contextlib.nullcontext() filelike = False try: if isinstance(fname, os.PathLike): fname = os.fspath(fname) if isinstance(fname, str): fh = np.lib._datasource.open(fname, 'rt', encoding=encoding) if encoding is None: encoding = getattr(fh, 'encoding', 'latin1') fh_closing_ctx = contextlib.closing(fh) data = fh filelike = True else: if encoding is None: encoding = getattr(fname, 'encoding', 'latin1') data = iter(fname) except TypeError as e: raise ValueError( f"fname must be a string, filehandle, list of strings,\n" f"or generator. Got {type(fname)} instead.") from e with fh_closing_ctx: if comments is not None: if filelike: data = iter(data) filelike = False data = _preprocess_comments(data, comments, encoding) if read_dtype_via_object_chunks is None: arr = _load_from_filelike( data, delimiter=delimiter, comment=comment, quote=quote, imaginary_unit=imaginary_unit, usecols=usecols, skiplines=skiplines, max_rows=max_rows, converters=converters, dtype=dtype, encoding=encoding, filelike=filelike, byte_converters=byte_converters) else: # This branch reads the file into chunks of object arrays and then # casts them to the desired actual dtype. This ensures correct # string-length and datetime-unit discovery (like `arr.astype()`). # Due to chunking, certain error reports are less clear, currently. if filelike: data = iter(data) # cannot chunk when reading from file c_byte_converters = False if read_dtype_via_object_chunks == "S": c_byte_converters = True # Use latin1 rather than ascii chunks = [] while max_rows != 0: if max_rows < 0: chunk_size = _loadtxt_chunksize else: chunk_size = min(_loadtxt_chunksize, max_rows) next_arr = _load_from_filelike( data, delimiter=delimiter, comment=comment, quote=quote, imaginary_unit=imaginary_unit, usecols=usecols, skiplines=skiplines, max_rows=max_rows, converters=converters, dtype=dtype, encoding=encoding, filelike=filelike, byte_converters=byte_converters, c_byte_converters=c_byte_converters) # Cast here already. We hope that this is better even for # large files because the storage is more compact. It could # be adapted (in principle the concatenate could cast). chunks.append(next_arr.astype(read_dtype_via_object_chunks)) skiprows = 0 # Only have to skip for first chunk if max_rows >= 0: max_rows -= chunk_size if len(next_arr) < chunk_size: # There was less data than requested, so we are done. break # Need at least one chunk, but if empty, the last one may have # the wrong shape. if len(chunks) > 1 and len(chunks[-1]) == 0: del chunks[-1] if len(chunks) == 1: arr = chunks[0] else: arr = np.concatenate(chunks, axis=0) # NOTE: ndmin works as advertised for structured dtypes, but normally # these would return a 1D result plus the structured dimension, # so ndmin=2 adds a third dimension even when no squeezing occurs. # A `squeeze=False` could be a better solution (pandas uses squeeze). arr = _ensure_ndmin_ndarray(arr, ndmin=ndmin) if arr.shape: if arr.shape[0] == 0: warnings.warn( f'loadtxt: input contained no data: "{fname}"', category=UserWarning, stacklevel=3 ) if unpack: # Unpack structured dtypes if requested: dt = arr.dtype if dt.names is not None: # For structured arrays, return an array for each field. return [arr[field] for field in dt.names] else: return arr.T else: return arr @set_array_function_like_doc @set_module('numpy') def loadtxt(fname, dtype=float, comments='#', delimiter=None, converters=None, skiprows=0, usecols=None, unpack=False, ndmin=0, encoding='bytes', max_rows=None, , quotechar=None, like=None): r""" Load data from a text file. Parameters ---------- fname : file, str, pathlib.Path, list of str, generator File, filename, list, or generator to read. If the filename extension is ``.gz`` or ``.bz2``, the file is first decompressed. Note that generators must return bytes or strings. The strings in a list or produced by a generator are treated as lines. dtype : data-type, optional Data-type of the resulting array; default: float. If this is a structured data-type, the resulting array will be 1-dimensional, and each row will be interpreted as an element of the array. In this case, the number of columns used must match the number of fields in the data-type. comments : str or sequence of str or None, optional The characters or list of characters used to indicate the start of a comment. None implies no comments. For backwards compatibility, byte strings will be decoded as 'latin1'. The default is '#'. delimiter : str, optional The character used to separate the values. For backwards compatibility, byte strings will be decoded as 'latin1'. The default is whitespace. .. versionchanged:: 1.23.0 Only single character delimiters are supported. Newline characters cannot be used as the delimiter. converters : dict or callable, optional Converter functions to customize value parsing. If `converters` is callable, the function is applied to all columns, else it must be a dict that maps column number to a parser function. See examples for further details. Default: None. .. versionchanged:: 1.23.0 The ability to pass a single callable to be applied to all columns was added. skiprows : int, optional Skip the first `skiprows` lines, including comments; default: 0. usecols : int or sequence, optional Which columns to read, with 0 being the first. For example, ``usecols = (1,4,5)`` will extract the 2nd, 5th and 6th columns. The default, None, results in all columns being read. .. versionchanged:: 1.11.0 When a single column has to be read it is possible to use an integer instead of a tuple. E.g ``usecols = 3`` reads the fourth column the same way as ``usecols = (3,)`` would. unpack : bool, optional If True, the returned array is transposed, so that arguments may be unpacked using ``x, y, z = loadtxt(...)``. When used with a structured data-type, arrays are returned for each field. Default is False. ndmin : int, optional The returned array will have at least `ndmin` dimensions. Otherwise mono-dimensional axes will be squeezed. Legal values: 0 (default), 1 or 2. .. versionadded:: 1.6.0 encoding : str, optional Encoding used to decode the inputfile. Does not apply to input streams. The special value 'bytes' enables backward compatibility workarounds that ensures you receive byte arrays as results if possible and passes 'latin1' encoded strings to converters. Override this value to receive unicode arrays and pass strings as input to converters. If set to None the system default is used. The default value is 'bytes'. .. versionadded:: 1.14.0 max_rows : int, optional Read `max_rows` rows of content after `skiprows` lines. The default is to read all the rows. Note that empty rows containing no data such as empty lines and comment lines are not counted towards `max_rows`, while such lines are counted in `skiprows`. .. versionadded:: 1.16.0 .. versionchanged:: 1.23.0 Lines containing no data, including comment lines (e.g., lines starting with '#' or as specified via `comments`) are not counted towards `max_rows`. quotechar : unicode character or None, optional The character used to denote the start and end of a quoted item. Occurrences of the delimiter or comment characters are ignored within a quoted item. The default value is ``quotechar=None``, which means quoting support is disabled. If two consecutive instances of `quotechar` are found within a quoted field, the first is treated as an escape character. See examples. .. versionadded:: 1.23.0 ${ARRAY_FUNCTION_LIKE} .. versionadded:: 1.20.0 Returns ------- out : ndarray Data read from the text file. See Also -------- load, fromstring, fromregex genfromtxt : Load data with missing values handled as specified. scipy.io.loadmat : reads MATLAB data files Notes ----- This function aims to be a fast reader for simply formatted files. The `genfromtxt` function provides more sophisticated handling of, e.g., lines with missing values. Each row in the input text file must have the same number of values to be able to read all values. If all rows do not have same number of values, a subset of up to n columns (where n is the least number of values present in all rows) can be read by specifying the columns via `usecols`. .. versionadded:: 1.10.0 The strings produced by the Python float.hex method can be used as input for floats. Examples -------- >>> from io import StringIO # StringIO behaves like a file object >>> c = StringIO("0 1\n2 3") >>> np.loadtxt(c) array([[0., 1.], [2., 3.]]) >>> d = StringIO("M 21 72\nF 35 58") >>> np.loadtxt(d, dtype={'names': ('gender', 'age', 'weight'), ... 'formats': ('S1', 'i4', 'f4')}) array([(b'M', 21, 72.), (b'F', 35, 58.)], dtype=[('gender', 'S1'), ('age', '<i4'), ('weight', '<f4')]) >>> c = StringIO("1,0,2\n3,0,4") >>> x, y = np.loadtxt(c, delimiter=',', usecols=(0, 2), unpack=True) >>> x array([1., 3.]) >>> y array([2., 4.]) The `converters` argument is used to specify functions to preprocess the text prior to parsing. `converters` can be a dictionary that maps preprocessing functions to each column: >>> s = StringIO("1.618, 2.296\n3.141, 4.669\n") >>> conv = { ... 0: lambda x: np.floor(float(x)), # conversion fn for column 0 ... 1: lambda x: np.ceil(float(x)), # conversion fn for column 1 ... } >>> np.loadtxt(s, delimiter=",", converters=conv) array([[1., 3.], [3., 5.]]) `converters` can be a callable instead of a dictionary, in which case it is applied to all columns: >>> s = StringIO("0xDE 0xAD\n0xC0 0xDE") >>> import functools >>> conv = functools.partial(int, base=16) >>> np.loadtxt(s, converters=conv) array([[222., 173.], [192., 222.]]) This example shows how `converters` can be used to convert a field with a trailing minus sign into a negative number. >>> s = StringIO('10.01 31.25-\n19.22 64.31\n17.57- 63.94') >>> def conv(fld): ... return -float(fld[:-1]) if fld.endswith(b'-') else float(fld) ... >>> np.loadtxt(s, converters=conv) array([[ 10.01, -31.25], [ 19.22, 64.31], [-17.57, 63.94]]) Using a callable as the converter can be particularly useful for handling values with different formatting, e.g. floats with underscores: >>> s = StringIO("1 2.7 100_000") >>> np.loadtxt(s, converters=float) array([1.e+00, 2.7e+00, 1.e+05]) This idea can be extended to automatically handle values specified in many different formats: >>> def conv(val): ... try: ... return float(val) ... except ValueError: ... return float.fromhex(val) >>> s = StringIO("1, 2.5, 3_000, 0b4, 0x1.4000000000000p+2") >>> np.loadtxt(s, delimiter=",", converters=conv, encoding=None) array([1.0e+00, 2.5e+00, 3.0e+03, 1.8e+02, 5.0e+00]) Note that with the default ``encoding="bytes"``, the inputs to the converter function are latin-1 encoded byte strings. To deactivate the implicit encoding prior to conversion, use ``encoding=None`` >>> s = StringIO('10.01 31.25-\n19.22 64.31\n17.57- 63.94') >>> conv = lambda x: -float(x[:-1]) if x.endswith('-') else float(x) >>> np.loadtxt(s, converters=conv, encoding=None) array([[ 10.01, -31.25], [ 19.22, 64.31], [-17.57, 63.94]]) Support for quoted fields is enabled with the `quotechar` parameter. Comment and delimiter characters are ignored when they appear within a quoted item delineated by `quotechar`: >>> s = StringIO('"alpha, #42", 10.0\n"beta, #64", 2.0\n') >>> dtype = np.dtype([("label", "U12"), ("value", float)]) >>> np.loadtxt(s, dtype=dtype, delimiter=",", quotechar='"') array([('alpha, #42', 10.), ('beta, #64', 2.)], dtype=[('label', '<U12'), ('value', '<f8')]) Quoted fields can be separated by multiple whitespace characters: >>> s = StringIO('"alpha, #42" 10.0\n"beta, #64" 2.0\n') >>> dtype = np.dtype([("label", "U12"), ("value", float)]) >>> np.loadtxt(s, dtype=dtype, delimiter=None, quotechar='"') array([('alpha, #42', 10.), ('beta, #64', 2.)], dtype=[('label', '<U12'), ('value', '<f8')]) Two consecutive quote characters within a quoted field are treated as a single escaped character: >>> s = StringIO('"Hello, my name is ""Monty""!"') >>> np.loadtxt(s, dtype="U", delimiter=",", quotechar='"') array('Hello, my name is "Monty"!', dtype='<U26') Read subset of columns when all rows do not contain equal number of values: >>> d = StringIO("1 2\n2 4\n3 9 12\n4 16 20") >>> np.loadtxt(d, usecols=(0, 1)) array([[ 1., 2.], [ 2., 4.], [ 3., 9.], [ 4., 16.]]) """ if like is not None: return _loadtxt_with_like( like, fname, dtype=dtype, comments=comments, delimiter=delimiter, converters=converters, skiprows=skiprows, usecols=usecols, unpack=unpack, ndmin=ndmin, encoding=encoding, max_rows=max_rows ) if isinstance(delimiter, bytes): delimiter.decode("latin1") if dtype is None: dtype = np.float64 comment = comments # Control character type conversions for Py3 convenience if comment is not None: if isinstance(comment, (str, bytes)): comment = [comment] comment = [ x.decode('latin1') if isinstance(x, bytes) else x for x in comment] if isinstance(delimiter, bytes): delimiter = delimiter.decode('latin1') arr = _read(fname, dtype=dtype, comment=comment, delimiter=delimiter, converters=converters, skiplines=skiprows, usecols=usecols, unpack=unpack, ndmin=ndmin, encoding=encoding, max_rows=max_rows, quote=quotechar) return arr _loadtxt_with_like = array_function_dispatch()(loadtxt) def _savetxt_dispatcher(fname, X, fmt=None, delimiter=None, newline=None, header=None, footer=None, comments=None, encoding=None): return (X,) @array_function_dispatch(_savetxt_dispatcher) def savetxt(fname, X, fmt='%.18e', delimiter=' ', newline='\n', header='', footer='', comments='# ', encoding=None): """ Save an array to a text file. Parameters ---------- fname : filename or file handle If the filename ends in ``.gz``, the file is automatically saved in compressed gzip format. `loadtxt` understands gzipped files transparently. X : 1D or 2D array_like Data to be saved to a text file. fmt : str or sequence of strs, optional A single format (%10.5f), a sequence of formats, or a multi-format string, e.g. 'Iteration %d -- %10.5f', in which case `delimiter` is ignored. For complex `X`, the legal options for `fmt` are: * a single specifier, `fmt='%.4e'`, resulting in numbers formatted like `' (%s+%sj)' % (fmt, fmt)` * a full string specifying every real and imaginary part, e.g. `' %.4e %+.4ej %.4e %+.4ej %.4e %+.4ej'` for 3 columns * a list of specifiers, one per column - in this case, the real and imaginary part must have separate specifiers, e.g. `['%.3e + %.3ej', '(%.15e%+.15ej)']` for 2 columns delimiter : str, optional String or character separating columns. newline : str, optional String or character separating lines. .. versionadded:: 1.5.0 header : str, optional String that will be written at the beginning of the file. .. versionadded:: 1.7.0 footer : str, optional String that will be written at the end of the file. .. versionadded:: 1.7.0 comments : str, optional String that will be prepended to the ``header`` and ``footer`` strings, to mark them as comments. Default: '# ', as expected by e.g. ``numpy.loadtxt``. .. versionadded:: 1.7.0 encoding : {None, str}, optional Encoding used to encode the outputfile. Does not apply to output streams. If the encoding is something other than 'bytes' or 'latin1' you will not be able to load the file in NumPy versions < 1.14. Default is 'latin1'. .. versionadded:: 1.14.0 See Also -------- save : Save an array to a binary file in NumPy ``.npy`` format savez : Save several arrays into an uncompressed ``.npz`` archive savez_compressed : Save several arrays into a compressed ``.npz`` archive Notes ----- Further explanation of the `fmt` parameter (``%[flag]width[.precision]specifier``): flags: ``-`` : left justify ``+`` : Forces to precede result with + or -. ``0`` : Left pad the number with zeros instead of space (see width). width: Minimum number of characters to be printed. The value is not truncated if it has more characters. precision: - For integer specifiers (eg. ``d,i,o,x``), the minimum number of digits. - For ``e, E`` and ``f`` specifiers, the number of digits to print after the decimal point. - For ``g`` and ``G``, the maximum number of significant digits. - For ``s``, the maximum number of characters. specifiers: ``c`` : character ``d`` or ``i`` : signed decimal integer ``e`` or ``E`` : scientific notation with ``e`` or ``E``. ``f`` : decimal floating point ``g,G`` : use the shorter of ``e,E`` or ``f`` ``o`` : signed octal ``s`` : string of characters ``u`` : unsigned decimal integer ``x,X`` : unsigned hexadecimal integer This explanation of ``fmt`` is not complete, for an exhaustive specification see [1]_. References ---------- .. [1] `Format Specification Mini-Language <https://docs.python.org/library/string.html#format-specification-mini-language>`_, Python Documentation. Examples -------- >>> x = y = z = np.arange(0.0,5.0,1.0) >>> np.savetxt('test.out', x, delimiter=',') # X is an array >>> np.savetxt('test.out', (x,y,z)) # x,y,z equal sized 1D arrays >>> np.savetxt('test.out', x, fmt='%1.4e') # use exponential notation """ # Py3 conversions first if isinstance(fmt, bytes): fmt = asstr(fmt) delimiter = asstr(delimiter) class WriteWrap: """Convert to bytes on bytestream inputs. """ def __init__(self, fh, encoding): self.fh = fh self.encoding = encoding self.do_write = self.first_write def close(self): self.fh.close() def write(self, v): self.do_write(v) def write_bytes(self, v): if isinstance(v, bytes): self.fh.write(v) else: self.fh.write(v.encode(self.encoding)) def write_normal(self, v): self.fh.write(asunicode(v)) def first_write(self, v): try: self.write_normal(v) self.write = self.write_normal except TypeError: # input is probably a bytestream self.write_bytes(v) self.write = self.write_bytes own_fh = False if isinstance(fname, os_PathLike): fname = os_fspath(fname) if _is_string_like(fname): # datasource doesn't support creating a new file ... open(fname, 'wt').close() fh = np.lib._datasource.open(fname, 'wt', encoding=encoding) own_fh = True elif hasattr(fname, 'write'): # wrap to handle byte output streams fh = WriteWrap(fname, encoding or 'latin1') else: raise ValueError('fname must be a string or file handle') try: X = np.asarray(X) # Handle 1-dimensional arrays if X.ndim == 0 or X.ndim > 2: raise ValueError( "Expected 1D or 2D array, got %dD array instead" % X.ndim) elif X.ndim == 1: # Common case -- 1d array of numbers if X.dtype.names is None: X = np.atleast_2d(X).T ncol = 1 # Complex dtype -- each field indicates a separate column else: ncol = len(X.dtype.names) else: ncol = X.shape[1] iscomplex_X = np.iscomplexobj(X) # `fmt` can be a string with multiple insertion points or a # list of formats. E.g. '%10.5f\t%10d' or ('%10.5f', '$10d') if type(fmt) in (list, tuple): if len(fmt) != ncol: raise AttributeError('fmt has wrong shape. %s' % str(fmt)) format = asstr(delimiter).join(map(asstr, fmt)) elif isinstance(fmt, str): n_fmt_chars = fmt.count('%') error = ValueError('fmt has wrong number of %% formats: %s' % fmt) if n_fmt_chars == 1: if iscomplex_X: fmt = [' (%s+%sj)' % (fmt, fmt), ] * ncol else: fmt = [fmt, ] * ncol format = delimiter.join(fmt) elif iscomplex_X and n_fmt_chars != (2 * ncol): raise error elif ((not iscomplex_X) and n_fmt_chars != ncol): raise error else: format = fmt else: raise ValueError('invalid fmt: %r' % (fmt,)) if len(header) > 0: header = header.replace('\n', '\n' + comments) fh.write(comments + header + newline) if iscomplex_X: for row in X: row2 = [] for number in row: row2.append(number.real) row2.append(number.imag) s = format % tuple(row2) + newline fh.write(s.replace('+-', '-')) else: for row in X: try: v = format % tuple(row) + newline except TypeError as e: raise TypeError("Mismatch between array dtype ('%s') and " "format specifier ('%s')" % (str(X.dtype), format)) from e fh.write(v) if len(footer) > 0: footer = footer.replace('\n', '\n' + comments) fh.write(comments + footer + newline) finally: if own_fh: fh.close() @set_module('numpy') def fromregex(file, regexp, dtype, encoding=None): r""" Construct an array from a text file, using regular expression parsing. The returned array is always a structured array, and is constructed from all matches of the regular expression in the file. Groups in the regular expression are converted to fields of the structured array. Parameters ---------- file : path or file Filename or file object to read. .. versionchanged:: 1.22.0 Now accepts `os.PathLike` implementations. regexp : str or regexp Regular expression used to parse the file. Groups in the regular expression correspond to fields in the dtype. dtype : dtype or list of dtypes Dtype for the structured array; must be a structured datatype. encoding : str, optional Encoding used to decode the inputfile. Does not apply to input streams. .. versionadded:: 1.14.0 Returns ------- output : ndarray The output array, containing the part of the content of `file` that was matched by `regexp`. `output` is always a structured array. Raises ------ TypeError When `dtype` is not a valid dtype for a structured array. See Also -------- fromstring, loadtxt Notes ----- Dtypes for structured arrays can be specified in several forms, but all forms specify at least the data type and field name. For details see `basics.rec`. Examples -------- >>> from io import StringIO >>> text = StringIO("1312 foo\n1534 bar\n444 qux") >>> regexp = r"(\d+)\s+(...)" # match [digits, whitespace, anything] >>> output = np.fromregex(text, regexp, ... [('num', np.int64), ('key', 'S3')]) >>> output array([(1312, b'foo'), (1534, b'bar'), ( 444, b'qux')], dtype=[('num', '<i8'), ('key', 'S3')]) >>> output['num'] array([1312, 1534, 444]) """ own_fh = False if not hasattr(file, "read"): file = os.fspath(file) file = np.lib._datasource.open(file, 'rt', encoding=encoding) own_fh = True try: if not isinstance(dtype, np.dtype): dtype = np.dtype(dtype) if dtype.names is None: raise TypeError('dtype must be a structured datatype.') content = file.read() if isinstance(content, bytes) and isinstance(regexp, str): regexp = asbytes(regexp) elif isinstance(content, str) and isinstance(regexp, bytes): regexp = asstr(regexp) if not hasattr(regexp, 'match'): regexp = re.compile(regexp) seq = regexp.findall(content) if seq and not isinstance(seq[0], tuple): # Only one group is in the regexp. # Create the new array as a single data-type and then # re-interpret as a single-field structured array. newdtype = np.dtype(dtype[dtype.names[0]]) output = np.array(seq, dtype=newdtype) output.dtype = dtype else: output = np.array(seq, dtype=dtype) return output finally: if own_fh: file.close() #####-------------------------------------------------------------------------- #---- --- ASCII functions --- #####-------------------------------------------------------------------------- @set_array_function_like_doc @set_module('numpy') def genfromtxt(fname, dtype=float, comments='#', delimiter=None, skip_header=0, skip_footer=0, converters=None, missing_values=None, filling_values=None, usecols=None, names=None, excludelist=None, deletechars=''.join(sorted(NameValidator.defaultdeletechars)), replace_space='_', autostrip=False, case_sensitive=True, defaultfmt="f%i", unpack=None, usemask=False, loose=True, invalid_raise=True, max_rows=None, encoding='bytes', , ndmin=0, like=None): """ Load data from a text file, with missing values handled as specified. Each line past the first `skip_header` lines is split at the `delimiter` character, and characters following the `comments` character are discarded. Parameters ---------- fname : file, str, pathlib.Path, list of str, generator File, filename, list, or generator to read. If the filename extension is ``.gz`` or ``.bz2``, the file is first decompressed. Note that generators must return bytes or strings. The strings in a list or produced by a generator are treated as lines. dtype : dtype, optional Data type of the resulting array. If None, the dtypes will be determined by the contents of each column, individually. comments : str, optional The character used to indicate the start of a comment. All the characters occurring on a line after a comment are discarded. delimiter : str, int, or sequence, optional The string used to separate values. By default, any consecutive whitespaces act as delimiter. An integer or sequence of integers can also be provided as width(s) of each field. skiprows : int, optional `skiprows` was removed in numpy 1.10. Please use `skip_header` instead. skip_header : int, optional The number of lines to skip at the beginning of the file. skip_footer : int, optional The number of lines to skip at the end of the file. converters : variable, optional The set of functions that convert the data of a column to a value. The converters can also be used to provide a default value for missing data: ``converters = {3: lambda s: float(s or 0)}``. missing : variable, optional `missing` was removed in numpy 1.10. Please use `missing_values` instead. missing_values : variable, optional The set of strings corresponding to missing data. filling_values : variable, optional The set of values to be used as default when the data are missing. usecols : sequence, optional Which columns to read, with 0 being the first. For example, ``usecols = (1, 4, 5)`` will extract the 2nd, 5th and 6th columns. names : {None, True, str, sequence}, optional If `names` is True, the field names are read from the first line after the first `skip_header` lines. This line can optionally be preceded by a comment delimiter. If `names` is a sequence or a single-string of comma-separated names, the names will be used to define the field names in a structured dtype. If `names` is None, the names of the dtype fields will be used, if any. excludelist : sequence, optional A list of names to exclude. This list is appended to the default list ['return','file','print']. Excluded names are appended with an underscore: for example, `file` would become `file_`. deletechars : str, optional A string combining invalid characters that must be deleted from the names. defaultfmt : str, optional A format used to define default field names, such as "f%i" or "f_%02i". autostrip : bool, optional Whether to automatically strip white spaces from the variables. replace_space : char, optional Character(s) used in replacement of white spaces in the variable names. By default, use a '_'. case_sensitive : {True, False, 'upper', 'lower'}, optional If True, field names are case sensitive. If False or 'upper', field names are converted to upper case. If 'lower', field names are converted to lower case. unpack : bool, optional If True, the returned array is transposed, so that arguments may be unpacked using ``x, y, z = genfromtxt(...)``. When used with a structured data-type, arrays are returned for each field. Default is False. usemask : bool, optional If True, return a masked array. If False, return a regular array. loose : bool, optional If True, do not raise errors for invalid values. invalid_raise : bool, optional If True, an exception is raised if an inconsistency is detected in the number of columns. If False, a warning is emitted and the offending lines are skipped. max_rows : int, optional The maximum number of rows to read. Must not be used with skip_footer at the same time. If given, the value must be at least 1. Default is to read the entire file. .. versionadded:: 1.10.0 encoding : str, optional Encoding used to decode the inputfile. Does not apply when `fname` is a file object. The special value 'bytes' enables backward compatibility workarounds that ensure that you receive byte arrays when possible and passes latin1 encoded strings to converters. Override this value to receive unicode arrays and pass strings as input to converters. If set to None the system default is used. The default value is 'bytes'. .. versionadded:: 1.14.0 ndmin : int, optional Same parameter as `loadtxt` .. versionadded:: 1.23.0 ${ARRAY_FUNCTION_LIKE} .. versionadded:: 1.20.0 Returns ------- out : ndarray Data read from the text file. If `usemask` is True, this is a masked array. See Also -------- numpy.loadtxt : equivalent function when no data is missing. Notes ----- When spaces are used as delimiters, or when no delimiter has been given as input, there should not be any missing data between two fields. * When the variables are named (either by a flexible dtype or with `names`), there must not be any header in the file (else a ValueError exception is raised). * Individual values are not stripped of spaces by default. When using a custom converter, make sure the function does remove spaces. References ---------- .. [1] NumPy User Guide, section `I/O with NumPy <https://docs.scipy.org/doc/numpy/user/basics.io.genfromtxt.html>`_. Examples -------- >>> from io import StringIO >>> import numpy as np Comma delimited file with mixed dtype >>> s = StringIO(u"1,1.3,abcde") >>> data = np.genfromtxt(s, dtype=[('myint','i8'),('myfloat','f8'), ... ('mystring','S5')], delimiter=",") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', 'S5')]) Using dtype = None >>> _ = s.seek(0) # needed for StringIO example only >>> data = np.genfromtxt(s, dtype=None, ... names = ['myint','myfloat','mystring'], delimiter=",") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', 'S5')]) Specifying dtype and names >>> _ = s.seek(0) >>> data = np.genfromtxt(s, dtype="i8,f8,S5", ... names=['myint','myfloat','mystring'], delimiter=",") >>> data array((1, 1.3, b'abcde'), dtype=[('myint', '<i8'), ('myfloat', '<f8'), ('mystring', 'S5')]) An example with fixed-width columns >>> s = StringIO(u"11.3abcde") >>> data = np.genfromtxt(s, dtype=None, names=['intvar','fltvar','strvar'], ... delimiter=[1,3,5]) >>> data array((1, 1.3, b'abcde'), dtype=[('intvar', '<i8'), ('fltvar', '<f8'), ('strvar', 'S5')]) An example to show comments >>> f = StringIO(''' ... text,# of chars ... hello world,11 ... numpy,5''') >>> np.genfromtxt(f, dtype='S12,S12', delimiter=',') array([(b'text', b''), (b'hello world', b'11'), (b'numpy', b'5')], dtype=[('f0', 'S12'), ('f1', 'S12')]) """ if like is not None: return _genfromtxt_with_like( like, fname, dtype=dtype, comments=comments, delimiter=delimiter, skip_header=skip_header, skip_footer=skip_footer, converters=converters, missing_values=missing_values, filling_values=filling_values, usecols=usecols, names=names, excludelist=excludelist, deletechars=deletechars, replace_space=replace_space, autostrip=autostrip, case_sensitive=case_sensitive, defaultfmt=defaultfmt, unpack=unpack, usemask=usemask, loose=loose, invalid_raise=invalid_raise, max_rows=max_rows, encoding=encoding, ndmin=ndmin, ) _ensure_ndmin_ndarray_check_param(ndmin) if max_rows is not None: if skip_footer: raise ValueError( "The keywords 'skip_footer' and 'max_rows' can not be " "specified at the same time.") if max_rows < 1: raise ValueError("'max_rows' must be at least 1.") if usemask: from numpy.ma import MaskedArray, make_mask_descr # Check the input dictionary of converters user_converters = converters or {} if not isinstance(user_converters, dict): raise TypeError( "The input argument 'converter' should be a valid dictionary " "(got '%s' instead)" % type(user_converters)) if encoding == 'bytes': encoding = None byte_converters = True else: byte_converters = False # Initialize the filehandle, the LineSplitter and the NameValidator if isinstance(fname, os_PathLike): fname = os_fspath(fname) if isinstance(fname, str): fid = np.lib._datasource.open(fname, 'rt', encoding=encoding) fid_ctx = contextlib.closing(fid) else: fid = fname fid_ctx = contextlib.nullcontext(fid) try: fhd = iter(fid) except TypeError as e: raise TypeError( "fname must be a string, a filehandle, a sequence of strings,\n" f"or an iterator of strings. Got {type(fname)} instead." ) from e with fid_ctx: split_line = LineSplitter(delimiter=delimiter, comments=comments, autostrip=autostrip, encoding=encoding) validate_names = NameValidator(excludelist=excludelist, deletechars=deletechars, case_sensitive=case_sensitive, replace_space=replace_space) # Skip the first `skip_header` rows try: for i in range(skip_header): next(fhd) # Keep on until we find the first valid values first_values = None while not first_values: first_line = _decode_line(next(fhd), encoding) if (names is True) and (comments is not None): if comments in first_line: first_line = ( ''.join(first_line.split(comments)[1:])) first_values = split_line(first_line) except StopIteration: # return an empty array if the datafile is empty first_line = '' first_values = [] warnings.warn('genfromtxt: Empty input file: "%s"' % fname, stacklevel=2) # Should we take the first values as names ? if names is True: fval = first_values[0].strip() if comments is not None: if fval in comments: del first_values[0] # Check the columns to use: make sure `usecols` is a list if usecols is not None: try: usecols = [_.strip() for _ in usecols.split(",")] except AttributeError: try: usecols = list(usecols) except TypeError: usecols = [usecols, ] nbcols = len(usecols or first_values) # Check the names and overwrite the dtype.names if needed if names is True: names = validate_names([str(_.strip()) for _ in first_values]) first_line = '' elif _is_string_like(names): names = validate_names([_.strip() for _ in names.split(',')]) elif names: names = validate_names(names) # Get the dtype if dtype is not None: dtype = easy_dtype(dtype, defaultfmt=defaultfmt, names=names, excludelist=excludelist, deletechars=deletechars, case_sensitive=case_sensitive, replace_space=replace_space) # Make sure the names is a list (for 2.5) if names is not None: names = list(names) if usecols: for (i, current) in enumerate(usecols): # if usecols is a list of names, convert to a list of indices if _is_string_like(current): usecols[i] = names.index(current) elif current < 0: usecols[i] = current + len(first_values) # If the dtype is not None, make sure we update it if (dtype is not None) and (len(dtype) > nbcols): descr = dtype.descr dtype = np.dtype([descr[_] for _ in usecols]) names = list(dtype.names) # If `names` is not None, update the names elif (names is not None) and (len(names) > nbcols): names = [names[_] for _ in usecols] elif (names is not None) and (dtype is not None): names = list(dtype.names) # Process the missing values ............................... # Rename missing_values for convenience user_missing_values = missing_values or () if isinstance(user_missing_values, bytes): user_missing_values = user_missing_values.decode('latin1') # Define the list of missing_values (one column: one list) missing_values = [list(['']) for _ in range(nbcols)] # We have a dictionary: process it field by field if isinstance(user_missing_values, dict): # Loop on the items for (key, val) in user_missing_values.items(): # Is the key a string ? if _is_string_like(key): try: # Transform it into an integer key = names.index(key) except ValueError: # We couldn't find it: the name must have been dropped continue # Redefine the key as needed if it's a column number if usecols: try: key = usecols.index(key) except ValueError: pass # Transform the value as a list of string if isinstance(val, (list, tuple)): val = [str(_) for _ in val] else: val = [str(val), ] # Add the value(s) to the current list of missing if key is None: # None acts as default for miss in missing_values: miss.extend(val) else: missing_values[key].extend(val) # We have a sequence : each item matches a column elif isinstance(user_missing_values, (list, tuple)): for (value, entry) in zip(user_missing_values, missing_values): value = str(value) if value not in entry: entry.append(value) # We have a string : apply it to all entries elif isinstance(user_missing_values, str): user_value = user_missing_values.split(",") for entry in missing_values: entry.extend(user_value) # We have something else: apply it to all entries else: for entry in missing_values: entry.extend([str(user_missing_values)]) # Process the filling_values ............................... # Rename the input for convenience user_filling_values = filling_values if user_filling_values is None: user_filling_values = [] # Define the default filling_values = [None] * nbcols # We have a dictionary : update each entry individually if isinstance(user_filling_values, dict): for (key, val) in user_filling_values.items(): if _is_string_like(key): try: # Transform it into an integer key = names.index(key) except ValueError: # We couldn't find it: the name must have been dropped, continue # Redefine the key if it's a column number and usecols is defined if usecols: try: key = usecols.index(key) except ValueError: pass # Add the value to the list filling_values[key] = val # We have a sequence : update on a one-to-one basis elif isinstance(user_filling_values, (list, tuple)): n = len(user_filling_values) if (n <= nbcols): filling_values[:n] = user_filling_values else: filling_values = user_filling_values[:nbcols] # We have something else : use it for all entries else: filling_values = [user_filling_values] * nbcols # Initialize the converters ................................ if dtype is None: # Note: we can't use a [...]nbcols, as we would have 3 times the same # ... converter, instead of 3 different converters. converters = [StringConverter(None, missing_values=miss, default=fill) for (miss, fill) in zip(missing_values, filling_values)] else: dtype_flat = flatten_dtype(dtype, flatten_base=True) # Initialize the converters if len(dtype_flat) > 1: # Flexible type : get a converter from each dtype zipit = zip(dtype_flat, missing_values, filling_values) converters = [StringConverter(dt, locked=True, missing_values=miss, default=fill) for (dt, miss, fill) in zipit] else: # Set to a default converter (but w/ different missing values) zipit = zip(missing_values, filling_values) converters = [StringConverter(dtype, locked=True, missing_values=miss, default=fill) for (miss, fill) in zipit] # Update the converters to use the user-defined ones uc_update = [] for (j, conv) in user_converters.items(): # If the converter is specified by column names, use the index instead if _is_string_like(j): try: j = names.index(j) i = j except ValueError: continue elif usecols: try: i = usecols.index(j) except ValueError: # Unused converter specified continue else: i = j # Find the value to test - first_line is not filtered by usecols: if len(first_line): testing_value = first_values[j] else: testing_value = None if conv is bytes: user_conv = asbytes elif byte_converters: # converters may use decode to workaround numpy's old behaviour, # so encode the string again before passing to the user converter def tobytes_first(x, conv): if type(x) is bytes: return conv(x) return conv(x.encode("latin1")) user_conv = functools.partial(tobytes_first, conv=conv) else: user_conv = conv converters[i].update(user_conv, locked=True, testing_value=testing_value, default=filling_values[i], missing_values=missing_values[i],) uc_update.append((i, user_conv)) # Make sure we have the corrected keys in user_converters... user_converters.update(uc_update) # Fixme: possible error as following variable never used. # miss_chars = [_.missing_values for _ in converters] # Initialize the output lists ... # ... rows rows = [] append_to_rows = rows.append # ... masks if usemask: masks = [] append_to_masks = masks.append # ... invalid invalid = [] append_to_invalid = invalid.append # Parse each line for (i, line) in enumerate(itertools.chain([first_line, ], fhd)): values = split_line(line) nbvalues = len(values) # Skip an empty line if nbvalues == 0: continue if usecols: # Select only the columns we need try: values = [values[_] for _ in usecols] except IndexError: append_to_invalid((i + skip_header + 1, nbvalues)) continue elif nbvalues != nbcols: append_to_invalid((i + skip_header + 1, nbvalues)) continue # Store the values append_to_rows(tuple(values)) if usemask: append_to_masks(tuple([v.strip() in m for (v, m) in zip(values, missing_values)])) if len(rows) == max_rows: break # Upgrade the converters (if needed) if dtype is None: for (i, converter) in enumerate(converters): current_column = [itemgetter(i)(_m) for _m in rows] try: converter.iterupgrade(current_column) except ConverterLockError: errmsg = "Converter #%i is locked and cannot be upgraded: " % i current_column = map(itemgetter(i), rows) for (j, value) in enumerate(current_column): try: converter.upgrade(value) except (ConverterError, ValueError): errmsg += "(occurred line #%i for value '%s')" errmsg %= (j + 1 + skip_header, value) raise ConverterError(errmsg) # Check that we don't have invalid values nbinvalid = len(invalid) if nbinvalid > 0: nbrows = len(rows) + nbinvalid - skip_footer # Construct the error message template = " Line #%%i (got %%i columns instead of %i)" % nbcols if skip_footer > 0: nbinvalid_skipped = len([_ for _ in invalid if _[0] > nbrows + skip_header]) invalid = invalid[:nbinvalid - nbinvalid_skipped] skip_footer -= nbinvalid_skipped # # nbrows -= skip_footer # errmsg = [template % (i, nb) # for (i, nb) in invalid if i < nbrows] # else: errmsg = [template % (i, nb) for (i, nb) in invalid] if len(errmsg): errmsg.insert(0, "Some errors were detected !") errmsg = "\n".join(errmsg) # Raise an exception ? if invalid_raise: raise ValueError(errmsg) # Issue a warning ? else: warnings.warn(errmsg, ConversionWarning, stacklevel=2) # Strip the last skip_footer data if skip_footer > 0: rows = rows[:-skip_footer] if usemask: masks = masks[:-skip_footer] # Convert each value according to the converter: # We want to modify the list in place to avoid creating a new one... if loose: rows = list( zip([[conv._loose_call(_r) for _r in map(itemgetter(i), rows)] for (i, conv) in enumerate(converters)])) else: rows = list( zip([[conv._strict_call(_r) for _r in map(itemgetter(i), rows)] for (i, conv) in enumerate(converters)])) # Reset the dtype data = rows if dtype is None: # Get the dtypes from the types of the converters column_types = [conv.type for conv in converters] # Find the columns with strings... strcolidx = [i for (i, v) in enumerate(column_types) if v == np.str_] if byte_converters and strcolidx: # convert strings back to bytes for backward compatibility warnings.warn( "Reading unicode strings without specifying the encoding " "argument is deprecated. Set the encoding, use None for the " "system default.", np.VisibleDeprecationWarning, stacklevel=2) def encode_unicode_cols(row_tup): row = list(row_tup) for i in strcolidx: row[i] = row[i].encode('latin1') return tuple(row) try: data = [encode_unicode_cols(r) for r in data] except UnicodeEncodeError: pass else: for i in strcolidx: column_types[i] = np.bytes_ # Update string types to be the right length sized_column_types = column_types[:] for i, col_type in enumerate(column_types): if np.issubdtype(col_type, np.character): n_chars = max(len(row[i]) for row in data) sized_column_types[i] = (col_type, n_chars) if names is None: # If the dtype is uniform (before sizing strings) base = { c_type for c, c_type in zip(converters, column_types) if c._checked} if len(base) == 1: uniform_type, = base (ddtype, mdtype) = (uniform_type, bool) else: ddtype = [(defaultfmt % i, dt) for (i, dt) in enumerate(sized_column_types)] if usemask: mdtype = [(defaultfmt % i, bool) for (i, dt) in enumerate(sized_column_types)] else: ddtype = list(zip(names, sized_column_types)) mdtype = list(zip(names, [bool] len(sized_column_types))) output = np.array(data, dtype=ddtype) if usemask: outputmask = np.array(masks, dtype=mdtype) else: # Overwrite the initial dtype names if needed if names and dtype.names is not None: dtype.names = names # Case 1. We have a structured type if len(dtype_flat) > 1: # Nested dtype, eg [('a', int), ('b', [('b0', int), ('b1', 'f4')])] # First, create the array using a flattened dtype: # [('a', int), ('b1', int), ('b2', float)] # Then, view the array using the specified dtype. if 'O' in (_.char for _ in dtype_flat): if has_nested_fields(dtype): raise NotImplementedError( "Nested fields involving objects are not supported...") else: output = np.array(data, dtype=dtype) else: rows = np.array(data, dtype=[('', _) for _ in dtype_flat]) output = rows.view(dtype) # Now, process the rowmasks the same way if usemask: rowmasks = np.array( masks, dtype=np.dtype([('', bool) for t in dtype_flat])) # Construct the new dtype mdtype = make_mask_descr(dtype) outputmask = rowmasks.view(mdtype) # Case #2. We have a basic dtype else: # We used some user-defined converters if user_converters: ishomogeneous = True descr = [] for i, ttype in enumerate([conv.type for conv in converters]): # Keep the dtype of the current converter if i in user_converters: ishomogeneous &= (ttype == dtype.type) if np.issubdtype(ttype, np.character): ttype = (ttype, max(len(row[i]) for row in data)) descr.append(('', ttype)) else: descr.append(('', dtype)) # So we changed the dtype ? if not ishomogeneous: # We have more than one field if len(descr) > 1: dtype = np.dtype(descr) # We have only one field: drop the name if not needed. else: dtype = np.dtype(ttype) # output = np.array(data, dtype) if usemask: if dtype.names is not None: mdtype = [(_, bool) for _ in dtype.names] else: mdtype = bool outputmask = np.array(masks, dtype=mdtype) # Try to take care of the missing data we missed names = output.dtype.names if usemask and names: for (name, conv) in zip(names, converters): missing_values = [conv(_) for _ in conv.missing_values if _ != ''] for mval in missing_values: outputmask[name] \|= (output[name] == mval) # Construct the final array if usemask: output = output.view(MaskedArray) output._mask = outputmask output = _ensure_ndmin_ndarray(output, ndmin=ndmin) if unpack: if names is None: return output.T elif len(names) == 1: # squeeze single-name dtypes too return output[names[0]] else: # For structured arrays with multiple fields, # return an array for each field. return [output[field] for field in names] return output _genfromtxt_with_like = array_function_dispatch()(genfromtxt) def recfromtxt(fname, kwargs): """ Load ASCII data from a file and return it in a record array. If ``usemask=False`` a standard `recarray` is returned, if ``usemask=True`` a MaskedRecords array is returned. Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function Notes ----- By default, `dtype` is None, which means that the data-type of the output array will be determined from the data. """ kwargs.setdefault("dtype", None) usemask = kwargs.get('usemask', False) output = genfromtxt(fname, kwargs) if usemask: from numpy.ma.mrecords import MaskedRecords output = output.view(MaskedRecords) else: output = output.view(np.recarray) return output def recfromcsv(fname, kwargs): """ Load ASCII data stored in a comma-separated file. The returned array is a record array (if ``usemask=False``, see `recarray`) or a masked record array (if ``usemask=True``, see `ma.mrecords.MaskedRecords`). Parameters ---------- fname, kwargs : For a description of input parameters, see `genfromtxt`. See Also -------- numpy.genfromtxt : generic function to load ASCII data. Notes ----- By default, `dtype` is None, which means that the data-type of the output array will be determined from the data. """ # Set default kwargs for genfromtxt as relevant to csv import. kwargs.setdefault("case_sensitive", "lower") kwargs.setdefault("names", True) kwargs.setdefault("delimiter", ",") kwargs.setdefault("dtype", None) output = genfromtxt(fname, kwargs) usemask = kwargs.get("usemask", False) if usemask: from numpy.ma.mrecords import MaskedRecords output = output.view(MaskedRecords) else: output = output.view(np.recarray) return output	95.04 KB	2026-01-20 12:58
📄 npyio.pyi import os import sys import zipfile import types from re import Pattern from collections.abc import Collection, Mapping, Iterator, Sequence, Callable, Iterable from typing import ( Literal as L, Any, TypeVar, Generic, IO, overload, Protocol, ) from numpy import ( DataSource as DataSource, ndarray, recarray, dtype, generic, float64, void, record, ) from numpy.ma.mrecords import MaskedRecords from numpy._typing import ( ArrayLike, DTypeLike, NDArray, _DTypeLike, _SupportsArrayFunc, ) from numpy.core.multiarray import ( packbits as packbits, unpackbits as unpackbits, ) _T = TypeVar("_T") _T_contra = TypeVar("_T_contra", contravariant=True) _T_co = TypeVar("_T_co", covariant=True) _SCT = TypeVar("_SCT", bound=generic) _CharType_co = TypeVar("_CharType_co", str, bytes, covariant=True) _CharType_contra = TypeVar("_CharType_contra", str, bytes, contravariant=True) class _SupportsGetItem(Protocol[_T_contra, _T_co]): def __getitem__(self, key: _T_contra, /) -> _T_co: ... class _SupportsRead(Protocol[_CharType_co]): def read(self) -> _CharType_co: ... class _SupportsReadSeek(Protocol[_CharType_co]): def read(self, n: int, /) -> _CharType_co: ... def seek(self, offset: int, whence: int, /) -> object: ... class _SupportsWrite(Protocol[_CharType_contra]): def write(self, s: _CharType_contra, /) -> object: ... __all__: list[str] class BagObj(Generic[_T_co]): def __init__(self, obj: _SupportsGetItem[str, _T_co]) -> None: ... def __getattribute__(self, key: str) -> _T_co: ... def __dir__(self) -> list[str]: ... class NpzFile(Mapping[str, NDArray[Any]]): zip: zipfile.ZipFile fid: None \| IO[str] files: list[str] allow_pickle: bool pickle_kwargs: None \| Mapping[str, Any] _MAX_REPR_ARRAY_COUNT: int # Represent `f` as a mutable property so we can access the type of `self` @property def f(self: _T) -> BagObj[_T]: ... @f.setter def f(self: _T, value: BagObj[_T]) -> None: ... def __init__( self, fid: IO[str], own_fid: bool = ..., allow_pickle: bool = ..., pickle_kwargs: None \| Mapping[str, Any] = ..., ) -> None: ... def __enter__(self: _T) -> _T: ... def __exit__( self, exc_type: None \| type[BaseException], exc_value: None \| BaseException, traceback: None \| types.TracebackType, /, ) -> None: ... def close(self) -> None: ... def __del__(self) -> None: ... def __iter__(self) -> Iterator[str]: ... def __len__(self) -> int: ... def __getitem__(self, key: str) -> NDArray[Any]: ... def __contains__(self, key: str) -> bool: ... def __repr__(self) -> str: ... # NOTE: Returns a `NpzFile` if file is a zip file; # returns an `ndarray`/`memmap` otherwise def load( file: str \| bytes \| os.PathLike[Any] \| _SupportsReadSeek[bytes], mmap_mode: L[None, "r+", "r", "w+", "c"] = ..., allow_pickle: bool = ..., fix_imports: bool = ..., encoding: L["ASCII", "latin1", "bytes"] = ..., ) -> Any: ... def save( file: str \| os.PathLike[str] \| _SupportsWrite[bytes], arr: ArrayLike, allow_pickle: bool = ..., fix_imports: bool = ..., ) -> None: ... def savez( file: str \| os.PathLike[str] \| _SupportsWrite[bytes], args: ArrayLike, kwds: ArrayLike, ) -> None: ... def savez_compressed( file: str \| os.PathLike[str] \| _SupportsWrite[bytes], args: ArrayLike, *kwds: ArrayLike, ) -> None: ... # File-like objects only have to implement `__iter__` and, # optionally, `encoding` @overload def loadtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: None = ..., comments: None \| str \| Sequence[str] = ..., delimiter: None \| str = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., skiprows: int = ..., usecols: int \| Sequence[int] = ..., unpack: bool = ..., ndmin: L[0, 1, 2] = ..., encoding: None \| str = ..., max_rows: None \| int = ..., , quotechar: None \| str = ..., like: None \| _SupportsArrayFunc = ... ) -> NDArray[float64]: ... @overload def loadtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: _DTypeLike[_SCT], comments: None \| str \| Sequence[str] = ..., delimiter: None \| str = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., skiprows: int = ..., usecols: int \| Sequence[int] = ..., unpack: bool = ..., ndmin: L[0, 1, 2] = ..., encoding: None \| str = ..., max_rows: None \| int = ..., , quotechar: None \| str = ..., like: None \| _SupportsArrayFunc = ... ) -> NDArray[_SCT]: ... @overload def loadtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: DTypeLike, comments: None \| str \| Sequence[str] = ..., delimiter: None \| str = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., skiprows: int = ..., usecols: int \| Sequence[int] = ..., unpack: bool = ..., ndmin: L[0, 1, 2] = ..., encoding: None \| str = ..., max_rows: None \| int = ..., , quotechar: None \| str = ..., like: None \| _SupportsArrayFunc = ... ) -> NDArray[Any]: ... def savetxt( fname: str \| os.PathLike[str] \| _SupportsWrite[str] \| _SupportsWrite[bytes], X: ArrayLike, fmt: str \| Sequence[str] = ..., delimiter: str = ..., newline: str = ..., header: str = ..., footer: str = ..., comments: str = ..., encoding: None \| str = ..., ) -> None: ... @overload def fromregex( file: str \| os.PathLike[str] \| _SupportsRead[str] \| _SupportsRead[bytes], regexp: str \| bytes \| Pattern[Any], dtype: _DTypeLike[_SCT], encoding: None \| str = ... ) -> NDArray[_SCT]: ... @overload def fromregex( file: str \| os.PathLike[str] \| _SupportsRead[str] \| _SupportsRead[bytes], regexp: str \| bytes \| Pattern[Any], dtype: DTypeLike, encoding: None \| str = ... ) -> NDArray[Any]: ... @overload def genfromtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: None = ..., comments: str = ..., delimiter: None \| str \| int \| Iterable[int] = ..., skip_header: int = ..., skip_footer: int = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., missing_values: Any = ..., filling_values: Any = ..., usecols: None \| Sequence[int] = ..., names: L[None, True] \| str \| Collection[str] = ..., excludelist: None \| Sequence[str] = ..., deletechars: str = ..., replace_space: str = ..., autostrip: bool = ..., case_sensitive: bool \| L['upper', 'lower'] = ..., defaultfmt: str = ..., unpack: None \| bool = ..., usemask: bool = ..., loose: bool = ..., invalid_raise: bool = ..., max_rows: None \| int = ..., encoding: str = ..., , ndmin: L[0, 1, 2] = ..., like: None \| _SupportsArrayFunc = ..., ) -> NDArray[Any]: ... @overload def genfromtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: _DTypeLike[_SCT], comments: str = ..., delimiter: None \| str \| int \| Iterable[int] = ..., skip_header: int = ..., skip_footer: int = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., missing_values: Any = ..., filling_values: Any = ..., usecols: None \| Sequence[int] = ..., names: L[None, True] \| str \| Collection[str] = ..., excludelist: None \| Sequence[str] = ..., deletechars: str = ..., replace_space: str = ..., autostrip: bool = ..., case_sensitive: bool \| L['upper', 'lower'] = ..., defaultfmt: str = ..., unpack: None \| bool = ..., usemask: bool = ..., loose: bool = ..., invalid_raise: bool = ..., max_rows: None \| int = ..., encoding: str = ..., , ndmin: L[0, 1, 2] = ..., like: None \| _SupportsArrayFunc = ..., ) -> NDArray[_SCT]: ... @overload def genfromtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], dtype: DTypeLike, comments: str = ..., delimiter: None \| str \| int \| Iterable[int] = ..., skip_header: int = ..., skip_footer: int = ..., converters: None \| Mapping[int \| str, Callable[[str], Any]] = ..., missing_values: Any = ..., filling_values: Any = ..., usecols: None \| Sequence[int] = ..., names: L[None, True] \| str \| Collection[str] = ..., excludelist: None \| Sequence[str] = ..., deletechars: str = ..., replace_space: str = ..., autostrip: bool = ..., case_sensitive: bool \| L['upper', 'lower'] = ..., defaultfmt: str = ..., unpack: None \| bool = ..., usemask: bool = ..., loose: bool = ..., invalid_raise: bool = ..., max_rows: None \| int = ..., encoding: str = ..., , ndmin: L[0, 1, 2] = ..., like: None \| _SupportsArrayFunc = ..., ) -> NDArray[Any]: ... @overload def recfromtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], , usemask: L[False] = ..., *kwargs: Any, ) -> recarray[Any, dtype[record]]: ... @overload def recfromtxt( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], , usemask: L[True], *kwargs: Any, ) -> MaskedRecords[Any, dtype[void]]: ... @overload def recfromcsv( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], , usemask: L[False] = ..., *kwargs: Any, ) -> recarray[Any, dtype[record]]: ... @overload def recfromcsv( fname: str \| os.PathLike[str] \| Iterable[str] \| Iterable[bytes], , usemask: L[True], **kwargs: Any, ) -> MaskedRecords[Any, dtype[void]]: ...	9.5 KB	2026-01-20 12:58
📄 polynomial.py """ Functions to operate on polynomials. """ __all__ = ['poly', 'roots', 'polyint', 'polyder', 'polyadd', 'polysub', 'polymul', 'polydiv', 'polyval', 'poly1d', 'polyfit', 'RankWarning'] import functools import re import warnings from .._utils import set_module import numpy.core.numeric as NX from numpy.core import (isscalar, abs, finfo, atleast_1d, hstack, dot, array, ones) from numpy.core import overrides from numpy.lib.twodim_base import diag, vander from numpy.lib.function_base import trim_zeros from numpy.lib.type_check import iscomplex, real, imag, mintypecode from numpy.linalg import eigvals, lstsq, inv array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') @set_module('numpy') class RankWarning(UserWarning): """ Issued by `polyfit` when the Vandermonde matrix is rank deficient. For more information, a way to suppress the warning, and an example of `RankWarning` being issued, see `polyfit`. """ pass def _poly_dispatcher(seq_of_zeros): return seq_of_zeros @array_function_dispatch(_poly_dispatcher) def poly(seq_of_zeros): """ Find the coefficients of a polynomial with the given sequence of roots. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Returns the coefficients of the polynomial whose leading coefficient is one for the given sequence of zeros (multiple roots must be included in the sequence as many times as their multiplicity; see Examples). A square matrix (or array, which will be treated as a matrix) can also be given, in which case the coefficients of the characteristic polynomial of the matrix are returned. Parameters ---------- seq_of_zeros : array_like, shape (N,) or (N, N) A sequence of polynomial roots, or a square array or matrix object. Returns ------- c : ndarray 1D array of polynomial coefficients from highest to lowest degree: ``c[0] * x*(N) + c[1] x*(N-1) + ... + c[N-1] x + c[N]`` where c[0] always equals 1. Raises ------ ValueError If input is the wrong shape (the input must be a 1-D or square 2-D array). See Also -------- polyval : Compute polynomial values. roots : Return the roots of a polynomial. polyfit : Least squares polynomial fit. poly1d : A one-dimensional polynomial class. Notes ----- Specifying the roots of a polynomial still leaves one degree of freedom, typically represented by an undetermined leading coefficient. [1]_ In the case of this function, that coefficient - the first one in the returned array - is always taken as one. (If for some reason you have one other point, the only automatic way presently to leverage that information is to use ``polyfit``.) The characteristic polynomial, :math:`p_a(t)`, of an `n`-by-`n` matrix A is given by :math:`p_a(t) = \\mathrm{det}(t\\, \\mathbf{I} - \\mathbf{A})`, where I is the `n`-by-`n` identity matrix. [2]_ References ---------- .. [1] M. Sullivan and M. Sullivan, III, "Algebra and Trigonometry, Enhanced With Graphing Utilities," Prentice-Hall, pg. 318, 1996. .. [2] G. Strang, "Linear Algebra and Its Applications, 2nd Edition," Academic Press, pg. 182, 1980. Examples -------- Given a sequence of a polynomial's zeros: >>> np.poly((0, 0, 0)) # Multiple root example array([1., 0., 0., 0.]) The line above represents z*3 + 0z*2 + 0z + 0. >>> np.poly((-1./2, 0, 1./2)) array([ 1. , 0. , -0.25, 0. ]) The line above represents z*3 - z/4 >>> np.poly((np.random.random(1)[0], 0, np.random.random(1)[0])) array([ 1. , -0.77086955, 0.08618131, 0. ]) # random Given a square array object: >>> P = np.array([[0, 1./3], [-1./2, 0]]) >>> np.poly(P) array([1. , 0. , 0.16666667]) Note how in all cases the leading coefficient is always 1. """ seq_of_zeros = atleast_1d(seq_of_zeros) sh = seq_of_zeros.shape if len(sh) == 2 and sh[0] == sh[1] and sh[0] != 0: seq_of_zeros = eigvals(seq_of_zeros) elif len(sh) == 1: dt = seq_of_zeros.dtype # Let object arrays slip through, e.g. for arbitrary precision if dt != object: seq_of_zeros = seq_of_zeros.astype(mintypecode(dt.char)) else: raise ValueError("input must be 1d or non-empty square 2d array.") if len(seq_of_zeros) == 0: return 1.0 dt = seq_of_zeros.dtype a = ones((1,), dtype=dt) for zero in seq_of_zeros: a = NX.convolve(a, array([1, -zero], dtype=dt), mode='full') if issubclass(a.dtype.type, NX.complexfloating): # if complex roots are all complex conjugates, the roots are real. roots = NX.asarray(seq_of_zeros, complex) if NX.all(NX.sort(roots) == NX.sort(roots.conjugate())): a = a.real.copy() return a def _roots_dispatcher(p): return p @array_function_dispatch(_roots_dispatcher) def roots(p): """ Return the roots of a polynomial with coefficients given in p. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. The values in the rank-1 array `p` are coefficients of a polynomial. If the length of `p` is n+1 then the polynomial is described by:: p[0] x*n + p[1] x*(n-1) + ... + p[n-1]x + p[n] Parameters ---------- p : array_like Rank-1 array of polynomial coefficients. Returns ------- out : ndarray An array containing the roots of the polynomial. Raises ------ ValueError When `p` cannot be converted to a rank-1 array. See also -------- poly : Find the coefficients of a polynomial with a given sequence of roots. polyval : Compute polynomial values. polyfit : Least squares polynomial fit. poly1d : A one-dimensional polynomial class. Notes ----- The algorithm relies on computing the eigenvalues of the companion matrix [1]_. References ---------- .. [1] R. A. Horn & C. R. Johnson, Matrix Analysis. Cambridge, UK: Cambridge University Press, 1999, pp. 146-7. Examples -------- >>> coeff = [3.2, 2, 1] >>> np.roots(coeff) array([-0.3125+0.46351241j, -0.3125-0.46351241j]) """ # If input is scalar, this makes it an array p = atleast_1d(p) if p.ndim != 1: raise ValueError("Input must be a rank-1 array.") # find non-zero array entries non_zero = NX.nonzero(NX.ravel(p))[0] # Return an empty array if polynomial is all zeros if len(non_zero) == 0: return NX.array([]) # find the number of trailing zeros -- this is the number of roots at 0. trailing_zeros = len(p) - non_zero[-1] - 1 # strip leading and trailing zeros p = p[int(non_zero[0]):int(non_zero[-1])+1] # casting: if incoming array isn't floating point, make it floating point. if not issubclass(p.dtype.type, (NX.floating, NX.complexfloating)): p = p.astype(float) N = len(p) if N > 1: # build companion matrix and find its eigenvalues (the roots) A = diag(NX.ones((N-2,), p.dtype), -1) A[0,:] = -p[1:] / p[0] roots = eigvals(A) else: roots = NX.array([]) # tack any zeros onto the back of the array roots = hstack((roots, NX.zeros(trailing_zeros, roots.dtype))) return roots def _polyint_dispatcher(p, m=None, k=None): return (p,) @array_function_dispatch(_polyint_dispatcher) def polyint(p, m=1, k=None): """ Return an antiderivative (indefinite integral) of a polynomial. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. The returned order `m` antiderivative `P` of polynomial `p` satisfies :math:`\\frac{d^m}{dx^m}P(x) = p(x)` and is defined up to `m - 1` integration constants `k`. The constants determine the low-order polynomial part .. math:: \\frac{k_{m-1}}{0!} x^0 + \\ldots + \\frac{k_0}{(m-1)!}x^{m-1} of `P` so that :math:`P^{(j)}(0) = k_{m-j-1}`. Parameters ---------- p : array_like or poly1d Polynomial to integrate. A sequence is interpreted as polynomial coefficients, see `poly1d`. m : int, optional Order of the antiderivative. (Default: 1) k : list of `m` scalars or scalar, optional Integration constants. They are given in the order of integration: those corresponding to highest-order terms come first. If ``None`` (default), all constants are assumed to be zero. If `m = 1`, a single scalar can be given instead of a list. See Also -------- polyder : derivative of a polynomial poly1d.integ : equivalent method Examples -------- The defining property of the antiderivative: >>> p = np.poly1d([1,1,1]) >>> P = np.polyint(p) >>> P poly1d([ 0.33333333, 0.5 , 1. , 0. ]) # may vary >>> np.polyder(P) == p True The integration constants default to zero, but can be specified: >>> P = np.polyint(p, 3) >>> P(0) 0.0 >>> np.polyder(P)(0) 0.0 >>> np.polyder(P, 2)(0) 0.0 >>> P = np.polyint(p, 3, k=[6,5,3]) >>> P poly1d([ 0.01666667, 0.04166667, 0.16666667, 3. , 5. , 3. ]) # may vary Note that 3 = 6 / 2!, and that the constants are given in the order of integrations. Constant of the highest-order polynomial term comes first: >>> np.polyder(P, 2)(0) 6.0 >>> np.polyder(P, 1)(0) 5.0 >>> P(0) 3.0 """ m = int(m) if m < 0: raise ValueError("Order of integral must be positive (see polyder)") if k is None: k = NX.zeros(m, float) k = atleast_1d(k) if len(k) == 1 and m > 1: k = k[0]NX.ones(m, float) if len(k) < m: raise ValueError( "k must be a scalar or a rank-1 array of length 1 or >m.") truepoly = isinstance(p, poly1d) p = NX.asarray(p) if m == 0: if truepoly: return poly1d(p) return p else: # Note: this must work also with object and integer arrays y = NX.concatenate((p.__truediv__(NX.arange(len(p), 0, -1)), [k[0]])) val = polyint(y, m - 1, k=k[1:]) if truepoly: return poly1d(val) return val def _polyder_dispatcher(p, m=None): return (p,) @array_function_dispatch(_polyder_dispatcher) def polyder(p, m=1): """ Return the derivative of the specified order of a polynomial. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Parameters ---------- p : poly1d or sequence Polynomial to differentiate. A sequence is interpreted as polynomial coefficients, see `poly1d`. m : int, optional Order of differentiation (default: 1) Returns ------- der : poly1d A new polynomial representing the derivative. See Also -------- polyint : Anti-derivative of a polynomial. poly1d : Class for one-dimensional polynomials. Examples -------- The derivative of the polynomial :math:`x^3 + x^2 + x^1 + 1` is: >>> p = np.poly1d([1,1,1,1]) >>> p2 = np.polyder(p) >>> p2 poly1d([3, 2, 1]) which evaluates to: >>> p2(2.) 17.0 We can verify this, approximating the derivative with ``(f(x + h) - f(x))/h``: >>> (p(2. + 0.001) - p(2.)) / 0.001 17.007000999997857 The fourth-order derivative of a 3rd-order polynomial is zero: >>> np.polyder(p, 2) poly1d([6, 2]) >>> np.polyder(p, 3) poly1d([6]) >>> np.polyder(p, 4) poly1d([0]) """ m = int(m) if m < 0: raise ValueError("Order of derivative must be positive (see polyint)") truepoly = isinstance(p, poly1d) p = NX.asarray(p) n = len(p) - 1 y = p[:-1] NX.arange(n, 0, -1) if m == 0: val = p else: val = polyder(y, m - 1) if truepoly: val = poly1d(val) return val def _polyfit_dispatcher(x, y, deg, rcond=None, full=None, w=None, cov=None): return (x, y, w) @array_function_dispatch(_polyfit_dispatcher) def polyfit(x, y, deg, rcond=None, full=False, w=None, cov=False): """ Least squares polynomial fit. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Fit a polynomial ``p(x) = p[0] * x*deg + ... + p[deg]`` of degree `deg` to points `(x, y)`. Returns a vector of coefficients `p` that minimises the squared error in the order `deg`, `deg-1`, ... `0`. The `Polynomial.fit <numpy.polynomial.polynomial.Polynomial.fit>` class method is recommended for new code as it is more stable numerically. See the documentation of the method for more information. Parameters ---------- x : array_like, shape (M,) x-coordinates of the M sample points ``(x[i], y[i])``. y : array_like, shape (M,) or (M, K) y-coordinates of the sample points. Several data sets of sample points sharing the same x-coordinates can be fitted at once by passing in a 2D-array that contains one dataset per column. deg : int Degree of the fitting polynomial rcond : float, optional Relative condition number of the fit. Singular values smaller than this relative to the largest singular value will be ignored. The default value is len(x)eps, where eps is the relative precision of the float type, about 2e-16 in most cases. full : bool, optional Switch determining nature of return value. When it is False (the default) just the coefficients are returned, when True diagnostic information from the singular value decomposition is also returned. w : array_like, shape (M,), optional Weights. If not None, the weight ``w[i]`` applies to the unsquared residual ``y[i] - y_hat[i]`` at ``x[i]``. Ideally the weights are chosen so that the errors of the products ``w[i]y[i]`` all have the same variance. When using inverse-variance weighting, use ``w[i] = 1/sigma(y[i])``. The default value is None. cov : bool or str, optional If given and not `False`, return not just the estimate but also its covariance matrix. By default, the covariance are scaled by chi2/dof, where dof = M - (deg + 1), i.e., the weights are presumed to be unreliable except in a relative sense and everything is scaled such that the reduced chi2 is unity. This scaling is omitted if ``cov='unscaled'``, as is relevant for the case that the weights are w = 1/sigma, with sigma known to be a reliable estimate of the uncertainty. Returns ------- p : ndarray, shape (deg + 1,) or (deg + 1, K) Polynomial coefficients, highest power first. If `y` was 2-D, the coefficients for `k`-th data set are in ``p[:,k]``. residuals, rank, singular_values, rcond These values are only returned if ``full == True`` - residuals -- sum of squared residuals of the least squares fit - rank -- the effective rank of the scaled Vandermonde coefficient matrix - singular_values -- singular values of the scaled Vandermonde coefficient matrix - rcond -- value of `rcond`. For more details, see `numpy.linalg.lstsq`. V : ndarray, shape (M,M) or (M,M,K) Present only if ``full == False`` and ``cov == True``. The covariance matrix of the polynomial coefficient estimates. The diagonal of this matrix are the variance estimates for each coefficient. If y is a 2-D array, then the covariance matrix for the `k`-th data set are in ``V[:,:,k]`` Warns ----- RankWarning The rank of the coefficient matrix in the least-squares fit is deficient. The warning is only raised if ``full == False``. The warnings can be turned off by >>> import warnings >>> warnings.simplefilter('ignore', np.RankWarning) See Also -------- polyval : Compute polynomial values. linalg.lstsq : Computes a least-squares fit. scipy.interpolate.UnivariateSpline : Computes spline fits. Notes ----- The solution minimizes the squared error .. math:: E = \\sum_{j=0}^k \|p(x_j) - y_j\|^2 in the equations:: x[0]n p[0] + ... + x[0] * p[n-1] + p[n] = y[0] x[1]*n p[0] + ... + x[1] * p[n-1] + p[n] = y[1] ... x[k]*n p[0] + ... + x[k] * p[n-1] + p[n] = y[k] The coefficient matrix of the coefficients `p` is a Vandermonde matrix. `polyfit` issues a `RankWarning` when the least-squares fit is badly conditioned. This implies that the best fit is not well-defined due to numerical error. The results may be improved by lowering the polynomial degree or by replacing `x` by `x` - `x`.mean(). The `rcond` parameter can also be set to a value smaller than its default, but the resulting fit may be spurious: including contributions from the small singular values can add numerical noise to the result. Note that fitting polynomial coefficients is inherently badly conditioned when the degree of the polynomial is large or the interval of sample points is badly centered. The quality of the fit should always be checked in these cases. When polynomial fits are not satisfactory, splines may be a good alternative. References ---------- .. [1] Wikipedia, "Curve fitting", https://en.wikipedia.org/wiki/Curve_fitting .. [2] Wikipedia, "Polynomial interpolation", https://en.wikipedia.org/wiki/Polynomial_interpolation Examples -------- >>> import warnings >>> x = np.array([0.0, 1.0, 2.0, 3.0, 4.0, 5.0]) >>> y = np.array([0.0, 0.8, 0.9, 0.1, -0.8, -1.0]) >>> z = np.polyfit(x, y, 3) >>> z array([ 0.08703704, -0.81349206, 1.69312169, -0.03968254]) # may vary It is convenient to use `poly1d` objects for dealing with polynomials: >>> p = np.poly1d(z) >>> p(0.5) 0.6143849206349179 # may vary >>> p(3.5) -0.34732142857143039 # may vary >>> p(10) 22.579365079365115 # may vary High-order polynomials may oscillate wildly: >>> with warnings.catch_warnings(): ... warnings.simplefilter('ignore', np.RankWarning) ... p30 = np.poly1d(np.polyfit(x, y, 30)) ... >>> p30(4) -0.80000000000000204 # may vary >>> p30(5) -0.99999999999999445 # may vary >>> p30(4.5) -0.10547061179440398 # may vary Illustration: >>> import matplotlib.pyplot as plt >>> xp = np.linspace(-2, 6, 100) >>> _ = plt.plot(x, y, '.', xp, p(xp), '-', xp, p30(xp), '--') >>> plt.ylim(-2,2) (-2, 2) >>> plt.show() """ order = int(deg) + 1 x = NX.asarray(x) + 0.0 y = NX.asarray(y) + 0.0 # check arguments. if deg < 0: raise ValueError("expected deg >= 0") if x.ndim != 1: raise TypeError("expected 1D vector for x") if x.size == 0: raise TypeError("expected non-empty vector for x") if y.ndim < 1 or y.ndim > 2: raise TypeError("expected 1D or 2D array for y") if x.shape[0] != y.shape[0]: raise TypeError("expected x and y to have same length") # set rcond if rcond is None: rcond = len(x)finfo(x.dtype).eps # set up least squares equation for powers of x lhs = vander(x, order) rhs = y # apply weighting if w is not None: w = NX.asarray(w) + 0.0 if w.ndim != 1: raise TypeError("expected a 1-d array for weights") if w.shape[0] != y.shape[0]: raise TypeError("expected w and y to have the same length") lhs = w[:, NX.newaxis] if rhs.ndim == 2: rhs = w[:, NX.newaxis] else: rhs = w # scale lhs to improve condition number and solve scale = NX.sqrt((lhslhs).sum(axis=0)) lhs /= scale c, resids, rank, s = lstsq(lhs, rhs, rcond) c = (c.T/scale).T # broadcast scale coefficients # warn on rank reduction, which indicates an ill conditioned matrix if rank != order and not full: msg = "Polyfit may be poorly conditioned" warnings.warn(msg, RankWarning, stacklevel=2) if full: return c, resids, rank, s, rcond elif cov: Vbase = inv(dot(lhs.T, lhs)) Vbase /= NX.outer(scale, scale) if cov == "unscaled": fac = 1 else: if len(x) <= order: raise ValueError("the number of data points must exceed order " "to scale the covariance matrix") # note, this used to be: fac = resids / (len(x) - order - 2.0) # it was deciced that the "- 2" (originally justified by "Bayesian # uncertainty analysis") is not what the user expects # (see gh-11196 and gh-11197) fac = resids / (len(x) - order) if y.ndim == 1: return c, Vbase fac else: return c, Vbase[:,:, NX.newaxis] * fac else: return c def _polyval_dispatcher(p, x): return (p, x) @array_function_dispatch(_polyval_dispatcher) def polyval(p, x): """ Evaluate a polynomial at specific values. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. If `p` is of length N, this function returns the value: ``p[0]x(N-1) + p[1]x*(N-2) + ... + p[N-2]x + p[N-1]`` If `x` is a sequence, then ``p(x)`` is returned for each element of ``x``. If `x` is another polynomial then the composite polynomial ``p(x(t))`` is returned. Parameters ---------- p : array_like or poly1d object 1D array of polynomial coefficients (including coefficients equal to zero) from highest degree to the constant term, or an instance of poly1d. x : array_like or poly1d object A number, an array of numbers, or an instance of poly1d, at which to evaluate `p`. Returns ------- values : ndarray or poly1d If `x` is a poly1d instance, the result is the composition of the two polynomials, i.e., `x` is "substituted" in `p` and the simplified result is returned. In addition, the type of `x` - array_like or poly1d - governs the type of the output: `x` array_like => `values` array_like, `x` a poly1d object => `values` is also. See Also -------- poly1d: A polynomial class. Notes ----- Horner's scheme [1]_ is used to evaluate the polynomial. Even so, for polynomials of high degree the values may be inaccurate due to rounding errors. Use carefully. If `x` is a subtype of `ndarray` the return value will be of the same type. References ---------- .. [1] I. N. Bronshtein, K. A. Semendyayev, and K. A. Hirsch (Eng. trans. Ed.), Handbook of Mathematics, New York, Van Nostrand Reinhold Co., 1985, pg. 720. Examples -------- >>> np.polyval([3,0,1], 5) # 3 * 5*2 + 0 5*1 + 1 76 >>> np.polyval([3,0,1], np.poly1d(5)) poly1d([76]) >>> np.polyval(np.poly1d([3,0,1]), 5) 76 >>> np.polyval(np.poly1d([3,0,1]), np.poly1d(5)) poly1d([76]) """ p = NX.asarray(p) if isinstance(x, poly1d): y = 0 else: x = NX.asanyarray(x) y = NX.zeros_like(x) for pv in p: y = y x + pv return y def _binary_op_dispatcher(a1, a2): return (a1, a2) @array_function_dispatch(_binary_op_dispatcher) def polyadd(a1, a2): """ Find the sum of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Returns the polynomial resulting from the sum of two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree. Parameters ---------- a1, a2 : array_like or poly1d object Input polynomials. Returns ------- out : ndarray or poly1d object The sum of the inputs. If either input is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree. See Also -------- poly1d : A one-dimensional polynomial class. poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval Examples -------- >>> np.polyadd([1, 2], [9, 5, 4]) array([9, 6, 6]) Using poly1d objects: >>> p1 = np.poly1d([1, 2]) >>> p2 = np.poly1d([9, 5, 4]) >>> print(p1) 1 x + 2 >>> print(p2) 2 9 x + 5 x + 4 >>> print(np.polyadd(p1, p2)) 2 9 x + 6 x + 6 """ truepoly = (isinstance(a1, poly1d) or isinstance(a2, poly1d)) a1 = atleast_1d(a1) a2 = atleast_1d(a2) diff = len(a2) - len(a1) if diff == 0: val = a1 + a2 elif diff > 0: zr = NX.zeros(diff, a1.dtype) val = NX.concatenate((zr, a1)) + a2 else: zr = NX.zeros(abs(diff), a2.dtype) val = a1 + NX.concatenate((zr, a2)) if truepoly: val = poly1d(val) return val @array_function_dispatch(_binary_op_dispatcher) def polysub(a1, a2): """ Difference (subtraction) of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Given two polynomials `a1` and `a2`, returns ``a1 - a2``. `a1` and `a2` can be either array_like sequences of the polynomials' coefficients (including coefficients equal to zero), or `poly1d` objects. Parameters ---------- a1, a2 : array_like or poly1d Minuend and subtrahend polynomials, respectively. Returns ------- out : ndarray or poly1d Array or `poly1d` object of the difference polynomial's coefficients. See Also -------- polyval, polydiv, polymul, polyadd Examples -------- .. math:: (2 x^2 + 10 x - 2) - (3 x^2 + 10 x -4) = (-x^2 + 2) >>> np.polysub([2, 10, -2], [3, 10, -4]) array([-1, 0, 2]) """ truepoly = (isinstance(a1, poly1d) or isinstance(a2, poly1d)) a1 = atleast_1d(a1) a2 = atleast_1d(a2) diff = len(a2) - len(a1) if diff == 0: val = a1 - a2 elif diff > 0: zr = NX.zeros(diff, a1.dtype) val = NX.concatenate((zr, a1)) - a2 else: zr = NX.zeros(abs(diff), a2.dtype) val = a1 - NX.concatenate((zr, a2)) if truepoly: val = poly1d(val) return val @array_function_dispatch(_binary_op_dispatcher) def polymul(a1, a2): """ Find the product of two polynomials. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. Finds the polynomial resulting from the multiplication of the two input polynomials. Each input must be either a poly1d object or a 1D sequence of polynomial coefficients, from highest to lowest degree. Parameters ---------- a1, a2 : array_like or poly1d object Input polynomials. Returns ------- out : ndarray or poly1d object The polynomial resulting from the multiplication of the inputs. If either inputs is a poly1d object, then the output is also a poly1d object. Otherwise, it is a 1D array of polynomial coefficients from highest to lowest degree. See Also -------- poly1d : A one-dimensional polynomial class. poly, polyadd, polyder, polydiv, polyfit, polyint, polysub, polyval convolve : Array convolution. Same output as polymul, but has parameter for overlap mode. Examples -------- >>> np.polymul([1, 2, 3], [9, 5, 1]) array([ 9, 23, 38, 17, 3]) Using poly1d objects: >>> p1 = np.poly1d([1, 2, 3]) >>> p2 = np.poly1d([9, 5, 1]) >>> print(p1) 2 1 x + 2 x + 3 >>> print(p2) 2 9 x + 5 x + 1 >>> print(np.polymul(p1, p2)) 4 3 2 9 x + 23 x + 38 x + 17 x + 3 """ truepoly = (isinstance(a1, poly1d) or isinstance(a2, poly1d)) a1, a2 = poly1d(a1), poly1d(a2) val = NX.convolve(a1, a2) if truepoly: val = poly1d(val) return val def _polydiv_dispatcher(u, v): return (u, v) @array_function_dispatch(_polydiv_dispatcher) def polydiv(u, v): """ Returns the quotient and remainder of polynomial division. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. The input arrays are the coefficients (including any coefficients equal to zero) of the "numerator" (dividend) and "denominator" (divisor) polynomials, respectively. Parameters ---------- u : array_like or poly1d Dividend polynomial's coefficients. v : array_like or poly1d Divisor polynomial's coefficients. Returns ------- q : ndarray Coefficients, including those equal to zero, of the quotient. r : ndarray Coefficients, including those equal to zero, of the remainder. See Also -------- poly, polyadd, polyder, polydiv, polyfit, polyint, polymul, polysub polyval Notes ----- Both `u` and `v` must be 0-d or 1-d (ndim = 0 or 1), but `u.ndim` need not equal `v.ndim`. In other words, all four possible combinations - ``u.ndim = v.ndim = 0``, ``u.ndim = v.ndim = 1``, ``u.ndim = 1, v.ndim = 0``, and ``u.ndim = 0, v.ndim = 1`` - work. Examples -------- .. math:: \\frac{3x^2 + 5x + 2}{2x + 1} = 1.5x + 1.75, remainder 0.25 >>> x = np.array([3.0, 5.0, 2.0]) >>> y = np.array([2.0, 1.0]) >>> np.polydiv(x, y) (array([1.5 , 1.75]), array([0.25])) """ truepoly = (isinstance(u, poly1d) or isinstance(v, poly1d)) u = atleast_1d(u) + 0.0 v = atleast_1d(v) + 0.0 # w has the common type w = u[0] + v[0] m = len(u) - 1 n = len(v) - 1 scale = 1. / v[0] q = NX.zeros((max(m - n + 1, 1),), w.dtype) r = u.astype(w.dtype) for k in range(0, m-n+1): d = scale * r[k] q[k] = d r[k:k+n+1] -= dv while NX.allclose(r[0], 0, rtol=1e-14) and (r.shape[-1] > 1): r = r[1:] if truepoly: return poly1d(q), poly1d(r) return q, r _poly_mat = re.compile(r"\\([0-9])") def _raise_power(astr, wrap=70): n = 0 line1 = '' line2 = '' output = ' ' while True: mat = _poly_mat.search(astr, n) if mat is None: break span = mat.span() power = mat.groups()[0] partstr = astr[n:span[0]] n = span[1] toadd2 = partstr + ' '(len(power)-1) toadd1 = ' '(len(partstr)-1) + power if ((len(line2) + len(toadd2) > wrap) or (len(line1) + len(toadd1) > wrap)): output += line1 + "\n" + line2 + "\n " line1 = toadd1 line2 = toadd2 else: line2 += partstr + ' '(len(power)-1) line1 += ' '(len(partstr)-1) + power output += line1 + "\n" + line2 return output + astr[n:] @set_module('numpy') class poly1d: """ A one-dimensional polynomial class. .. note:: This forms part of the old polynomial API. Since version 1.4, the new polynomial API defined in `numpy.polynomial` is preferred. A summary of the differences can be found in the :doc:`transition guide </reference/routines.polynomials>`. A convenience class, used to encapsulate "natural" operations on polynomials so that said operations may take on their customary form in code (see Examples). Parameters ---------- c_or_r : array_like The polynomial's coefficients, in decreasing powers, or if the value of the second parameter is True, the polynomial's roots (values where the polynomial evaluates to 0). For example, ``poly1d([1, 2, 3])`` returns an object that represents :math:`x^2 + 2x + 3`, whereas ``poly1d([1, 2, 3], True)`` returns one that represents :math:`(x-1)(x-2)(x-3) = x^3 - 6x^2 + 11x -6`. r : bool, optional If True, `c_or_r` specifies the polynomial's roots; the default is False. variable : str, optional Changes the variable used when printing `p` from `x` to `variable` (see Examples). Examples -------- Construct the polynomial :math:`x^2 + 2x + 3`: >>> p = np.poly1d([1, 2, 3]) >>> print(np.poly1d(p)) 2 1 x + 2 x + 3 Evaluate the polynomial at :math:`x = 0.5`: >>> p(0.5) 4.25 Find the roots: >>> p.r array([-1.+1.41421356j, -1.-1.41421356j]) >>> p(p.r) array([ -4.44089210e-16+0.j, -4.44089210e-16+0.j]) # may vary These numbers in the previous line represent (0, 0) to machine precision Show the coefficients: >>> p.c array([1, 2, 3]) Display the order (the leading zero-coefficients are removed): >>> p.order 2 Show the coefficient of the k-th power in the polynomial (which is equivalent to ``p.c[-(i+1)]``): >>> p[1] 2 Polynomials can be added, subtracted, multiplied, and divided (returns quotient and remainder): >>> p * p poly1d([ 1, 4, 10, 12, 9]) >>> (p3 + 4) / p (poly1d([ 1., 4., 10., 12., 9.]), poly1d([4.])) ``asarray(p)`` gives the coefficient array, so polynomials can be used in all functions that accept arrays: >>> p2 # square of polynomial poly1d([ 1, 4, 10, 12, 9]) >>> np.square(p) # square of individual coefficients array([1, 4, 9]) The variable used in the string representation of `p` can be modified, using the `variable` parameter: >>> p = np.poly1d([1,2,3], variable='z') >>> print(p) 2 1 z + 2 z + 3 Construct a polynomial from its roots: >>> np.poly1d([1, 2], True) poly1d([ 1., -3., 2.]) This is the same polynomial as obtained by: >>> np.poly1d([1, -1]) * np.poly1d([1, -2]) poly1d([ 1, -3, 2]) """ __hash__ = None @property def coeffs(self): """ The polynomial coefficients """ return self._coeffs @coeffs.setter def coeffs(self, value): # allowing this makes p.coeffs = 2 legal if value is not self._coeffs: raise AttributeError("Cannot set attribute") @property def variable(self): """ The name of the polynomial variable """ return self._variable # calculated attributes @property def order(self): """ The order or degree of the polynomial """ return len(self._coeffs) - 1 @property def roots(self): """ The roots of the polynomial, where self(x) == 0 """ return roots(self._coeffs) # our internal _coeffs property need to be backed by __dict__['coeffs'] for # scipy to work correctly. @property def _coeffs(self): return self.__dict__['coeffs'] @_coeffs.setter def _coeffs(self, coeffs): self.__dict__['coeffs'] = coeffs # alias attributes r = roots c = coef = coefficients = coeffs o = order def __init__(self, c_or_r, r=False, variable=None): if isinstance(c_or_r, poly1d): self._variable = c_or_r._variable self._coeffs = c_or_r._coeffs if set(c_or_r.__dict__) - set(self.__dict__): msg = ("In the future extra properties will not be copied " "across when constructing one poly1d from another") warnings.warn(msg, FutureWarning, stacklevel=2) self.__dict__.update(c_or_r.__dict__) if variable is not None: self._variable = variable return if r: c_or_r = poly(c_or_r) c_or_r = atleast_1d(c_or_r) if c_or_r.ndim > 1: raise ValueError("Polynomial must be 1d only.") c_or_r = trim_zeros(c_or_r, trim='f') if len(c_or_r) == 0: c_or_r = NX.array([0], dtype=c_or_r.dtype) self._coeffs = c_or_r if variable is None: variable = 'x' self._variable = variable def __array__(self, t=None): if t: return NX.asarray(self.coeffs, t) else: return NX.asarray(self.coeffs) def __repr__(self): vals = repr(self.coeffs) vals = vals[6:-1] return "poly1d(%s)" % vals def __len__(self): return self.order def __str__(self): thestr = "0" var = self.variable # Remove leading zeros coeffs = self.coeffs[NX.logical_or.accumulate(self.coeffs != 0)] N = len(coeffs)-1 def fmt_float(q): s = '%.4g' % q if s.endswith('.0000'): s = s[:-5] return s for k, coeff in enumerate(coeffs): if not iscomplex(coeff): coefstr = fmt_float(real(coeff)) elif real(coeff) == 0: coefstr = '%sj' % fmt_float(imag(coeff)) else: coefstr = '(%s + %sj)' % (fmt_float(real(coeff)), fmt_float(imag(coeff))) power = (N-k) if power == 0: if coefstr != '0': newstr = '%s' % (coefstr,) else: if k == 0: newstr = '0' else: newstr = '' elif power == 1: if coefstr == '0': newstr = '' elif coefstr == 'b': newstr = var else: newstr = '%s %s' % (coefstr, var) else: if coefstr == '0': newstr = '' elif coefstr == 'b': newstr = '%s%d' % (var, power,) else: newstr = '%s %s%d' % (coefstr, var, power) if k > 0: if newstr != '': if newstr.startswith('-'): thestr = "%s - %s" % (thestr, newstr[1:]) else: thestr = "%s + %s" % (thestr, newstr) else: thestr = newstr return _raise_power(thestr) def __call__(self, val): return polyval(self.coeffs, val) def __neg__(self): return poly1d(-self.coeffs) def __pos__(self): return self def __mul__(self, other): if isscalar(other): return poly1d(self.coeffs other) else: other = poly1d(other) return poly1d(polymul(self.coeffs, other.coeffs)) def __rmul__(self, other): if isscalar(other): return poly1d(other * self.coeffs) else: other = poly1d(other) return poly1d(polymul(self.coeffs, other.coeffs)) def __add__(self, other): other = poly1d(other) return poly1d(polyadd(self.coeffs, other.coeffs)) def __radd__(self, other): other = poly1d(other) return poly1d(polyadd(self.coeffs, other.coeffs)) def __pow__(self, val): if not isscalar(val) or int(val) != val or val < 0: raise ValueError("Power to non-negative integers only.") res = [1] for _ in range(val): res = polymul(self.coeffs, res) return poly1d(res) def __sub__(self, other): other = poly1d(other) return poly1d(polysub(self.coeffs, other.coeffs)) def __rsub__(self, other): other = poly1d(other) return poly1d(polysub(other.coeffs, self.coeffs)) def __div__(self, other): if isscalar(other): return poly1d(self.coeffs/other) else: other = poly1d(other) return polydiv(self, other) __truediv__ = __div__ def __rdiv__(self, other): if isscalar(other): return poly1d(other/self.coeffs) else: other = poly1d(other) return polydiv(other, self) __rtruediv__ = __rdiv__ def __eq__(self, other): if not isinstance(other, poly1d): return NotImplemented if self.coeffs.shape != other.coeffs.shape: return False return (self.coeffs == other.coeffs).all() def __ne__(self, other): if not isinstance(other, poly1d): return NotImplemented return not self.__eq__(other) def __getitem__(self, val): ind = self.order - val if val > self.order: return self.coeffs.dtype.type(0) if val < 0: return self.coeffs.dtype.type(0) return self.coeffs[ind] def __setitem__(self, key, val): ind = self.order - key if key < 0: raise ValueError("Does not support negative powers.") if key > self.order: zr = NX.zeros(key-self.order, self.coeffs.dtype) self._coeffs = NX.concatenate((zr, self.coeffs)) ind = 0 self._coeffs[ind] = val return def __iter__(self): return iter(self.coeffs) def integ(self, m=1, k=0): """ Return an antiderivative (indefinite integral) of this polynomial. Refer to `polyint` for full documentation. See Also -------- polyint : equivalent function """ return poly1d(polyint(self.coeffs, m=m, k=k)) def deriv(self, m=1): """ Return a derivative of this polynomial. Refer to `polyder` for full documentation. See Also -------- polyder : equivalent function """ return poly1d(polyder(self.coeffs, m=m)) # Stuff to do on module import warnings.simplefilter('always', RankWarning)	43.1 KB	2026-01-20 12:58
📄 polynomial.pyi from typing import ( Literal as L, overload, Any, SupportsInt, SupportsIndex, TypeVar, NoReturn, ) from numpy import ( RankWarning as RankWarning, poly1d as poly1d, unsignedinteger, signedinteger, floating, complexfloating, bool_, int32, int64, float64, complex128, object_, ) from numpy._typing import ( NDArray, ArrayLike, _ArrayLikeBool_co, _ArrayLikeUInt_co, _ArrayLikeInt_co, _ArrayLikeFloat_co, _ArrayLikeComplex_co, _ArrayLikeObject_co, ) _T = TypeVar("_T") _2Tup = tuple[_T, _T] _5Tup = tuple[ _T, NDArray[float64], NDArray[int32], NDArray[float64], NDArray[float64], ] __all__: list[str] def poly(seq_of_zeros: ArrayLike) -> NDArray[floating[Any]]: ... # Returns either a float or complex array depending on the input values. # See `np.linalg.eigvals`. def roots(p: ArrayLike) -> NDArray[complexfloating[Any, Any]] \| NDArray[floating[Any]]: ... @overload def polyint( p: poly1d, m: SupportsInt \| SupportsIndex = ..., k: None \| _ArrayLikeComplex_co \| _ArrayLikeObject_co = ..., ) -> poly1d: ... @overload def polyint( p: _ArrayLikeFloat_co, m: SupportsInt \| SupportsIndex = ..., k: None \| _ArrayLikeFloat_co = ..., ) -> NDArray[floating[Any]]: ... @overload def polyint( p: _ArrayLikeComplex_co, m: SupportsInt \| SupportsIndex = ..., k: None \| _ArrayLikeComplex_co = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def polyint( p: _ArrayLikeObject_co, m: SupportsInt \| SupportsIndex = ..., k: None \| _ArrayLikeObject_co = ..., ) -> NDArray[object_]: ... @overload def polyder( p: poly1d, m: SupportsInt \| SupportsIndex = ..., ) -> poly1d: ... @overload def polyder( p: _ArrayLikeFloat_co, m: SupportsInt \| SupportsIndex = ..., ) -> NDArray[floating[Any]]: ... @overload def polyder( p: _ArrayLikeComplex_co, m: SupportsInt \| SupportsIndex = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def polyder( p: _ArrayLikeObject_co, m: SupportsInt \| SupportsIndex = ..., ) -> NDArray[object_]: ... @overload def polyfit( x: _ArrayLikeFloat_co, y: _ArrayLikeFloat_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[False] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: L[False] = ..., ) -> NDArray[float64]: ... @overload def polyfit( x: _ArrayLikeComplex_co, y: _ArrayLikeComplex_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[False] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: L[False] = ..., ) -> NDArray[complex128]: ... @overload def polyfit( x: _ArrayLikeFloat_co, y: _ArrayLikeFloat_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[False] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: L[True, "unscaled"] = ..., ) -> _2Tup[NDArray[float64]]: ... @overload def polyfit( x: _ArrayLikeComplex_co, y: _ArrayLikeComplex_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[False] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: L[True, "unscaled"] = ..., ) -> _2Tup[NDArray[complex128]]: ... @overload def polyfit( x: _ArrayLikeFloat_co, y: _ArrayLikeFloat_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[True] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: bool \| L["unscaled"] = ..., ) -> _5Tup[NDArray[float64]]: ... @overload def polyfit( x: _ArrayLikeComplex_co, y: _ArrayLikeComplex_co, deg: SupportsIndex \| SupportsInt, rcond: None \| float = ..., full: L[True] = ..., w: None \| _ArrayLikeFloat_co = ..., cov: bool \| L["unscaled"] = ..., ) -> _5Tup[NDArray[complex128]]: ... @overload def polyval( p: _ArrayLikeBool_co, x: _ArrayLikeBool_co, ) -> NDArray[int64]: ... @overload def polyval( p: _ArrayLikeUInt_co, x: _ArrayLikeUInt_co, ) -> NDArray[unsignedinteger[Any]]: ... @overload def polyval( p: _ArrayLikeInt_co, x: _ArrayLikeInt_co, ) -> NDArray[signedinteger[Any]]: ... @overload def polyval( p: _ArrayLikeFloat_co, x: _ArrayLikeFloat_co, ) -> NDArray[floating[Any]]: ... @overload def polyval( p: _ArrayLikeComplex_co, x: _ArrayLikeComplex_co, ) -> NDArray[complexfloating[Any, Any]]: ... @overload def polyval( p: _ArrayLikeObject_co, x: _ArrayLikeObject_co, ) -> NDArray[object_]: ... @overload def polyadd( a1: poly1d, a2: _ArrayLikeComplex_co \| _ArrayLikeObject_co, ) -> poly1d: ... @overload def polyadd( a1: _ArrayLikeComplex_co \| _ArrayLikeObject_co, a2: poly1d, ) -> poly1d: ... @overload def polyadd( a1: _ArrayLikeBool_co, a2: _ArrayLikeBool_co, ) -> NDArray[bool_]: ... @overload def polyadd( a1: _ArrayLikeUInt_co, a2: _ArrayLikeUInt_co, ) -> NDArray[unsignedinteger[Any]]: ... @overload def polyadd( a1: _ArrayLikeInt_co, a2: _ArrayLikeInt_co, ) -> NDArray[signedinteger[Any]]: ... @overload def polyadd( a1: _ArrayLikeFloat_co, a2: _ArrayLikeFloat_co, ) -> NDArray[floating[Any]]: ... @overload def polyadd( a1: _ArrayLikeComplex_co, a2: _ArrayLikeComplex_co, ) -> NDArray[complexfloating[Any, Any]]: ... @overload def polyadd( a1: _ArrayLikeObject_co, a2: _ArrayLikeObject_co, ) -> NDArray[object_]: ... @overload def polysub( a1: poly1d, a2: _ArrayLikeComplex_co \| _ArrayLikeObject_co, ) -> poly1d: ... @overload def polysub( a1: _ArrayLikeComplex_co \| _ArrayLikeObject_co, a2: poly1d, ) -> poly1d: ... @overload def polysub( a1: _ArrayLikeBool_co, a2: _ArrayLikeBool_co, ) -> NoReturn: ... @overload def polysub( a1: _ArrayLikeUInt_co, a2: _ArrayLikeUInt_co, ) -> NDArray[unsignedinteger[Any]]: ... @overload def polysub( a1: _ArrayLikeInt_co, a2: _ArrayLikeInt_co, ) -> NDArray[signedinteger[Any]]: ... @overload def polysub( a1: _ArrayLikeFloat_co, a2: _ArrayLikeFloat_co, ) -> NDArray[floating[Any]]: ... @overload def polysub( a1: _ArrayLikeComplex_co, a2: _ArrayLikeComplex_co, ) -> NDArray[complexfloating[Any, Any]]: ... @overload def polysub( a1: _ArrayLikeObject_co, a2: _ArrayLikeObject_co, ) -> NDArray[object_]: ... # NOTE: Not an alias, but they do have the same signature (that we can reuse) polymul = polyadd @overload def polydiv( u: poly1d, v: _ArrayLikeComplex_co \| _ArrayLikeObject_co, ) -> _2Tup[poly1d]: ... @overload def polydiv( u: _ArrayLikeComplex_co \| _ArrayLikeObject_co, v: poly1d, ) -> _2Tup[poly1d]: ... @overload def polydiv( u: _ArrayLikeFloat_co, v: _ArrayLikeFloat_co, ) -> _2Tup[NDArray[floating[Any]]]: ... @overload def polydiv( u: _ArrayLikeComplex_co, v: _ArrayLikeComplex_co, ) -> _2Tup[NDArray[complexfloating[Any, Any]]]: ... @overload def polydiv( u: _ArrayLikeObject_co, v: _ArrayLikeObject_co, ) -> _2Tup[NDArray[Any]]: ...	6.79 KB	2026-01-20 12:58
📄 recfunctions.py """ Collection of utilities to manipulate structured arrays. Most of these functions were initially implemented by John Hunter for matplotlib. They have been rewritten and extended for convenience. """ import itertools import numpy as np import numpy.ma as ma from numpy import ndarray, recarray from numpy.ma import MaskedArray from numpy.ma.mrecords import MaskedRecords from numpy.core.overrides import array_function_dispatch from numpy.lib._iotools import _is_string_like _check_fill_value = np.ma.core._check_fill_value __all__ = [ 'append_fields', 'apply_along_fields', 'assign_fields_by_name', 'drop_fields', 'find_duplicates', 'flatten_descr', 'get_fieldstructure', 'get_names', 'get_names_flat', 'join_by', 'merge_arrays', 'rec_append_fields', 'rec_drop_fields', 'rec_join', 'recursive_fill_fields', 'rename_fields', 'repack_fields', 'require_fields', 'stack_arrays', 'structured_to_unstructured', 'unstructured_to_structured', ] def _recursive_fill_fields_dispatcher(input, output): return (input, output) @array_function_dispatch(_recursive_fill_fields_dispatcher) def recursive_fill_fields(input, output): """ Fills fields from output with fields from input, with support for nested structures. Parameters ---------- input : ndarray Input array. output : ndarray Output array. Notes ----- * `output` should be at least the same size as `input` Examples -------- >>> from numpy.lib import recfunctions as rfn >>> a = np.array([(1, 10.), (2, 20.)], dtype=[('A', np.int64), ('B', np.float64)]) >>> b = np.zeros((3,), dtype=a.dtype) >>> rfn.recursive_fill_fields(a, b) array([(1, 10.), (2, 20.), (0, 0.)], dtype=[('A', '<i8'), ('B', '<f8')]) """ newdtype = output.dtype for field in newdtype.names: try: current = input[field] except ValueError: continue if current.dtype.names is not None: recursive_fill_fields(current, output[field]) else: output[field][:len(current)] = current return output def _get_fieldspec(dtype): """ Produce a list of name/dtype pairs corresponding to the dtype fields Similar to dtype.descr, but the second item of each tuple is a dtype, not a string. As a result, this handles subarray dtypes Can be passed to the dtype constructor to reconstruct the dtype, noting that this (deliberately) discards field offsets. Examples -------- >>> dt = np.dtype([(('a', 'A'), np.int64), ('b', np.double, 3)]) >>> dt.descr [(('a', 'A'), '<i8'), ('b', '<f8', (3,))] >>> _get_fieldspec(dt) [(('a', 'A'), dtype('int64')), ('b', dtype(('<f8', (3,))))] """ if dtype.names is None: # .descr returns a nameless field, so we should too return [('', dtype)] else: fields = ((name, dtype.fields[name]) for name in dtype.names) # keep any titles, if present return [ (name if len(f) == 2 else (f[2], name), f[0]) for name, f in fields ] def get_names(adtype): """ Returns the field names of the input datatype as a tuple. Input datatype must have fields otherwise error is raised. Parameters ---------- adtype : dtype Input datatype Examples -------- >>> from numpy.lib import recfunctions as rfn >>> rfn.get_names(np.empty((1,), dtype=[('A', int)]).dtype) ('A',) >>> rfn.get_names(np.empty((1,), dtype=[('A',int), ('B', float)]).dtype) ('A', 'B') >>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])]) >>> rfn.get_names(adtype) ('a', ('b', ('ba', 'bb'))) """ listnames = [] names = adtype.names for name in names: current = adtype[name] if current.names is not None: listnames.append((name, tuple(get_names(current)))) else: listnames.append(name) return tuple(listnames) def get_names_flat(adtype): """ Returns the field names of the input datatype as a tuple. Input datatype must have fields otherwise error is raised. Nested structure are flattened beforehand. Parameters ---------- adtype : dtype Input datatype Examples -------- >>> from numpy.lib import recfunctions as rfn >>> rfn.get_names_flat(np.empty((1,), dtype=[('A', int)]).dtype) is None False >>> rfn.get_names_flat(np.empty((1,), dtype=[('A',int), ('B', str)]).dtype) ('A', 'B') >>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])]) >>> rfn.get_names_flat(adtype) ('a', 'b', 'ba', 'bb') """ listnames = [] names = adtype.names for name in names: listnames.append(name) current = adtype[name] if current.names is not None: listnames.extend(get_names_flat(current)) return tuple(listnames) def flatten_descr(ndtype): """ Flatten a structured data-type description. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> ndtype = np.dtype([('a', '<i4'), ('b', [('ba', '<f8'), ('bb', '<i4')])]) >>> rfn.flatten_descr(ndtype) (('a', dtype('int32')), ('ba', dtype('float64')), ('bb', dtype('int32'))) """ names = ndtype.names if names is None: return (('', ndtype),) else: descr = [] for field in names: (typ, _) = ndtype.fields[field] if typ.names is not None: descr.extend(flatten_descr(typ)) else: descr.append((field, typ)) return tuple(descr) def _zip_dtype(seqarrays, flatten=False): newdtype = [] if flatten: for a in seqarrays: newdtype.extend(flatten_descr(a.dtype)) else: for a in seqarrays: current = a.dtype if current.names is not None and len(current.names) == 1: # special case - dtypes of 1 field are flattened newdtype.extend(_get_fieldspec(current)) else: newdtype.append(('', current)) return np.dtype(newdtype) def _zip_descr(seqarrays, flatten=False): """ Combine the dtype description of a series of arrays. Parameters ---------- seqarrays : sequence of arrays Sequence of arrays flatten : {boolean}, optional Whether to collapse nested descriptions. """ return _zip_dtype(seqarrays, flatten=flatten).descr def get_fieldstructure(adtype, lastname=None, parents=None,): """ Returns a dictionary with fields indexing lists of their parent fields. This function is used to simplify access to fields nested in other fields. Parameters ---------- adtype : np.dtype Input datatype lastname : optional Last processed field name (used internally during recursion). parents : dictionary Dictionary of parent fields (used interbally during recursion). Examples -------- >>> from numpy.lib import recfunctions as rfn >>> ndtype = np.dtype([('A', int), ... ('B', [('BA', int), ... ('BB', [('BBA', int), ('BBB', int)])])]) >>> rfn.get_fieldstructure(ndtype) ... # XXX: possible regression, order of BBA and BBB is swapped {'A': [], 'B': [], 'BA': ['B'], 'BB': ['B'], 'BBA': ['B', 'BB'], 'BBB': ['B', 'BB']} """ if parents is None: parents = {} names = adtype.names for name in names: current = adtype[name] if current.names is not None: if lastname: parents[name] = [lastname, ] else: parents[name] = [] parents.update(get_fieldstructure(current, name, parents)) else: lastparent = [_ for _ in (parents.get(lastname, []) or [])] if lastparent: lastparent.append(lastname) elif lastname: lastparent = [lastname, ] parents[name] = lastparent or [] return parents def _izip_fields_flat(iterable): """ Returns an iterator of concatenated fields from a sequence of arrays, collapsing any nested structure. """ for element in iterable: if isinstance(element, np.void): yield from _izip_fields_flat(tuple(element)) else: yield element def _izip_fields(iterable): """ Returns an iterator of concatenated fields from a sequence of arrays. """ for element in iterable: if (hasattr(element, '__iter__') and not isinstance(element, str)): yield from _izip_fields(element) elif isinstance(element, np.void) and len(tuple(element)) == 1: # this statement is the same from the previous expression yield from _izip_fields(element) else: yield element def _izip_records(seqarrays, fill_value=None, flatten=True): """ Returns an iterator of concatenated items from a sequence of arrays. Parameters ---------- seqarrays : sequence of arrays Sequence of arrays. fill_value : {None, integer} Value used to pad shorter iterables. flatten : {True, False}, Whether to """ # Should we flatten the items, or just use a nested approach if flatten: zipfunc = _izip_fields_flat else: zipfunc = _izip_fields for tup in itertools.zip_longest(seqarrays, fillvalue=fill_value): yield tuple(zipfunc(tup)) def _fix_output(output, usemask=True, asrecarray=False): """ Private function: return a recarray, a ndarray, a MaskedArray or a MaskedRecords depending on the input parameters """ if not isinstance(output, MaskedArray): usemask = False if usemask: if asrecarray: output = output.view(MaskedRecords) else: output = ma.filled(output) if asrecarray: output = output.view(recarray) return output def _fix_defaults(output, defaults=None): """ Update the fill_value and masked data of `output` from the default given in a dictionary defaults. """ names = output.dtype.names (data, mask, fill_value) = (output.data, output.mask, output.fill_value) for (k, v) in (defaults or {}).items(): if k in names: fill_value[k] = v data[k][mask[k]] = v return output def _merge_arrays_dispatcher(seqarrays, fill_value=None, flatten=None, usemask=None, asrecarray=None): return seqarrays @array_function_dispatch(_merge_arrays_dispatcher) def merge_arrays(seqarrays, fill_value=-1, flatten=False, usemask=False, asrecarray=False): """ Merge arrays field by field. Parameters ---------- seqarrays : sequence of ndarrays Sequence of arrays fill_value : {float}, optional Filling value used to pad missing data on the shorter arrays. flatten : {False, True}, optional Whether to collapse nested fields. usemask : {False, True}, optional Whether to return a masked array or not. asrecarray : {False, True}, optional Whether to return a recarray (MaskedRecords) or not. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> rfn.merge_arrays((np.array([1, 2]), np.array([10., 20., 30.]))) array([( 1, 10.), ( 2, 20.), (-1, 30.)], dtype=[('f0', '<i8'), ('f1', '<f8')]) >>> rfn.merge_arrays((np.array([1, 2], dtype=np.int64), ... np.array([10., 20., 30.])), usemask=False) array([(1, 10.0), (2, 20.0), (-1, 30.0)], dtype=[('f0', '<i8'), ('f1', '<f8')]) >>> rfn.merge_arrays((np.array([1, 2]).view([('a', np.int64)]), ... np.array([10., 20., 30.])), ... usemask=False, asrecarray=True) rec.array([( 1, 10.), ( 2, 20.), (-1, 30.)], dtype=[('a', '<i8'), ('f1', '<f8')]) Notes ----- Without a mask, the missing value will be filled with something, depending on what its corresponding type: * ``-1`` for integers * ``-1.0`` for floating point numbers * ``'-'`` for characters * ``'-1'`` for strings * ``True`` for boolean values * XXX: I just obtained these values empirically """ # Only one item in the input sequence ? if (len(seqarrays) == 1): seqarrays = np.asanyarray(seqarrays[0]) # Do we have a single ndarray as input ? if isinstance(seqarrays, (ndarray, np.void)): seqdtype = seqarrays.dtype # Make sure we have named fields if seqdtype.names is None: seqdtype = np.dtype([('', seqdtype)]) if not flatten or _zip_dtype((seqarrays,), flatten=True) == seqdtype: # Minimal processing needed: just make sure everything's a-ok seqarrays = seqarrays.ravel() # Find what type of array we must return if usemask: if asrecarray: seqtype = MaskedRecords else: seqtype = MaskedArray elif asrecarray: seqtype = recarray else: seqtype = ndarray return seqarrays.view(dtype=seqdtype, type=seqtype) else: seqarrays = (seqarrays,) else: # Make sure we have arrays in the input sequence seqarrays = [np.asanyarray(_m) for _m in seqarrays] # Find the sizes of the inputs and their maximum sizes = tuple(a.size for a in seqarrays) maxlength = max(sizes) # Get the dtype of the output (flattening if needed) newdtype = _zip_dtype(seqarrays, flatten=flatten) # Initialize the sequences for data and mask seqdata = [] seqmask = [] # If we expect some kind of MaskedArray, make a special loop. if usemask: for (a, n) in zip(seqarrays, sizes): nbmissing = (maxlength - n) # Get the data and mask data = a.ravel().__array__() mask = ma.getmaskarray(a).ravel() # Get the filling value (if needed) if nbmissing: fval = _check_fill_value(fill_value, a.dtype) if isinstance(fval, (ndarray, np.void)): if len(fval.dtype) == 1: fval = fval.item()[0] fmsk = True else: fval = np.array(fval, dtype=a.dtype, ndmin=1) fmsk = np.ones((1,), dtype=mask.dtype) else: fval = None fmsk = True # Store an iterator padding the input to the expected length seqdata.append(itertools.chain(data, [fval] * nbmissing)) seqmask.append(itertools.chain(mask, [fmsk] * nbmissing)) # Create an iterator for the data data = tuple(_izip_records(seqdata, flatten=flatten)) output = ma.array(np.fromiter(data, dtype=newdtype, count=maxlength), mask=list(_izip_records(seqmask, flatten=flatten))) if asrecarray: output = output.view(MaskedRecords) else: # Same as before, without the mask we don't need... for (a, n) in zip(seqarrays, sizes): nbmissing = (maxlength - n) data = a.ravel().__array__() if nbmissing: fval = _check_fill_value(fill_value, a.dtype) if isinstance(fval, (ndarray, np.void)): if len(fval.dtype) == 1: fval = fval.item()[0] else: fval = np.array(fval, dtype=a.dtype, ndmin=1) else: fval = None seqdata.append(itertools.chain(data, [fval] * nbmissing)) output = np.fromiter(tuple(_izip_records(seqdata, flatten=flatten)), dtype=newdtype, count=maxlength) if asrecarray: output = output.view(recarray) # And we're done... return output def _drop_fields_dispatcher(base, drop_names, usemask=None, asrecarray=None): return (base,) @array_function_dispatch(_drop_fields_dispatcher) def drop_fields(base, drop_names, usemask=True, asrecarray=False): """ Return a new array with fields in `drop_names` dropped. Nested fields are supported. .. versionchanged:: 1.18.0 `drop_fields` returns an array with 0 fields if all fields are dropped, rather than returning ``None`` as it did previously. Parameters ---------- base : array Input array drop_names : string or sequence String or sequence of strings corresponding to the names of the fields to drop. usemask : {False, True}, optional Whether to return a masked array or not. asrecarray : string or sequence, optional Whether to return a recarray or a mrecarray (`asrecarray=True`) or a plain ndarray or masked array with flexible dtype. The default is False. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> a = np.array([(1, (2, 3.0)), (4, (5, 6.0))], ... dtype=[('a', np.int64), ('b', [('ba', np.double), ('bb', np.int64)])]) >>> rfn.drop_fields(a, 'a') array([((2., 3),), ((5., 6),)], dtype=[('b', [('ba', '<f8'), ('bb', '<i8')])]) >>> rfn.drop_fields(a, 'ba') array([(1, (3,)), (4, (6,))], dtype=[('a', '<i8'), ('b', [('bb', '<i8')])]) >>> rfn.drop_fields(a, ['ba', 'bb']) array([(1,), (4,)], dtype=[('a', '<i8')]) """ if _is_string_like(drop_names): drop_names = [drop_names] else: drop_names = set(drop_names) def _drop_descr(ndtype, drop_names): names = ndtype.names newdtype = [] for name in names: current = ndtype[name] if name in drop_names: continue if current.names is not None: descr = _drop_descr(current, drop_names) if descr: newdtype.append((name, descr)) else: newdtype.append((name, current)) return newdtype newdtype = _drop_descr(base.dtype, drop_names) output = np.empty(base.shape, dtype=newdtype) output = recursive_fill_fields(base, output) return _fix_output(output, usemask=usemask, asrecarray=asrecarray) def _keep_fields(base, keep_names, usemask=True, asrecarray=False): """ Return a new array keeping only the fields in `keep_names`, and preserving the order of those fields. Parameters ---------- base : array Input array keep_names : string or sequence String or sequence of strings corresponding to the names of the fields to keep. Order of the names will be preserved. usemask : {False, True}, optional Whether to return a masked array or not. asrecarray : string or sequence, optional Whether to return a recarray or a mrecarray (`asrecarray=True`) or a plain ndarray or masked array with flexible dtype. The default is False. """ newdtype = [(n, base.dtype[n]) for n in keep_names] output = np.empty(base.shape, dtype=newdtype) output = recursive_fill_fields(base, output) return _fix_output(output, usemask=usemask, asrecarray=asrecarray) def _rec_drop_fields_dispatcher(base, drop_names): return (base,) @array_function_dispatch(_rec_drop_fields_dispatcher) def rec_drop_fields(base, drop_names): """ Returns a new numpy.recarray with fields in `drop_names` dropped. """ return drop_fields(base, drop_names, usemask=False, asrecarray=True) def _rename_fields_dispatcher(base, namemapper): return (base,) @array_function_dispatch(_rename_fields_dispatcher) def rename_fields(base, namemapper): """ Rename the fields from a flexible-datatype ndarray or recarray. Nested fields are supported. Parameters ---------- base : ndarray Input array whose fields must be modified. namemapper : dictionary Dictionary mapping old field names to their new version. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> a = np.array([(1, (2, [3.0, 30.])), (4, (5, [6.0, 60.]))], ... dtype=[('a', int),('b', [('ba', float), ('bb', (float, 2))])]) >>> rfn.rename_fields(a, {'a':'A', 'bb':'BB'}) array([(1, (2., [ 3., 30.])), (4, (5., [ 6., 60.]))], dtype=[('A', '<i8'), ('b', [('ba', '<f8'), ('BB', '<f8', (2,))])]) """ def _recursive_rename_fields(ndtype, namemapper): newdtype = [] for name in ndtype.names: newname = namemapper.get(name, name) current = ndtype[name] if current.names is not None: newdtype.append( (newname, _recursive_rename_fields(current, namemapper)) ) else: newdtype.append((newname, current)) return newdtype newdtype = _recursive_rename_fields(base.dtype, namemapper) return base.view(newdtype) def _append_fields_dispatcher(base, names, data, dtypes=None, fill_value=None, usemask=None, asrecarray=None): yield base yield from data @array_function_dispatch(_append_fields_dispatcher) def append_fields(base, names, data, dtypes=None, fill_value=-1, usemask=True, asrecarray=False): """ Add new fields to an existing array. The names of the fields are given with the `names` arguments, the corresponding values with the `data` arguments. If a single field is appended, `names`, `data` and `dtypes` do not have to be lists but just values. Parameters ---------- base : array Input array to extend. names : string, sequence String or sequence of strings corresponding to the names of the new fields. data : array or sequence of arrays Array or sequence of arrays storing the fields to add to the base. dtypes : sequence of datatypes, optional Datatype or sequence of datatypes. If None, the datatypes are estimated from the `data`. fill_value : {float}, optional Filling value used to pad missing data on the shorter arrays. usemask : {False, True}, optional Whether to return a masked array or not. asrecarray : {False, True}, optional Whether to return a recarray (MaskedRecords) or not. """ # Check the names if isinstance(names, (tuple, list)): if len(names) != len(data): msg = "The number of arrays does not match the number of names" raise ValueError(msg) elif isinstance(names, str): names = [names, ] data = [data, ] # if dtypes is None: data = [np.array(a, copy=False, subok=True) for a in data] data = [a.view([(name, a.dtype)]) for (name, a) in zip(names, data)] else: if not isinstance(dtypes, (tuple, list)): dtypes = [dtypes, ] if len(data) != len(dtypes): if len(dtypes) == 1: dtypes = dtypes * len(data) else: msg = "The dtypes argument must be None, a dtype, or a list." raise ValueError(msg) data = [np.array(a, copy=False, subok=True, dtype=d).view([(n, d)]) for (a, n, d) in zip(data, names, dtypes)] # base = merge_arrays(base, usemask=usemask, fill_value=fill_value) if len(data) > 1: data = merge_arrays(data, flatten=True, usemask=usemask, fill_value=fill_value) else: data = data.pop() # output = ma.masked_all( max(len(base), len(data)), dtype=_get_fieldspec(base.dtype) + _get_fieldspec(data.dtype)) output = recursive_fill_fields(base, output) output = recursive_fill_fields(data, output) # return _fix_output(output, usemask=usemask, asrecarray=asrecarray) def _rec_append_fields_dispatcher(base, names, data, dtypes=None): yield base yield from data @array_function_dispatch(_rec_append_fields_dispatcher) def rec_append_fields(base, names, data, dtypes=None): """ Add new fields to an existing array. The names of the fields are given with the `names` arguments, the corresponding values with the `data` arguments. If a single field is appended, `names`, `data` and `dtypes` do not have to be lists but just values. Parameters ---------- base : array Input array to extend. names : string, sequence String or sequence of strings corresponding to the names of the new fields. data : array or sequence of arrays Array or sequence of arrays storing the fields to add to the base. dtypes : sequence of datatypes, optional Datatype or sequence of datatypes. If None, the datatypes are estimated from the `data`. See Also -------- append_fields Returns ------- appended_array : np.recarray """ return append_fields(base, names, data=data, dtypes=dtypes, asrecarray=True, usemask=False) def _repack_fields_dispatcher(a, align=None, recurse=None): return (a,) @array_function_dispatch(_repack_fields_dispatcher) def repack_fields(a, align=False, recurse=False): """ Re-pack the fields of a structured array or dtype in memory. The memory layout of structured datatypes allows fields at arbitrary byte offsets. This means the fields can be separated by padding bytes, their offsets can be non-monotonically increasing, and they can overlap. This method removes any overlaps and reorders the fields in memory so they have increasing byte offsets, and adds or removes padding bytes depending on the `align` option, which behaves like the `align` option to `numpy.dtype`. If `align=False`, this method produces a "packed" memory layout in which each field starts at the byte the previous field ended, and any padding bytes are removed. If `align=True`, this methods produces an "aligned" memory layout in which each field's offset is a multiple of its alignment, and the total itemsize is a multiple of the largest alignment, by adding padding bytes as needed. Parameters ---------- a : ndarray or dtype array or dtype for which to repack the fields. align : boolean If true, use an "aligned" memory layout, otherwise use a "packed" layout. recurse : boolean If True, also repack nested structures. Returns ------- repacked : ndarray or dtype Copy of `a` with fields repacked, or `a` itself if no repacking was needed. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> def print_offsets(d): ... print("offsets:", [d.fields[name][1] for name in d.names]) ... print("itemsize:", d.itemsize) ... >>> dt = np.dtype('u1, <i8, <f8', align=True) >>> dt dtype({'names': ['f0', 'f1', 'f2'], 'formats': ['u1', '<i8', '<f8'], \ 'offsets': [0, 8, 16], 'itemsize': 24}, align=True) >>> print_offsets(dt) offsets: [0, 8, 16] itemsize: 24 >>> packed_dt = rfn.repack_fields(dt) >>> packed_dt dtype([('f0', 'u1'), ('f1', '<i8'), ('f2', '<f8')]) >>> print_offsets(packed_dt) offsets: [0, 1, 9] itemsize: 17 """ if not isinstance(a, np.dtype): dt = repack_fields(a.dtype, align=align, recurse=recurse) return a.astype(dt, copy=False) if a.names is None: return a fieldinfo = [] for name in a.names: tup = a.fields[name] if recurse: fmt = repack_fields(tup[0], align=align, recurse=True) else: fmt = tup[0] if len(tup) == 3: name = (tup[2], name) fieldinfo.append((name, fmt)) dt = np.dtype(fieldinfo, align=align) return np.dtype((a.type, dt)) def _get_fields_and_offsets(dt, offset=0): """ Returns a flat list of (dtype, count, offset) tuples of all the scalar fields in the dtype "dt", including nested fields, in left to right order. """ # counts up elements in subarrays, including nested subarrays, and returns # base dtype and count def count_elem(dt): count = 1 while dt.shape != (): for size in dt.shape: count = size dt = dt.base return dt, count fields = [] for name in dt.names: field = dt.fields[name] f_dt, f_offset = field[0], field[1] f_dt, n = count_elem(f_dt) if f_dt.names is None: fields.append((np.dtype((f_dt, (n,))), n, f_offset + offset)) else: subfields = _get_fields_and_offsets(f_dt, f_offset + offset) size = f_dt.itemsize for i in range(n): if i == 0: # optimization: avoid list comprehension if no subarray fields.extend(subfields) else: fields.extend([(d, c, o + isize) for d, c, o in subfields]) return fields def _common_stride(offsets, counts, itemsize): """ Returns the stride between the fields, or None if the stride is not constant. The values in "counts" designate the lengths of subarrays. Subarrays are treated as many contiguous fields, with always positive stride. """ if len(offsets) <= 1: return itemsize negative = offsets[1] < offsets[0] # negative stride if negative: # reverse, so offsets will be ascending it = zip(reversed(offsets), reversed(counts)) else: it = zip(offsets, counts) prev_offset = None stride = None for offset, count in it: if count != 1: # subarray: always c-contiguous if negative: return None # subarrays can never have a negative stride if stride is None: stride = itemsize if stride != itemsize: return None end_offset = offset + (count - 1) * itemsize else: end_offset = offset if prev_offset is not None: new_stride = offset - prev_offset if stride is None: stride = new_stride if stride != new_stride: return None prev_offset = end_offset if negative: return -stride return stride def _structured_to_unstructured_dispatcher(arr, dtype=None, copy=None, casting=None): return (arr,) @array_function_dispatch(_structured_to_unstructured_dispatcher) def structured_to_unstructured(arr, dtype=None, copy=False, casting='unsafe'): """ Converts an n-D structured array into an (n+1)-D unstructured array. The new array will have a new last dimension equal in size to the number of field-elements of the input array. If not supplied, the output datatype is determined from the numpy type promotion rules applied to all the field datatypes. Nested fields, as well as each element of any subarray fields, all count as a single field-elements. Parameters ---------- arr : ndarray Structured array or dtype to convert. Cannot contain object datatype. dtype : dtype, optional The dtype of the output unstructured array. copy : bool, optional If true, always return a copy. If false, a view is returned if possible, such as when the `dtype` and strides of the fields are suitable and the array subtype is one of `np.ndarray`, `np.recarray` or `np.memmap`. .. versionchanged:: 1.25.0 A view can now be returned if the fields are separated by a uniform stride. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional See casting argument of `numpy.ndarray.astype`. Controls what kind of data casting may occur. Returns ------- unstructured : ndarray Unstructured array with one more dimension. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> a = np.zeros(4, dtype=[('a', 'i4'), ('b', 'f4,u2'), ('c', 'f4', 2)]) >>> a array([(0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.])], dtype=[('a', '<i4'), ('b', [('f0', '<f4'), ('f1', '<u2')]), ('c', '<f4', (2,))]) >>> rfn.structured_to_unstructured(a) array([[0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.], [0., 0., 0., 0., 0.]]) >>> b = np.array([(1, 2, 5), (4, 5, 7), (7, 8 ,11), (10, 11, 12)], ... dtype=[('x', 'i4'), ('y', 'f4'), ('z', 'f8')]) >>> np.mean(rfn.structured_to_unstructured(b[['x', 'z']]), axis=-1) array([ 3. , 5.5, 9. , 11. ]) """ if arr.dtype.names is None: raise ValueError('arr must be a structured array') fields = _get_fields_and_offsets(arr.dtype) n_fields = len(fields) if n_fields == 0 and dtype is None: raise ValueError("arr has no fields. Unable to guess dtype") elif n_fields == 0: # too many bugs elsewhere for this to work now raise NotImplementedError("arr with no fields is not supported") dts, counts, offsets = zip(fields) names = ['f{}'.format(n) for n in range(n_fields)] if dtype is None: out_dtype = np.result_type([dt.base for dt in dts]) else: out_dtype = np.dtype(dtype) # Use a series of views and casts to convert to an unstructured array: # first view using flattened fields (doesn't work for object arrays) # Note: dts may include a shape for subarrays flattened_fields = np.dtype({'names': names, 'formats': dts, 'offsets': offsets, 'itemsize': arr.dtype.itemsize}) arr = arr.view(flattened_fields) # we only allow a few types to be unstructured by manipulating the # strides, because we know it won't work with, for example, np.matrix nor # np.ma.MaskedArray. can_view = type(arr) in (np.ndarray, np.recarray, np.memmap) if (not copy) and can_view and all(dt.base == out_dtype for dt in dts): # all elements have the right dtype already; if they have a common # stride, we can just return a view common_stride = _common_stride(offsets, counts, out_dtype.itemsize) if common_stride is not None: wrap = arr.__array_wrap__ new_shape = arr.shape + (sum(counts), out_dtype.itemsize) new_strides = arr.strides + (abs(common_stride), 1) arr = arr[..., np.newaxis].view(np.uint8) # view as bytes arr = arr[..., min(offsets):] # remove the leading unused data arr = np.lib.stride_tricks.as_strided(arr, new_shape, new_strides, subok=True) # cast and drop the last dimension again arr = arr.view(out_dtype)[..., 0] if common_stride < 0: arr = arr[..., ::-1] # reverse, if the stride was negative if type(arr) is not type(wrap.__self__): # Some types (e.g. recarray) turn into an ndarray along the # way, so we have to wrap it again in order to match the # behavior with copy=True. arr = wrap(arr) return arr # next cast to a packed format with all fields converted to new dtype packed_fields = np.dtype({'names': names, 'formats': [(out_dtype, dt.shape) for dt in dts]}) arr = arr.astype(packed_fields, copy=copy, casting=casting) # finally is it safe to view the packed fields as the unstructured type return arr.view((out_dtype, (sum(counts),))) def _unstructured_to_structured_dispatcher(arr, dtype=None, names=None, align=None, copy=None, casting=None): return (arr,) @array_function_dispatch(_unstructured_to_structured_dispatcher) def unstructured_to_structured(arr, dtype=None, names=None, align=False, copy=False, casting='unsafe'): """ Converts an n-D unstructured array into an (n-1)-D structured array. The last dimension of the input array is converted into a structure, with number of field-elements equal to the size of the last dimension of the input array. By default all output fields have the input array's dtype, but an output structured dtype with an equal number of fields-elements can be supplied instead. Nested fields, as well as each element of any subarray fields, all count towards the number of field-elements. Parameters ---------- arr : ndarray Unstructured array or dtype to convert. dtype : dtype, optional The structured dtype of the output array names : list of strings, optional If dtype is not supplied, this specifies the field names for the output dtype, in order. The field dtypes will be the same as the input array. align : boolean, optional Whether to create an aligned memory layout. copy : bool, optional See copy argument to `numpy.ndarray.astype`. If true, always return a copy. If false, and `dtype` requirements are satisfied, a view is returned. casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional See casting argument of `numpy.ndarray.astype`. Controls what kind of data casting may occur. Returns ------- structured : ndarray Structured array with fewer dimensions. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> dt = np.dtype([('a', 'i4'), ('b', 'f4,u2'), ('c', 'f4', 2)]) >>> a = np.arange(20).reshape((4,5)) >>> a array([[ 0, 1, 2, 3, 4], [ 5, 6, 7, 8, 9], [10, 11, 12, 13, 14], [15, 16, 17, 18, 19]]) >>> rfn.unstructured_to_structured(a, dt) array([( 0, ( 1., 2), [ 3., 4.]), ( 5, ( 6., 7), [ 8., 9.]), (10, (11., 12), [13., 14.]), (15, (16., 17), [18., 19.])], dtype=[('a', '<i4'), ('b', [('f0', '<f4'), ('f1', '<u2')]), ('c', '<f4', (2,))]) """ if arr.shape == (): raise ValueError('arr must have at least one dimension') n_elem = arr.shape[-1] if n_elem == 0: # too many bugs elsewhere for this to work now raise NotImplementedError("last axis with size 0 is not supported") if dtype is None: if names is None: names = ['f{}'.format(n) for n in range(n_elem)] out_dtype = np.dtype([(n, arr.dtype) for n in names], align=align) fields = _get_fields_and_offsets(out_dtype) dts, counts, offsets = zip(fields) else: if names is not None: raise ValueError("don't supply both dtype and names") # if dtype is the args of np.dtype, construct it dtype = np.dtype(dtype) # sanity check of the input dtype fields = _get_fields_and_offsets(dtype) if len(fields) == 0: dts, counts, offsets = [], [], [] else: dts, counts, offsets = zip(fields) if n_elem != sum(counts): raise ValueError('The length of the last dimension of arr must ' 'be equal to the number of fields in dtype') out_dtype = dtype if align and not out_dtype.isalignedstruct: raise ValueError("align was True but dtype is not aligned") names = ['f{}'.format(n) for n in range(len(fields))] # Use a series of views and casts to convert to a structured array: # first view as a packed structured array of one dtype packed_fields = np.dtype({'names': names, 'formats': [(arr.dtype, dt.shape) for dt in dts]}) arr = np.ascontiguousarray(arr).view(packed_fields) # next cast to an unpacked but flattened format with varied dtypes flattened_fields = np.dtype({'names': names, 'formats': dts, 'offsets': offsets, 'itemsize': out_dtype.itemsize}) arr = arr.astype(flattened_fields, copy=copy, casting=casting) # finally view as the final nested dtype and remove the last axis return arr.view(out_dtype)[..., 0] def _apply_along_fields_dispatcher(func, arr): return (arr,) @array_function_dispatch(_apply_along_fields_dispatcher) def apply_along_fields(func, arr): """ Apply function 'func' as a reduction across fields of a structured array. This is similar to `apply_along_axis`, but treats the fields of a structured array as an extra axis. The fields are all first cast to a common type following the type-promotion rules from `numpy.result_type` applied to the field's dtypes. Parameters ---------- func : function Function to apply on the "field" dimension. This function must support an `axis` argument, like np.mean, np.sum, etc. arr : ndarray Structured array for which to apply func. Returns ------- out : ndarray Result of the recution operation Examples -------- >>> from numpy.lib import recfunctions as rfn >>> b = np.array([(1, 2, 5), (4, 5, 7), (7, 8 ,11), (10, 11, 12)], ... dtype=[('x', 'i4'), ('y', 'f4'), ('z', 'f8')]) >>> rfn.apply_along_fields(np.mean, b) array([ 2.66666667, 5.33333333, 8.66666667, 11. ]) >>> rfn.apply_along_fields(np.mean, b[['x', 'z']]) array([ 3. , 5.5, 9. , 11. ]) """ if arr.dtype.names is None: raise ValueError('arr must be a structured array') uarr = structured_to_unstructured(arr) return func(uarr, axis=-1) # works and avoids axis requirement, but very, very slow: #return np.apply_along_axis(func, -1, uarr) def _assign_fields_by_name_dispatcher(dst, src, zero_unassigned=None): return dst, src @array_function_dispatch(_assign_fields_by_name_dispatcher) def assign_fields_by_name(dst, src, zero_unassigned=True): """ Assigns values from one structured array to another by field name. Normally in numpy >= 1.14, assignment of one structured array to another copies fields "by position", meaning that the first field from the src is copied to the first field of the dst, and so on, regardless of field name. This function instead copies "by field name", such that fields in the dst are assigned from the identically named field in the src. This applies recursively for nested structures. This is how structure assignment worked in numpy >= 1.6 to <= 1.13. Parameters ---------- dst : ndarray src : ndarray The source and destination arrays during assignment. zero_unassigned : bool, optional If True, fields in the dst for which there was no matching field in the src are filled with the value 0 (zero). This was the behavior of numpy <= 1.13. If False, those fields are not modified. """ if dst.dtype.names is None: dst[...] = src return for name in dst.dtype.names: if name not in src.dtype.names: if zero_unassigned: dst[name] = 0 else: assign_fields_by_name(dst[name], src[name], zero_unassigned) def _require_fields_dispatcher(array, required_dtype): return (array,) @array_function_dispatch(_require_fields_dispatcher) def require_fields(array, required_dtype): """ Casts a structured array to a new dtype using assignment by field-name. This function assigns from the old to the new array by name, so the value of a field in the output array is the value of the field with the same name in the source array. This has the effect of creating a new ndarray containing only the fields "required" by the required_dtype. If a field name in the required_dtype does not exist in the input array, that field is created and set to 0 in the output array. Parameters ---------- a : ndarray array to cast required_dtype : dtype datatype for output array Returns ------- out : ndarray array with the new dtype, with field values copied from the fields in the input array with the same name Examples -------- >>> from numpy.lib import recfunctions as rfn >>> a = np.ones(4, dtype=[('a', 'i4'), ('b', 'f8'), ('c', 'u1')]) >>> rfn.require_fields(a, [('b', 'f4'), ('c', 'u1')]) array([(1., 1), (1., 1), (1., 1), (1., 1)], dtype=[('b', '<f4'), ('c', 'u1')]) >>> rfn.require_fields(a, [('b', 'f4'), ('newf', 'u1')]) array([(1., 0), (1., 0), (1., 0), (1., 0)], dtype=[('b', '<f4'), ('newf', 'u1')]) """ out = np.empty(array.shape, dtype=required_dtype) assign_fields_by_name(out, array) return out def _stack_arrays_dispatcher(arrays, defaults=None, usemask=None, asrecarray=None, autoconvert=None): return arrays @array_function_dispatch(_stack_arrays_dispatcher) def stack_arrays(arrays, defaults=None, usemask=True, asrecarray=False, autoconvert=False): """ Superposes arrays fields by fields Parameters ---------- arrays : array or sequence Sequence of input arrays. defaults : dictionary, optional Dictionary mapping field names to the corresponding default values. usemask : {True, False}, optional Whether to return a MaskedArray (or MaskedRecords is `asrecarray==True`) or a ndarray. asrecarray : {False, True}, optional Whether to return a recarray (or MaskedRecords if `usemask==True`) or just a flexible-type ndarray. autoconvert : {False, True}, optional Whether automatically cast the type of the field to the maximum. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> x = np.array([1, 2,]) >>> rfn.stack_arrays(x) is x True >>> z = np.array([('A', 1), ('B', 2)], dtype=[('A', '\|S3'), ('B', float)]) >>> zz = np.array([('a', 10., 100.), ('b', 20., 200.), ('c', 30., 300.)], ... dtype=[('A', '\|S3'), ('B', np.double), ('C', np.double)]) >>> test = rfn.stack_arrays((z,zz)) >>> test masked_array(data=[(b'A', 1.0, --), (b'B', 2.0, --), (b'a', 10.0, 100.0), (b'b', 20.0, 200.0), (b'c', 30.0, 300.0)], mask=[(False, False, True), (False, False, True), (False, False, False), (False, False, False), (False, False, False)], fill_value=(b'N/A', 1.e+20, 1.e+20), dtype=[('A', 'S3'), ('B', '<f8'), ('C', '<f8')]) """ if isinstance(arrays, ndarray): return arrays elif len(arrays) == 1: return arrays[0] seqarrays = [np.asanyarray(a).ravel() for a in arrays] nrecords = [len(a) for a in seqarrays] ndtype = [a.dtype for a in seqarrays] fldnames = [d.names for d in ndtype] # dtype_l = ndtype[0] newdescr = _get_fieldspec(dtype_l) names = [n for n, d in newdescr] for dtype_n in ndtype[1:]: for fname, fdtype in _get_fieldspec(dtype_n): if fname not in names: newdescr.append((fname, fdtype)) names.append(fname) else: nameidx = names.index(fname) _, cdtype = newdescr[nameidx] if autoconvert: newdescr[nameidx] = (fname, max(fdtype, cdtype)) elif fdtype != cdtype: raise TypeError("Incompatible type '%s' <> '%s'" % (cdtype, fdtype)) # Only one field: use concatenate if len(newdescr) == 1: output = ma.concatenate(seqarrays) else: # output = ma.masked_all((np.sum(nrecords),), newdescr) offset = np.cumsum(np.r_[0, nrecords]) seen = [] for (a, n, i, j) in zip(seqarrays, fldnames, offset[:-1], offset[1:]): names = a.dtype.names if names is None: output['f%i' % len(seen)][i:j] = a else: for name in n: output[name][i:j] = a[name] if name not in seen: seen.append(name) # return _fix_output(_fix_defaults(output, defaults), usemask=usemask, asrecarray=asrecarray) def _find_duplicates_dispatcher( a, key=None, ignoremask=None, return_index=None): return (a,) @array_function_dispatch(_find_duplicates_dispatcher) def find_duplicates(a, key=None, ignoremask=True, return_index=False): """ Find the duplicates in a structured array along a given key Parameters ---------- a : array-like Input array key : {string, None}, optional Name of the fields along which to check the duplicates. If None, the search is performed by records ignoremask : {True, False}, optional Whether masked data should be discarded or considered as duplicates. return_index : {False, True}, optional Whether to return the indices of the duplicated values. Examples -------- >>> from numpy.lib import recfunctions as rfn >>> ndtype = [('a', int)] >>> a = np.ma.array([1, 1, 1, 2, 2, 3, 3], ... mask=[0, 0, 1, 0, 0, 0, 1]).view(ndtype) >>> rfn.find_duplicates(a, ignoremask=True, return_index=True) (masked_array(data=[(1,), (1,), (2,), (2,)], mask=[(False,), (False,), (False,), (False,)], fill_value=(999999,), dtype=[('a', '<i8')]), array([0, 1, 3, 4])) """ a = np.asanyarray(a).ravel() # Get a dictionary of fields fields = get_fieldstructure(a.dtype) # Get the sorting data (by selecting the corresponding field) base = a if key: for f in fields[key]: base = base[f] base = base[key] # Get the sorting indices and the sorted data sortidx = base.argsort() sortedbase = base[sortidx] sorteddata = sortedbase.filled() # Compare the sorting data flag = (sorteddata[:-1] == sorteddata[1:]) # If masked data must be ignored, set the flag to false where needed if ignoremask: sortedmask = sortedbase.recordmask flag[sortedmask[1:]] = False flag = np.concatenate(([False], flag)) # We need to take the point on the left as well (else we're missing it) flag[:-1] = flag[:-1] + flag[1:] duplicates = a[sortidx][flag] if return_index: return (duplicates, sortidx[flag]) else: return duplicates def _join_by_dispatcher( key, r1, r2, jointype=None, r1postfix=None, r2postfix=None, defaults=None, usemask=None, asrecarray=None): return (r1, r2) @array_function_dispatch(_join_by_dispatcher) def join_by(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2', defaults=None, usemask=True, asrecarray=False): """ Join arrays `r1` and `r2` on key `key`. The key should be either a string or a sequence of string corresponding to the fields used to join the array. An exception is raised if the `key` field cannot be found in the two input arrays. Neither `r1` nor `r2` should have any duplicates along `key`: the presence of duplicates will make the output quite unreliable. Note that duplicates are not looked for by the algorithm. Parameters ---------- key : {string, sequence} A string or a sequence of strings corresponding to the fields used for comparison. r1, r2 : arrays Structured arrays. jointype : {'inner', 'outer', 'leftouter'}, optional If 'inner', returns the elements common to both r1 and r2. If 'outer', returns the common elements as well as the elements of r1 not in r2 and the elements of not in r2. If 'leftouter', returns the common elements and the elements of r1 not in r2. r1postfix : string, optional String appended to the names of the fields of r1 that are present in r2 but absent of the key. r2postfix : string, optional String appended to the names of the fields of r2 that are present in r1 but absent of the key. defaults : {dictionary}, optional Dictionary mapping field names to the corresponding default values. usemask : {True, False}, optional Whether to return a MaskedArray (or MaskedRecords is `asrecarray==True`) or a ndarray. asrecarray : {False, True}, optional Whether to return a recarray (or MaskedRecords if `usemask==True`) or just a flexible-type ndarray. Notes ----- * The output is sorted along the key. * A temporary array is formed by dropping the fields not in the key for the two arrays and concatenating the result. This array is then sorted, and the common entries selected. The output is constructed by filling the fields with the selected entries. Matching is not preserved if there are some duplicates... """ # Check jointype if jointype not in ('inner', 'outer', 'leftouter'): raise ValueError( "The 'jointype' argument should be in 'inner', " "'outer' or 'leftouter' (got '%s' instead)" % jointype ) # If we have a single key, put it in a tuple if isinstance(key, str): key = (key,) # Check the keys if len(set(key)) != len(key): dup = next(x for n,x in enumerate(key) if x in key[n+1:]) raise ValueError("duplicate join key %r" % dup) for name in key: if name not in r1.dtype.names: raise ValueError('r1 does not have key field %r' % name) if name not in r2.dtype.names: raise ValueError('r2 does not have key field %r' % name) # Make sure we work with ravelled arrays r1 = r1.ravel() r2 = r2.ravel() # Fixme: nb2 below is never used. Commenting out for pyflakes. # (nb1, nb2) = (len(r1), len(r2)) nb1 = len(r1) (r1names, r2names) = (r1.dtype.names, r2.dtype.names) # Check the names for collision collisions = (set(r1names) & set(r2names)) - set(key) if collisions and not (r1postfix or r2postfix): msg = "r1 and r2 contain common names, r1postfix and r2postfix " msg += "can't both be empty" raise ValueError(msg) # Make temporary arrays of just the keys # (use order of keys in `r1` for back-compatibility) key1 = [ n for n in r1names if n in key ] r1k = _keep_fields(r1, key1) r2k = _keep_fields(r2, key1) # Concatenate the two arrays for comparison aux = ma.concatenate((r1k, r2k)) idx_sort = aux.argsort(order=key) aux = aux[idx_sort] # # Get the common keys flag_in = ma.concatenate(([False], aux[1:] == aux[:-1])) flag_in[:-1] = flag_in[1:] + flag_in[:-1] idx_in = idx_sort[flag_in] idx_1 = idx_in[(idx_in < nb1)] idx_2 = idx_in[(idx_in >= nb1)] - nb1 (r1cmn, r2cmn) = (len(idx_1), len(idx_2)) if jointype == 'inner': (r1spc, r2spc) = (0, 0) elif jointype == 'outer': idx_out = idx_sort[~flag_in] idx_1 = np.concatenate((idx_1, idx_out[(idx_out < nb1)])) idx_2 = np.concatenate((idx_2, idx_out[(idx_out >= nb1)] - nb1)) (r1spc, r2spc) = (len(idx_1) - r1cmn, len(idx_2) - r2cmn) elif jointype == 'leftouter': idx_out = idx_sort[~flag_in] idx_1 = np.concatenate((idx_1, idx_out[(idx_out < nb1)])) (r1spc, r2spc) = (len(idx_1) - r1cmn, 0) # Select the entries from each input (s1, s2) = (r1[idx_1], r2[idx_2]) # # Build the new description of the output array ....... # Start with the key fields ndtype = _get_fieldspec(r1k.dtype) # Add the fields from r1 for fname, fdtype in _get_fieldspec(r1.dtype): if fname not in key: ndtype.append((fname, fdtype)) # Add the fields from r2 for fname, fdtype in _get_fieldspec(r2.dtype): # Have we seen the current name already ? # we need to rebuild this list every time names = list(name for name, dtype in ndtype) try: nameidx = names.index(fname) except ValueError: #... we haven't: just add the description to the current list ndtype.append((fname, fdtype)) else: # collision _, cdtype = ndtype[nameidx] if fname in key: # The current field is part of the key: take the largest dtype ndtype[nameidx] = (fname, max(fdtype, cdtype)) else: # The current field is not part of the key: add the suffixes, # and place the new field adjacent to the old one ndtype[nameidx:nameidx + 1] = [ (fname + r1postfix, cdtype), (fname + r2postfix, fdtype) ] # Rebuild a dtype from the new fields ndtype = np.dtype(ndtype) # Find the largest nb of common fields : # r1cmn and r2cmn should be equal, but... cmn = max(r1cmn, r2cmn) # Construct an empty array output = ma.masked_all((cmn + r1spc + r2spc,), dtype=ndtype) names = output.dtype.names for f in r1names: selected = s1[f] if f not in names or (f in r2names and not r2postfix and f not in key): f += r1postfix current = output[f] current[:r1cmn] = selected[:r1cmn] if jointype in ('outer', 'leftouter'): current[cmn:cmn + r1spc] = selected[r1cmn:] for f in r2names: selected = s2[f] if f not in names or (f in r1names and not r1postfix and f not in key): f += r2postfix current = output[f] current[:r2cmn] = selected[:r2cmn] if (jointype == 'outer') and r2spc: current[-r2spc:] = selected[r2cmn:] # Sort and finalize the output output.sort(order=key) kwargs = dict(usemask=usemask, asrecarray=asrecarray) return _fix_output(_fix_defaults(output, defaults), kwargs) def _rec_join_dispatcher( key, r1, r2, jointype=None, r1postfix=None, r2postfix=None, defaults=None): return (r1, r2) @array_function_dispatch(_rec_join_dispatcher) def rec_join(key, r1, r2, jointype='inner', r1postfix='1', r2postfix='2', defaults=None): """ Join arrays `r1` and `r2` on keys. Alternative to join_by, that always returns a np.recarray. See Also -------- join_by : equivalent function """ kwargs = dict(jointype=jointype, r1postfix=r1postfix, r2postfix=r2postfix, defaults=defaults, usemask=False, asrecarray=True) return join_by(key, r1, r2, kwargs)	58.03 KB	2026-01-20 12:58
📄 scimath.py """ Wrapper functions to more user-friendly calling of certain math functions whose output data-type is different than the input data-type in certain domains of the input. For example, for functions like `log` with branch cuts, the versions in this module provide the mathematically valid answers in the complex plane:: >>> import math >>> np.emath.log(-math.exp(1)) == (1+1jmath.pi) True Similarly, `sqrt`, other base logarithms, `power` and trig functions are correctly handled. See their respective docstrings for specific examples. Functions --------- .. autosummary:: :toctree: generated/ sqrt log log2 logn log10 power arccos arcsin arctanh """ import numpy.core.numeric as nx import numpy.core.numerictypes as nt from numpy.core.numeric import asarray, any from numpy.core.overrides import array_function_dispatch from numpy.lib.type_check import isreal __all__ = [ 'sqrt', 'log', 'log2', 'logn', 'log10', 'power', 'arccos', 'arcsin', 'arctanh' ] _ln2 = nx.log(2.0) def _tocomplex(arr): """Convert its input `arr` to a complex array. The input is returned as a complex array of the smallest type that will fit the original data: types like single, byte, short, etc. become csingle, while others become cdouble. A copy of the input is always made. Parameters ---------- arr : array Returns ------- array An array with the same input data as the input but in complex form. Examples -------- First, consider an input of type short: >>> a = np.array([1,2,3],np.short) >>> ac = np.lib.scimath._tocomplex(a); ac array([1.+0.j, 2.+0.j, 3.+0.j], dtype=complex64) >>> ac.dtype dtype('complex64') If the input is of type double, the output is correspondingly of the complex double type as well: >>> b = np.array([1,2,3],np.double) >>> bc = np.lib.scimath._tocomplex(b); bc array([1.+0.j, 2.+0.j, 3.+0.j]) >>> bc.dtype dtype('complex128') Note that even if the input was complex to begin with, a copy is still made, since the astype() method always copies: >>> c = np.array([1,2,3],np.csingle) >>> cc = np.lib.scimath._tocomplex(c); cc array([1.+0.j, 2.+0.j, 3.+0.j], dtype=complex64) >>> c = 2; c array([2.+0.j, 4.+0.j, 6.+0.j], dtype=complex64) >>> cc array([1.+0.j, 2.+0.j, 3.+0.j], dtype=complex64) """ if issubclass(arr.dtype.type, (nt.single, nt.byte, nt.short, nt.ubyte, nt.ushort, nt.csingle)): return arr.astype(nt.csingle) else: return arr.astype(nt.cdouble) def _fix_real_lt_zero(x): """Convert `x` to complex if it has real, negative components. Otherwise, output is just the array version of the input (via asarray). Parameters ---------- x : array_like Returns ------- array Examples -------- >>> np.lib.scimath._fix_real_lt_zero([1,2]) array([1, 2]) >>> np.lib.scimath._fix_real_lt_zero([-1,2]) array([-1.+0.j, 2.+0.j]) """ x = asarray(x) if any(isreal(x) & (x < 0)): x = _tocomplex(x) return x def _fix_int_lt_zero(x): """Convert `x` to double if it has real, negative components. Otherwise, output is just the array version of the input (via asarray). Parameters ---------- x : array_like Returns ------- array Examples -------- >>> np.lib.scimath._fix_int_lt_zero([1,2]) array([1, 2]) >>> np.lib.scimath._fix_int_lt_zero([-1,2]) array([-1., 2.]) """ x = asarray(x) if any(isreal(x) & (x < 0)): x = x * 1.0 return x def _fix_real_abs_gt_1(x): """Convert `x` to complex if it has real components x_i with abs(x_i)>1. Otherwise, output is just the array version of the input (via asarray). Parameters ---------- x : array_like Returns ------- array Examples -------- >>> np.lib.scimath._fix_real_abs_gt_1([0,1]) array([0, 1]) >>> np.lib.scimath._fix_real_abs_gt_1([0,2]) array([0.+0.j, 2.+0.j]) """ x = asarray(x) if any(isreal(x) & (abs(x) > 1)): x = _tocomplex(x) return x def _unary_dispatcher(x): return (x,) @array_function_dispatch(_unary_dispatcher) def sqrt(x): """ Compute the square root of x. For negative input elements, a complex value is returned (unlike `numpy.sqrt` which returns NaN). Parameters ---------- x : array_like The input value(s). Returns ------- out : ndarray or scalar The square root of `x`. If `x` was a scalar, so is `out`, otherwise an array is returned. See Also -------- numpy.sqrt Examples -------- For real, non-negative inputs this works just like `numpy.sqrt`: >>> np.emath.sqrt(1) 1.0 >>> np.emath.sqrt([1, 4]) array([1., 2.]) But it automatically handles negative inputs: >>> np.emath.sqrt(-1) 1j >>> np.emath.sqrt([-1,4]) array([0.+1.j, 2.+0.j]) Different results are expected because: floating point 0.0 and -0.0 are distinct. For more control, explicitly use complex() as follows: >>> np.emath.sqrt(complex(-4.0, 0.0)) 2j >>> np.emath.sqrt(complex(-4.0, -0.0)) -2j """ x = _fix_real_lt_zero(x) return nx.sqrt(x) @array_function_dispatch(_unary_dispatcher) def log(x): """ Compute the natural logarithm of `x`. Return the "principal value" (for a description of this, see `numpy.log`) of :math:`log_e(x)`. For real `x > 0`, this is a real number (``log(0)`` returns ``-inf`` and ``log(np.inf)`` returns ``inf``). Otherwise, the complex principle value is returned. Parameters ---------- x : array_like The value(s) whose log is (are) required. Returns ------- out : ndarray or scalar The log of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array is returned. See Also -------- numpy.log Notes ----- For a log() that returns ``NAN`` when real `x < 0`, use `numpy.log` (note, however, that otherwise `numpy.log` and this `log` are identical, i.e., both return ``-inf`` for `x = 0`, ``inf`` for `x = inf`, and, notably, the complex principle value if ``x.imag != 0``). Examples -------- >>> np.emath.log(np.exp(1)) 1.0 Negative arguments are handled "correctly" (recall that ``exp(log(x)) == x`` does not hold for real ``x < 0``): >>> np.emath.log(-np.exp(1)) == (1 + np.pi * 1j) True """ x = _fix_real_lt_zero(x) return nx.log(x) @array_function_dispatch(_unary_dispatcher) def log10(x): """ Compute the logarithm base 10 of `x`. Return the "principal value" (for a description of this, see `numpy.log10`) of :math:`log_{10}(x)`. For real `x > 0`, this is a real number (``log10(0)`` returns ``-inf`` and ``log10(np.inf)`` returns ``inf``). Otherwise, the complex principle value is returned. Parameters ---------- x : array_like or scalar The value(s) whose log base 10 is (are) required. Returns ------- out : ndarray or scalar The log base 10 of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array object is returned. See Also -------- numpy.log10 Notes ----- For a log10() that returns ``NAN`` when real `x < 0`, use `numpy.log10` (note, however, that otherwise `numpy.log10` and this `log10` are identical, i.e., both return ``-inf`` for `x = 0`, ``inf`` for `x = inf`, and, notably, the complex principle value if ``x.imag != 0``). Examples -------- (We set the printing precision so the example can be auto-tested) >>> np.set_printoptions(precision=4) >>> np.emath.log10(101) 1.0 >>> np.emath.log10([-101, -102, 102]) array([1.+1.3644j, 2.+1.3644j, 2.+0.j ]) """ x = _fix_real_lt_zero(x) return nx.log10(x) def _logn_dispatcher(n, x): return (n, x,) @array_function_dispatch(_logn_dispatcher) def logn(n, x): """ Take log base n of x. If `x` contains negative inputs, the answer is computed and returned in the complex domain. Parameters ---------- n : array_like The integer base(s) in which the log is taken. x : array_like The value(s) whose log base `n` is (are) required. Returns ------- out : ndarray or scalar The log base `n` of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array is returned. Examples -------- >>> np.set_printoptions(precision=4) >>> np.emath.logn(2, [4, 8]) array([2., 3.]) >>> np.emath.logn(2, [-4, -8, 8]) array([2.+4.5324j, 3.+4.5324j, 3.+0.j ]) """ x = _fix_real_lt_zero(x) n = _fix_real_lt_zero(n) return nx.log(x)/nx.log(n) @array_function_dispatch(_unary_dispatcher) def log2(x): """ Compute the logarithm base 2 of `x`. Return the "principal value" (for a description of this, see `numpy.log2`) of :math:`log_2(x)`. For real `x > 0`, this is a real number (``log2(0)`` returns ``-inf`` and ``log2(np.inf)`` returns ``inf``). Otherwise, the complex principle value is returned. Parameters ---------- x : array_like The value(s) whose log base 2 is (are) required. Returns ------- out : ndarray or scalar The log base 2 of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array is returned. See Also -------- numpy.log2 Notes ----- For a log2() that returns ``NAN`` when real `x < 0`, use `numpy.log2` (note, however, that otherwise `numpy.log2` and this `log2` are identical, i.e., both return ``-inf`` for `x = 0`, ``inf`` for `x = inf`, and, notably, the complex principle value if ``x.imag != 0``). Examples -------- We set the printing precision so the example can be auto-tested: >>> np.set_printoptions(precision=4) >>> np.emath.log2(8) 3.0 >>> np.emath.log2([-4, -8, 8]) array([2.+4.5324j, 3.+4.5324j, 3.+0.j ]) """ x = _fix_real_lt_zero(x) return nx.log2(x) def _power_dispatcher(x, p): return (x, p) @array_function_dispatch(_power_dispatcher) def power(x, p): """ Return x to the power p, (xp). If `x` contains negative values, the output is converted to the complex domain. Parameters ---------- x : array_like The input value(s). p : array_like of ints The power(s) to which `x` is raised. If `x` contains multiple values, `p` has to either be a scalar, or contain the same number of values as `x`. In the latter case, the result is ``x[0]p[0], x[1]p[1], ...``. Returns ------- out : ndarray or scalar The result of ``xp``. If `x` and `p` are scalars, so is `out`, otherwise an array is returned. See Also -------- numpy.power Examples -------- >>> np.set_printoptions(precision=4) >>> np.emath.power([2, 4], 2) array([ 4, 16]) >>> np.emath.power([2, 4], -2) array([0.25 , 0.0625]) >>> np.emath.power([-2, 4], 2) array([ 4.-0.j, 16.+0.j]) """ x = _fix_real_lt_zero(x) p = _fix_int_lt_zero(p) return nx.power(x, p) @array_function_dispatch(_unary_dispatcher) def arccos(x): """ Compute the inverse cosine of x. Return the "principal value" (for a description of this, see `numpy.arccos`) of the inverse cosine of `x`. For real `x` such that `abs(x) <= 1`, this is a real number in the closed interval :math:`[0, \\pi]`. Otherwise, the complex principle value is returned. Parameters ---------- x : array_like or scalar The value(s) whose arccos is (are) required. Returns ------- out : ndarray or scalar The inverse cosine(s) of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array object is returned. See Also -------- numpy.arccos Notes ----- For an arccos() that returns ``NAN`` when real `x` is not in the interval ``[-1,1]``, use `numpy.arccos`. Examples -------- >>> np.set_printoptions(precision=4) >>> np.emath.arccos(1) # a scalar is returned 0.0 >>> np.emath.arccos([1,2]) array([0.-0.j , 0.-1.317j]) """ x = _fix_real_abs_gt_1(x) return nx.arccos(x) @array_function_dispatch(_unary_dispatcher) def arcsin(x): """ Compute the inverse sine of x. Return the "principal value" (for a description of this, see `numpy.arcsin`) of the inverse sine of `x`. For real `x` such that `abs(x) <= 1`, this is a real number in the closed interval :math:`[-\\pi/2, \\pi/2]`. Otherwise, the complex principle value is returned. Parameters ---------- x : array_like or scalar The value(s) whose arcsin is (are) required. Returns ------- out : ndarray or scalar The inverse sine(s) of the `x` value(s). If `x` was a scalar, so is `out`, otherwise an array object is returned. See Also -------- numpy.arcsin Notes ----- For an arcsin() that returns ``NAN`` when real `x` is not in the interval ``[-1,1]``, use `numpy.arcsin`. Examples -------- >>> np.set_printoptions(precision=4) >>> np.emath.arcsin(0) 0.0 >>> np.emath.arcsin([0,1]) array([0. , 1.5708]) """ x = _fix_real_abs_gt_1(x) return nx.arcsin(x) @array_function_dispatch(_unary_dispatcher) def arctanh(x): """ Compute the inverse hyperbolic tangent of `x`. Return the "principal value" (for a description of this, see `numpy.arctanh`) of ``arctanh(x)``. For real `x` such that ``abs(x) < 1``, this is a real number. If `abs(x) > 1`, or if `x` is complex, the result is complex. Finally, `x = 1` returns``inf`` and ``x=-1`` returns ``-inf``. Parameters ---------- x : array_like The value(s) whose arctanh is (are) required. Returns ------- out : ndarray or scalar The inverse hyperbolic tangent(s) of the `x` value(s). If `x` was a scalar so is `out`, otherwise an array is returned. See Also -------- numpy.arctanh Notes ----- For an arctanh() that returns ``NAN`` when real `x` is not in the interval ``(-1,1)``, use `numpy.arctanh` (this latter, however, does return +/-inf for ``x = +/-1``). Examples -------- >>> np.set_printoptions(precision=4) >>> from numpy.testing import suppress_warnings >>> with suppress_warnings() as sup: ... sup.filter(RuntimeWarning) ... np.emath.arctanh(np.eye(2)) array([[inf, 0.], [ 0., inf]]) >>> np.emath.arctanh([1j]) array([0.+0.7854j]) """ x = _fix_real_abs_gt_1(x) return nx.arctanh(x)	14.68 KB	2026-01-20 12:58
📄 scimath.pyi from typing import overload, Any from numpy import complexfloating from numpy._typing import ( NDArray, _ArrayLikeFloat_co, _ArrayLikeComplex_co, _ComplexLike_co, _FloatLike_co, ) __all__: list[str] @overload def sqrt(x: _FloatLike_co) -> Any: ... @overload def sqrt(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def sqrt(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def sqrt(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def log(x: _FloatLike_co) -> Any: ... @overload def log(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def log(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def log(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def log10(x: _FloatLike_co) -> Any: ... @overload def log10(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def log10(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def log10(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def log2(x: _FloatLike_co) -> Any: ... @overload def log2(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def log2(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def log2(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def logn(n: _FloatLike_co, x: _FloatLike_co) -> Any: ... @overload def logn(n: _ComplexLike_co, x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def logn(n: _ArrayLikeFloat_co, x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def logn(n: _ArrayLikeComplex_co, x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def power(x: _FloatLike_co, p: _FloatLike_co) -> Any: ... @overload def power(x: _ComplexLike_co, p: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def power(x: _ArrayLikeFloat_co, p: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def power(x: _ArrayLikeComplex_co, p: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def arccos(x: _FloatLike_co) -> Any: ... @overload def arccos(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def arccos(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def arccos(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def arcsin(x: _FloatLike_co) -> Any: ... @overload def arcsin(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def arcsin(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def arcsin(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def arctanh(x: _FloatLike_co) -> Any: ... @overload def arctanh(x: _ComplexLike_co) -> complexfloating[Any, Any]: ... @overload def arctanh(x: _ArrayLikeFloat_co) -> NDArray[Any]: ... @overload def arctanh(x: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ...	2.82 KB	2026-01-20 12:58
📄 setup.py def configuration(parent_package='',top_path=None): from numpy.distutils.misc_util import Configuration config = Configuration('lib', parent_package, top_path) config.add_subpackage('tests') config.add_data_dir('tests/data') config.add_data_files('*.pyi') return config if __name__ == '__main__': from numpy.distutils.core import setup setup(configuration=configuration)	405 B	2026-01-20 12:58
📄 shape_base.py import functools import numpy.core.numeric as _nx from numpy.core.numeric import asarray, zeros, array, asanyarray from numpy.core.fromnumeric import reshape, transpose from numpy.core.multiarray import normalize_axis_index from numpy.core import overrides from numpy.core import vstack, atleast_3d from numpy.core.numeric import normalize_axis_tuple from numpy.core.shape_base import _arrays_for_stack_dispatcher from numpy.lib.index_tricks import ndindex from numpy.matrixlib.defmatrix import matrix # this raises all the right alarm bells __all__ = [ 'column_stack', 'row_stack', 'dstack', 'array_split', 'split', 'hsplit', 'vsplit', 'dsplit', 'apply_over_axes', 'expand_dims', 'apply_along_axis', 'kron', 'tile', 'get_array_wrap', 'take_along_axis', 'put_along_axis' ] array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') def _make_along_axis_idx(arr_shape, indices, axis): # compute dimensions to iterate over if not _nx.issubdtype(indices.dtype, _nx.integer): raise IndexError('`indices` must be an integer array') if len(arr_shape) != indices.ndim: raise ValueError( "`indices` and `arr` must have the same number of dimensions") shape_ones = (1,) * indices.ndim dest_dims = list(range(axis)) + [None] + list(range(axis+1, indices.ndim)) # build a fancy index, consisting of orthogonal aranges, with the # requested index inserted at the right location fancy_index = [] for dim, n in zip(dest_dims, arr_shape): if dim is None: fancy_index.append(indices) else: ind_shape = shape_ones[:dim] + (-1,) + shape_ones[dim+1:] fancy_index.append(_nx.arange(n).reshape(ind_shape)) return tuple(fancy_index) def _take_along_axis_dispatcher(arr, indices, axis): return (arr, indices) @array_function_dispatch(_take_along_axis_dispatcher) def take_along_axis(arr, indices, axis): """ Take values from the input array by matching 1d index and data slices. This iterates over matching 1d slices oriented along the specified axis in the index and data arrays, and uses the former to look up values in the latter. These slices can be different lengths. Functions returning an index along an axis, like `argsort` and `argpartition`, produce suitable indices for this function. .. versionadded:: 1.15.0 Parameters ---------- arr : ndarray (Ni..., M, Nk...) Source array indices : ndarray (Ni..., J, Nk...) Indices to take along each 1d slice of `arr`. This must match the dimension of arr, but dimensions Ni and Nj only need to broadcast against `arr`. axis : int The axis to take 1d slices along. If axis is None, the input array is treated as if it had first been flattened to 1d, for consistency with `sort` and `argsort`. Returns ------- out: ndarray (Ni..., J, Nk...) The indexed result. Notes ----- This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii`` and ``kk`` to a tuple of indices:: Ni, M, Nk = a.shape[:axis], a.shape[axis], a.shape[axis+1:] J = indices.shape[axis] # Need not equal M out = np.empty(Ni + (J,) + Nk) for ii in ndindex(Ni): for kk in ndindex(Nk): a_1d = a [ii + s_[:,] + kk] indices_1d = indices[ii + s_[:,] + kk] out_1d = out [ii + s_[:,] + kk] for j in range(J): out_1d[j] = a_1d[indices_1d[j]] Equivalently, eliminating the inner loop, the last two lines would be:: out_1d[:] = a_1d[indices_1d] See Also -------- take : Take along an axis, using the same indices for every 1d slice put_along_axis : Put values into the destination array by matching 1d index and data slices Examples -------- For this sample array >>> a = np.array([[10, 30, 20], [60, 40, 50]]) We can sort either by using sort directly, or argsort and this function >>> np.sort(a, axis=1) array([[10, 20, 30], [40, 50, 60]]) >>> ai = np.argsort(a, axis=1) >>> ai array([[0, 2, 1], [1, 2, 0]]) >>> np.take_along_axis(a, ai, axis=1) array([[10, 20, 30], [40, 50, 60]]) The same works for max and min, if you maintain the trivial dimension with ``keepdims``: >>> np.max(a, axis=1, keepdims=True) array([[30], [60]]) >>> ai = np.argmax(a, axis=1, keepdims=True) >>> ai array([[1], [0]]) >>> np.take_along_axis(a, ai, axis=1) array([[30], [60]]) If we want to get the max and min at the same time, we can stack the indices first >>> ai_min = np.argmin(a, axis=1, keepdims=True) >>> ai_max = np.argmax(a, axis=1, keepdims=True) >>> ai = np.concatenate([ai_min, ai_max], axis=1) >>> ai array([[0, 1], [1, 0]]) >>> np.take_along_axis(a, ai, axis=1) array([[10, 30], [40, 60]]) """ # normalize inputs if axis is None: arr = arr.flat arr_shape = (len(arr),) # flatiter has no .shape axis = 0 else: axis = normalize_axis_index(axis, arr.ndim) arr_shape = arr.shape # use the fancy index return arr[_make_along_axis_idx(arr_shape, indices, axis)] def _put_along_axis_dispatcher(arr, indices, values, axis): return (arr, indices, values) @array_function_dispatch(_put_along_axis_dispatcher) def put_along_axis(arr, indices, values, axis): """ Put values into the destination array by matching 1d index and data slices. This iterates over matching 1d slices oriented along the specified axis in the index and data arrays, and uses the former to place values into the latter. These slices can be different lengths. Functions returning an index along an axis, like `argsort` and `argpartition`, produce suitable indices for this function. .. versionadded:: 1.15.0 Parameters ---------- arr : ndarray (Ni..., M, Nk...) Destination array. indices : ndarray (Ni..., J, Nk...) Indices to change along each 1d slice of `arr`. This must match the dimension of arr, but dimensions in Ni and Nj may be 1 to broadcast against `arr`. values : array_like (Ni..., J, Nk...) values to insert at those indices. Its shape and dimension are broadcast to match that of `indices`. axis : int The axis to take 1d slices along. If axis is None, the destination array is treated as if a flattened 1d view had been created of it. Notes ----- This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii`` and ``kk`` to a tuple of indices:: Ni, M, Nk = a.shape[:axis], a.shape[axis], a.shape[axis+1:] J = indices.shape[axis] # Need not equal M for ii in ndindex(Ni): for kk in ndindex(Nk): a_1d = a [ii + s_[:,] + kk] indices_1d = indices[ii + s_[:,] + kk] values_1d = values [ii + s_[:,] + kk] for j in range(J): a_1d[indices_1d[j]] = values_1d[j] Equivalently, eliminating the inner loop, the last two lines would be:: a_1d[indices_1d] = values_1d See Also -------- take_along_axis : Take values from the input array by matching 1d index and data slices Examples -------- For this sample array >>> a = np.array([[10, 30, 20], [60, 40, 50]]) We can replace the maximum values with: >>> ai = np.argmax(a, axis=1, keepdims=True) >>> ai array([[1], [0]]) >>> np.put_along_axis(a, ai, 99, axis=1) >>> a array([[10, 99, 20], [99, 40, 50]]) """ # normalize inputs if axis is None: arr = arr.flat axis = 0 arr_shape = (len(arr),) # flatiter has no .shape else: axis = normalize_axis_index(axis, arr.ndim) arr_shape = arr.shape # use the fancy index arr[_make_along_axis_idx(arr_shape, indices, axis)] = values def _apply_along_axis_dispatcher(func1d, axis, arr, args, kwargs): return (arr,) @array_function_dispatch(_apply_along_axis_dispatcher) def apply_along_axis(func1d, axis, arr, args, *kwargs): """ Apply a function to 1-D slices along the given axis. Execute `func1d(a, args, *kwargs)` where `func1d` operates on 1-D arrays and `a` is a 1-D slice of `arr` along `axis`. This is equivalent to (but faster than) the following use of `ndindex` and `s_`, which sets each of ``ii``, ``jj``, and ``kk`` to a tuple of indices:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] for ii in ndindex(Ni): for kk in ndindex(Nk): f = func1d(arr[ii + s_[:,] + kk]) Nj = f.shape for jj in ndindex(Nj): out[ii + jj + kk] = f[jj] Equivalently, eliminating the inner loop, this can be expressed as:: Ni, Nk = a.shape[:axis], a.shape[axis+1:] for ii in ndindex(Ni): for kk in ndindex(Nk): out[ii + s_[...,] + kk] = func1d(arr[ii + s_[:,] + kk]) Parameters ---------- func1d : function (M,) -> (Nj...) This function should accept 1-D arrays. It is applied to 1-D slices of `arr` along the specified axis. axis : integer Axis along which `arr` is sliced. arr : ndarray (Ni..., M, Nk...) Input array. args : any Additional arguments to `func1d`. kwargs : any Additional named arguments to `func1d`. .. versionadded:: 1.9.0 Returns ------- out : ndarray (Ni..., Nj..., Nk...) The output array. The shape of `out` is identical to the shape of `arr`, except along the `axis` dimension. This axis is removed, and replaced with new dimensions equal to the shape of the return value of `func1d`. So if `func1d` returns a scalar `out` will have one fewer dimensions than `arr`. See Also -------- apply_over_axes : Apply a function repeatedly over multiple axes. Examples -------- >>> def my_func(a): ... \"\"\"Average first and last element of a 1-D array\"\"\" ... return (a[0] + a[-1]) 0.5 >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]]) >>> np.apply_along_axis(my_func, 0, b) array([4., 5., 6.]) >>> np.apply_along_axis(my_func, 1, b) array([2., 5., 8.]) For a function that returns a 1D array, the number of dimensions in `outarr` is the same as `arr`. >>> b = np.array([[8,1,7], [4,3,9], [5,2,6]]) >>> np.apply_along_axis(sorted, 1, b) array([[1, 7, 8], [3, 4, 9], [2, 5, 6]]) For a function that returns a higher dimensional array, those dimensions are inserted in place of the `axis` dimension. >>> b = np.array([[1,2,3], [4,5,6], [7,8,9]]) >>> np.apply_along_axis(np.diag, -1, b) array([[[1, 0, 0], [0, 2, 0], [0, 0, 3]], [[4, 0, 0], [0, 5, 0], [0, 0, 6]], [[7, 0, 0], [0, 8, 0], [0, 0, 9]]]) """ # handle negative axes arr = asanyarray(arr) nd = arr.ndim axis = normalize_axis_index(axis, nd) # arr, with the iteration axis at the end in_dims = list(range(nd)) inarr_view = transpose(arr, in_dims[:axis] + in_dims[axis+1:] + [axis]) # compute indices for the iteration axes, and append a trailing ellipsis to # prevent 0d arrays decaying to scalars, which fixes gh-8642 inds = ndindex(inarr_view.shape[:-1]) inds = (ind + (Ellipsis,) for ind in inds) # invoke the function on the first item try: ind0 = next(inds) except StopIteration: raise ValueError( 'Cannot apply_along_axis when any iteration dimensions are 0' ) from None res = asanyarray(func1d(inarr_view[ind0], args, kwargs)) # build a buffer for storing evaluations of func1d. # remove the requested axis, and add the new ones on the end. # laid out so that each write is contiguous. # for a tuple index inds, buff[inds] = func1d(inarr_view[inds]) buff = zeros(inarr_view.shape[:-1] + res.shape, res.dtype) # permutation of axes such that out = buff.transpose(buff_permute) buff_dims = list(range(buff.ndim)) buff_permute = ( buff_dims[0 : axis] + buff_dims[buff.ndim-res.ndim : buff.ndim] + buff_dims[axis : buff.ndim-res.ndim] ) # matrices have a nasty __array_prepare__ and __array_wrap__ if not isinstance(res, matrix): buff = res.__array_prepare__(buff) # save the first result, then compute and save all remaining results buff[ind0] = res for ind in inds: buff[ind] = asanyarray(func1d(inarr_view[ind], args, *kwargs)) if not isinstance(res, matrix): # wrap the array, to preserve subclasses buff = res.__array_wrap__(buff) # finally, rotate the inserted axes back to where they belong return transpose(buff, buff_permute) else: # matrices have to be transposed first, because they collapse dimensions! out_arr = transpose(buff, buff_permute) return res.__array_wrap__(out_arr) def _apply_over_axes_dispatcher(func, a, axes): return (a,) @array_function_dispatch(_apply_over_axes_dispatcher) def apply_over_axes(func, a, axes): """ Apply a function repeatedly over multiple axes. `func` is called as `res = func(a, axis)`, where `axis` is the first element of `axes`. The result `res` of the function call must have either the same dimensions as `a` or one less dimension. If `res` has one less dimension than `a`, a dimension is inserted before `axis`. The call to `func` is then repeated for each axis in `axes`, with `res` as the first argument. Parameters ---------- func : function This function must take two arguments, `func(a, axis)`. a : array_like Input array. axes : array_like Axes over which `func` is applied; the elements must be integers. Returns ------- apply_over_axis : ndarray The output array. The number of dimensions is the same as `a`, but the shape can be different. This depends on whether `func` changes the shape of its output with respect to its input. See Also -------- apply_along_axis : Apply a function to 1-D slices of an array along the given axis. Notes ----- This function is equivalent to tuple axis arguments to reorderable ufuncs with keepdims=True. Tuple axis arguments to ufuncs have been available since version 1.7.0. Examples -------- >>> a = np.arange(24).reshape(2,3,4) >>> a array([[[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11]], [[12, 13, 14, 15], [16, 17, 18, 19], [20, 21, 22, 23]]]) Sum over axes 0 and 2. The result has same number of dimensions as the original array: >>> np.apply_over_axes(np.sum, a, [0,2]) array([[[ 60], [ 92], [124]]]) Tuple axis arguments to ufuncs are equivalent: >>> np.sum(a, axis=(0,2), keepdims=True) array([[[ 60], [ 92], [124]]]) """ val = asarray(a) N = a.ndim if array(axes).ndim == 0: axes = (axes,) for axis in axes: if axis < 0: axis = N + axis args = (val, axis) res = func(args) if res.ndim == val.ndim: val = res else: res = expand_dims(res, axis) if res.ndim == val.ndim: val = res else: raise ValueError("function is not returning " "an array of the correct shape") return val def _expand_dims_dispatcher(a, axis): return (a,) @array_function_dispatch(_expand_dims_dispatcher) def expand_dims(a, axis): """ Expand the shape of an array. Insert a new axis that will appear at the `axis` position in the expanded array shape. Parameters ---------- a : array_like Input array. axis : int or tuple of ints Position in the expanded axes where the new axis (or axes) is placed. .. deprecated:: 1.13.0 Passing an axis where ``axis > a.ndim`` will be treated as ``axis == a.ndim``, and passing ``axis < -a.ndim - 1`` will be treated as ``axis == 0``. This behavior is deprecated. .. versionchanged:: 1.18.0 A tuple of axes is now supported. Out of range axes as described above are now forbidden and raise an `AxisError`. Returns ------- result : ndarray View of `a` with the number of dimensions increased. See Also -------- squeeze : The inverse operation, removing singleton dimensions reshape : Insert, remove, and combine dimensions, and resize existing ones doc.indexing, atleast_1d, atleast_2d, atleast_3d Examples -------- >>> x = np.array([1, 2]) >>> x.shape (2,) The following is equivalent to ``x[np.newaxis, :]`` or ``x[np.newaxis]``: >>> y = np.expand_dims(x, axis=0) >>> y array([[1, 2]]) >>> y.shape (1, 2) The following is equivalent to ``x[:, np.newaxis]``: >>> y = np.expand_dims(x, axis=1) >>> y array([[1], [2]]) >>> y.shape (2, 1) ``axis`` may also be a tuple: >>> y = np.expand_dims(x, axis=(0, 1)) >>> y array([[[1, 2]]]) >>> y = np.expand_dims(x, axis=(2, 0)) >>> y array([[[1], [2]]]) Note that some examples may use ``None`` instead of ``np.newaxis``. These are the same objects: >>> np.newaxis is None True """ if isinstance(a, matrix): a = asarray(a) else: a = asanyarray(a) if type(axis) not in (tuple, list): axis = (axis,) out_ndim = len(axis) + a.ndim axis = normalize_axis_tuple(axis, out_ndim) shape_it = iter(a.shape) shape = [1 if ax in axis else next(shape_it) for ax in range(out_ndim)] return a.reshape(shape) row_stack = vstack def _column_stack_dispatcher(tup): return _arrays_for_stack_dispatcher(tup) @array_function_dispatch(_column_stack_dispatcher) def column_stack(tup): """ Stack 1-D arrays as columns into a 2-D array. Take a sequence of 1-D arrays and stack them as columns to make a single 2-D array. 2-D arrays are stacked as-is, just like with `hstack`. 1-D arrays are turned into 2-D columns first. Parameters ---------- tup : sequence of 1-D or 2-D arrays. Arrays to stack. All of them must have the same first dimension. Returns ------- stacked : 2-D array The array formed by stacking the given arrays. See Also -------- stack, hstack, vstack, concatenate Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.column_stack((a,b)) array([[1, 2], [2, 3], [3, 4]]) """ arrays = [] for v in tup: arr = asanyarray(v) if arr.ndim < 2: arr = array(arr, copy=False, subok=True, ndmin=2).T arrays.append(arr) return _nx.concatenate(arrays, 1) def _dstack_dispatcher(tup): return _arrays_for_stack_dispatcher(tup) @array_function_dispatch(_dstack_dispatcher) def dstack(tup): """ Stack arrays in sequence depth wise (along third axis). This is equivalent to concatenation along the third axis after 2-D arrays of shape `(M,N)` have been reshaped to `(M,N,1)` and 1-D arrays of shape `(N,)` have been reshaped to `(1,N,1)`. Rebuilds arrays divided by `dsplit`. This function makes most sense for arrays with up to 3 dimensions. For instance, for pixel-data with a height (first axis), width (second axis), and r/g/b channels (third axis). The functions `concatenate`, `stack` and `block` provide more general stacking and concatenation operations. Parameters ---------- tup : sequence of arrays The arrays must have the same shape along all but the third axis. 1-D or 2-D arrays must have the same shape. Returns ------- stacked : ndarray The array formed by stacking the given arrays, will be at least 3-D. See Also -------- concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. block : Assemble an nd-array from nested lists of blocks. vstack : Stack arrays in sequence vertically (row wise). hstack : Stack arrays in sequence horizontally (column wise). column_stack : Stack 1-D arrays as columns into a 2-D array. dsplit : Split array along third axis. Examples -------- >>> a = np.array((1,2,3)) >>> b = np.array((2,3,4)) >>> np.dstack((a,b)) array([[[1, 2], [2, 3], [3, 4]]]) >>> a = np.array([[1],[2],[3]]) >>> b = np.array([[2],[3],[4]]) >>> np.dstack((a,b)) array([[[1, 2]], [[2, 3]], [[3, 4]]]) """ arrs = atleast_3d(tup) if not isinstance(arrs, list): arrs = [arrs] return _nx.concatenate(arrs, 2) def _replace_zero_by_x_arrays(sub_arys): for i in range(len(sub_arys)): if _nx.ndim(sub_arys[i]) == 0: sub_arys[i] = _nx.empty(0, dtype=sub_arys[i].dtype) elif _nx.sometrue(_nx.equal(_nx.shape(sub_arys[i]), 0)): sub_arys[i] = _nx.empty(0, dtype=sub_arys[i].dtype) return sub_arys def _array_split_dispatcher(ary, indices_or_sections, axis=None): return (ary, indices_or_sections) @array_function_dispatch(_array_split_dispatcher) def array_split(ary, indices_or_sections, axis=0): """ Split an array into multiple sub-arrays. Please refer to the ``split`` documentation. The only difference between these functions is that ``array_split`` allows `indices_or_sections` to be an integer that does not* equally divide the axis. For an array of length l that should be split into n sections, it returns l % n sub-arrays of size l//n + 1 and the rest of size l//n. See Also -------- split : Split array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(8.0) >>> np.array_split(x, 3) [array([0., 1., 2.]), array([3., 4., 5.]), array([6., 7.])] >>> x = np.arange(9) >>> np.array_split(x, 4) [array([0, 1, 2]), array([3, 4]), array([5, 6]), array([7, 8])] """ try: Ntotal = ary.shape[axis] except AttributeError: Ntotal = len(ary) try: # handle array case. Nsections = len(indices_or_sections) + 1 div_points = [0] + list(indices_or_sections) + [Ntotal] except TypeError: # indices_or_sections is a scalar, not an array. Nsections = int(indices_or_sections) if Nsections <= 0: raise ValueError('number sections must be larger than 0.') from None Neach_section, extras = divmod(Ntotal, Nsections) section_sizes = ([0] + extras * [Neach_section+1] + (Nsections-extras) * [Neach_section]) div_points = _nx.array(section_sizes, dtype=_nx.intp).cumsum() sub_arys = [] sary = _nx.swapaxes(ary, axis, 0) for i in range(Nsections): st = div_points[i] end = div_points[i + 1] sub_arys.append(_nx.swapaxes(sary[st:end], axis, 0)) return sub_arys def _split_dispatcher(ary, indices_or_sections, axis=None): return (ary, indices_or_sections) @array_function_dispatch(_split_dispatcher) def split(ary, indices_or_sections, axis=0): """ Split an array into multiple sub-arrays as views into `ary`. Parameters ---------- ary : ndarray Array to be divided into sub-arrays. indices_or_sections : int or 1-D array If `indices_or_sections` is an integer, N, the array will be divided into N equal arrays along `axis`. If such a split is not possible, an error is raised. If `indices_or_sections` is a 1-D array of sorted integers, the entries indicate where along `axis` the array is split. For example, ``[2, 3]`` would, for ``axis=0``, result in - ary[:2] - ary[2:3] - ary[3:] If an index exceeds the dimension of the array along `axis`, an empty sub-array is returned correspondingly. axis : int, optional The axis along which to split, default is 0. Returns ------- sub-arrays : list of ndarrays A list of sub-arrays as views into `ary`. Raises ------ ValueError If `indices_or_sections` is given as an integer, but a split does not result in equal division. See Also -------- array_split : Split an array into multiple sub-arrays of equal or near-equal size. Does not raise an exception if an equal division cannot be made. hsplit : Split array into multiple sub-arrays horizontally (column-wise). vsplit : Split array into multiple sub-arrays vertically (row wise). dsplit : Split array into multiple sub-arrays along the 3rd axis (depth). concatenate : Join a sequence of arrays along an existing axis. stack : Join a sequence of arrays along a new axis. hstack : Stack arrays in sequence horizontally (column wise). vstack : Stack arrays in sequence vertically (row wise). dstack : Stack arrays in sequence depth wise (along third dimension). Examples -------- >>> x = np.arange(9.0) >>> np.split(x, 3) [array([0., 1., 2.]), array([3., 4., 5.]), array([6., 7., 8.])] >>> x = np.arange(8.0) >>> np.split(x, [3, 5, 6, 10]) [array([0., 1., 2.]), array([3., 4.]), array([5.]), array([6., 7.]), array([], dtype=float64)] """ try: len(indices_or_sections) except TypeError: sections = indices_or_sections N = ary.shape[axis] if N % sections: raise ValueError( 'array split does not result in an equal division') from None return array_split(ary, indices_or_sections, axis) def _hvdsplit_dispatcher(ary, indices_or_sections): return (ary, indices_or_sections) @array_function_dispatch(_hvdsplit_dispatcher) def hsplit(ary, indices_or_sections): """ Split an array into multiple sub-arrays horizontally (column-wise). Please refer to the `split` documentation. `hsplit` is equivalent to `split` with ``axis=1``, the array is always split along the second axis except for 1-D arrays, where it is split at ``axis=0``. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(4, 4) >>> x array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.], [12., 13., 14., 15.]]) >>> np.hsplit(x, 2) [array([[ 0., 1.], [ 4., 5.], [ 8., 9.], [12., 13.]]), array([[ 2., 3.], [ 6., 7.], [10., 11.], [14., 15.]])] >>> np.hsplit(x, np.array([3, 6])) [array([[ 0., 1., 2.], [ 4., 5., 6.], [ 8., 9., 10.], [12., 13., 14.]]), array([[ 3.], [ 7.], [11.], [15.]]), array([], shape=(4, 0), dtype=float64)] With a higher dimensional array the split is still along the second axis. >>> x = np.arange(8.0).reshape(2, 2, 2) >>> x array([[[0., 1.], [2., 3.]], [[4., 5.], [6., 7.]]]) >>> np.hsplit(x, 2) [array([[[0., 1.]], [[4., 5.]]]), array([[[2., 3.]], [[6., 7.]]])] With a 1-D array, the split is along axis 0. >>> x = np.array([0, 1, 2, 3, 4, 5]) >>> np.hsplit(x, 2) [array([0, 1, 2]), array([3, 4, 5])] """ if _nx.ndim(ary) == 0: raise ValueError('hsplit only works on arrays of 1 or more dimensions') if ary.ndim > 1: return split(ary, indices_or_sections, 1) else: return split(ary, indices_or_sections, 0) @array_function_dispatch(_hvdsplit_dispatcher) def vsplit(ary, indices_or_sections): """ Split an array into multiple sub-arrays vertically (row-wise). Please refer to the ``split`` documentation. ``vsplit`` is equivalent to ``split`` with `axis=0` (default), the array is always split along the first axis regardless of the array dimension. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(4, 4) >>> x array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.], [12., 13., 14., 15.]]) >>> np.vsplit(x, 2) [array([[0., 1., 2., 3.], [4., 5., 6., 7.]]), array([[ 8., 9., 10., 11.], [12., 13., 14., 15.]])] >>> np.vsplit(x, np.array([3, 6])) [array([[ 0., 1., 2., 3.], [ 4., 5., 6., 7.], [ 8., 9., 10., 11.]]), array([[12., 13., 14., 15.]]), array([], shape=(0, 4), dtype=float64)] With a higher dimensional array the split is still along the first axis. >>> x = np.arange(8.0).reshape(2, 2, 2) >>> x array([[[0., 1.], [2., 3.]], [[4., 5.], [6., 7.]]]) >>> np.vsplit(x, 2) [array([[[0., 1.], [2., 3.]]]), array([[[4., 5.], [6., 7.]]])] """ if _nx.ndim(ary) < 2: raise ValueError('vsplit only works on arrays of 2 or more dimensions') return split(ary, indices_or_sections, 0) @array_function_dispatch(_hvdsplit_dispatcher) def dsplit(ary, indices_or_sections): """ Split array into multiple sub-arrays along the 3rd axis (depth). Please refer to the `split` documentation. `dsplit` is equivalent to `split` with ``axis=2``, the array is always split along the third axis provided the array dimension is greater than or equal to 3. See Also -------- split : Split an array into multiple sub-arrays of equal size. Examples -------- >>> x = np.arange(16.0).reshape(2, 2, 4) >>> x array([[[ 0., 1., 2., 3.], [ 4., 5., 6., 7.]], [[ 8., 9., 10., 11.], [12., 13., 14., 15.]]]) >>> np.dsplit(x, 2) [array([[[ 0., 1.], [ 4., 5.]], [[ 8., 9.], [12., 13.]]]), array([[[ 2., 3.], [ 6., 7.]], [[10., 11.], [14., 15.]]])] >>> np.dsplit(x, np.array([3, 6])) [array([[[ 0., 1., 2.], [ 4., 5., 6.]], [[ 8., 9., 10.], [12., 13., 14.]]]), array([[[ 3.], [ 7.]], [[11.], [15.]]]), array([], shape=(2, 2, 0), dtype=float64)] """ if _nx.ndim(ary) < 3: raise ValueError('dsplit only works on arrays of 3 or more dimensions') return split(ary, indices_or_sections, 2) def get_array_prepare(args): """Find the wrapper for the array with the highest priority. In case of ties, leftmost wins. If no wrapper is found, return None """ wrappers = sorted((getattr(x, '__array_priority__', 0), -i, x.__array_prepare__) for i, x in enumerate(args) if hasattr(x, '__array_prepare__')) if wrappers: return wrappers[-1][-1] return None def get_array_wrap(args): """Find the wrapper for the array with the highest priority. In case of ties, leftmost wins. If no wrapper is found, return None """ wrappers = sorted((getattr(x, '__array_priority__', 0), -i, x.__array_wrap__) for i, x in enumerate(args) if hasattr(x, '__array_wrap__')) if wrappers: return wrappers[-1][-1] return None def _kron_dispatcher(a, b): return (a, b) @array_function_dispatch(_kron_dispatcher) def kron(a, b): """ Kronecker product of two arrays. Computes the Kronecker product, a composite array made of blocks of the second array scaled by the first. Parameters ---------- a, b : array_like Returns ------- out : ndarray See Also -------- outer : The outer product Notes ----- The function assumes that the number of dimensions of `a` and `b` are the same, if necessary prepending the smallest with ones. If ``a.shape = (r0,r1,..,rN)`` and ``b.shape = (s0,s1,...,sN)``, the Kronecker product has shape ``(r0s0, r1s1, ..., rNSN)``. The elements are products of elements from `a` and `b`, organized explicitly by:: kron(a,b)[k0,k1,...,kN] = a[i0,i1,...,iN] b[j0,j1,...,jN] where:: kt = it * st + jt, t = 0,...,N In the common 2-D case (N=1), the block structure can be visualized:: [[ a[0,0]b, a[0,1]b, ... , a[0,-1]b ], [ ... ... ], [ a[-1,0]b, a[-1,1]b, ... , a[-1,-1]b ]] Examples -------- >>> np.kron([1,10,100], [5,6,7]) array([ 5, 6, 7, ..., 500, 600, 700]) >>> np.kron([5,6,7], [1,10,100]) array([ 5, 50, 500, ..., 7, 70, 700]) >>> np.kron(np.eye(2), np.ones((2,2))) array([[1., 1., 0., 0.], [1., 1., 0., 0.], [0., 0., 1., 1.], [0., 0., 1., 1.]]) >>> a = np.arange(100).reshape((2,5,2,5)) >>> b = np.arange(24).reshape((2,3,4)) >>> c = np.kron(a,b) >>> c.shape (2, 10, 6, 20) >>> I = (1,3,0,2) >>> J = (0,2,1) >>> J1 = (0,) + J # extend to ndim=4 >>> S1 = (1,) + b.shape >>> K = tuple(np.array(I) * np.array(S1) + np.array(J1)) >>> c[K] == a[I]b[J] True """ # Working: # 1. Equalise the shapes by prepending smaller array with 1s # 2. Expand shapes of both the arrays by adding new axes at # odd positions for 1st array and even positions for 2nd # 3. Compute the product of the modified array # 4. The inner most array elements now contain the rows of # the Kronecker product # 5. Reshape the result to kron's shape, which is same as # product of shapes of the two arrays. b = asanyarray(b) a = array(a, copy=False, subok=True, ndmin=b.ndim) is_any_mat = isinstance(a, matrix) or isinstance(b, matrix) ndb, nda = b.ndim, a.ndim nd = max(ndb, nda) if (nda == 0 or ndb == 0): return _nx.multiply(a, b) as_ = a.shape bs = b.shape if not a.flags.contiguous: a = reshape(a, as_) if not b.flags.contiguous: b = reshape(b, bs) # Equalise the shapes by prepending smaller one with 1s as_ = (1,)max(0, ndb-nda) + as_ bs = (1,)max(0, nda-ndb) + bs # Insert empty dimensions a_arr = expand_dims(a, axis=tuple(range(ndb-nda))) b_arr = expand_dims(b, axis=tuple(range(nda-ndb))) # Compute the product a_arr = expand_dims(a_arr, axis=tuple(range(1, nd2, 2))) b_arr = expand_dims(b_arr, axis=tuple(range(0, nd2, 2))) # In case of `mat`, convert result to `array` result = _nx.multiply(a_arr, b_arr, subok=(not is_any_mat)) # Reshape back result = result.reshape(_nx.multiply(as_, bs)) return result if not is_any_mat else matrix(result, copy=False) def _tile_dispatcher(A, reps): return (A, reps) @array_function_dispatch(_tile_dispatcher) def tile(A, reps): """ Construct an array by repeating A the number of times given by reps. If `reps` has length ``d``, the result will have dimension of ``max(d, A.ndim)``. If ``A.ndim < d``, `A` is promoted to be d-dimensional by prepending new axes. So a shape (3,) array is promoted to (1, 3) for 2-D replication, or shape (1, 1, 3) for 3-D replication. If this is not the desired behavior, promote `A` to d-dimensions manually before calling this function. If ``A.ndim > d``, `reps` is promoted to `A`.ndim by pre-pending 1's to it. Thus for an `A` of shape (2, 3, 4, 5), a `reps` of (2, 2) is treated as (1, 1, 2, 2). Note : Although tile may be used for broadcasting, it is strongly recommended to use numpy's broadcasting operations and functions. Parameters ---------- A : array_like The input array. reps : array_like The number of repetitions of `A` along each axis. Returns ------- c : ndarray The tiled output array. See Also -------- repeat : Repeat elements of an array. broadcast_to : Broadcast an array to a new shape Examples -------- >>> a = np.array([0, 1, 2]) >>> np.tile(a, 2) array([0, 1, 2, 0, 1, 2]) >>> np.tile(a, (2, 2)) array([[0, 1, 2, 0, 1, 2], [0, 1, 2, 0, 1, 2]]) >>> np.tile(a, (2, 1, 2)) array([[[0, 1, 2, 0, 1, 2]], [[0, 1, 2, 0, 1, 2]]]) >>> b = np.array([[1, 2], [3, 4]]) >>> np.tile(b, 2) array([[1, 2, 1, 2], [3, 4, 3, 4]]) >>> np.tile(b, (2, 1)) array([[1, 2], [3, 4], [1, 2], [3, 4]]) >>> c = np.array([1,2,3,4]) >>> np.tile(c,(4,1)) array([[1, 2, 3, 4], [1, 2, 3, 4], [1, 2, 3, 4], [1, 2, 3, 4]]) """ try: tup = tuple(reps) except TypeError: tup = (reps,) d = len(tup) if all(x == 1 for x in tup) and isinstance(A, _nx.ndarray): # Fixes the problem that the function does not make a copy if A is a # numpy array and the repetitions are 1 in all dimensions return _nx.array(A, copy=True, subok=True, ndmin=d) else: # Note that no copy of zero-sized arrays is made. However since they # have no data there is no risk of an inadvertent overwrite. c = _nx.array(A, copy=False, subok=True, ndmin=d) if (d < c.ndim): tup = (1,)(c.ndim-d) + tup shape_out = tuple(s*t for s, t in zip(c.shape, tup)) n = c.size if n > 0: for dim_in, nrep in zip(c.shape, tup): if nrep != 1: c = c.reshape(-1, n).repeat(nrep, 0) n //= dim_in return c.reshape(shape_out)	38.03 KB	2026-01-20 12:58
📄 shape_base.pyi from collections.abc import Callable, Sequence from typing import TypeVar, Any, overload, SupportsIndex, Protocol from numpy import ( generic, integer, ufunc, bool_, unsignedinteger, signedinteger, floating, complexfloating, object_, ) from numpy._typing import ( ArrayLike, NDArray, _ShapeLike, _ArrayLike, _ArrayLikeBool_co, _ArrayLikeUInt_co, _ArrayLikeInt_co, _ArrayLikeFloat_co, _ArrayLikeComplex_co, _ArrayLikeObject_co, ) from numpy.core.shape_base import vstack _SCT = TypeVar("_SCT", bound=generic) # The signatures of `__array_wrap__` and `__array_prepare__` are the same; # give them unique names for the sake of clarity class _ArrayWrap(Protocol): def __call__( self, array: NDArray[Any], context: None \| tuple[ufunc, tuple[Any, ...], int] = ..., /, ) -> Any: ... class _ArrayPrepare(Protocol): def __call__( self, array: NDArray[Any], context: None \| tuple[ufunc, tuple[Any, ...], int] = ..., /, ) -> Any: ... class _SupportsArrayWrap(Protocol): @property def __array_wrap__(self) -> _ArrayWrap: ... class _SupportsArrayPrepare(Protocol): @property def __array_prepare__(self) -> _ArrayPrepare: ... __all__: list[str] row_stack = vstack def take_along_axis( arr: _SCT \| NDArray[_SCT], indices: NDArray[integer[Any]], axis: None \| int, ) -> NDArray[_SCT]: ... def put_along_axis( arr: NDArray[_SCT], indices: NDArray[integer[Any]], values: ArrayLike, axis: None \| int, ) -> None: ... # TODO: Use PEP 612 `ParamSpec` once mypy supports `Concatenate` # xref python/mypy#8645 @overload def apply_along_axis( func1d: Callable[..., _ArrayLike[_SCT]], axis: SupportsIndex, arr: ArrayLike, args: Any, kwargs: Any, ) -> NDArray[_SCT]: ... @overload def apply_along_axis( func1d: Callable[..., ArrayLike], axis: SupportsIndex, arr: ArrayLike, args: Any, *kwargs: Any, ) -> NDArray[Any]: ... def apply_over_axes( func: Callable[[NDArray[Any], int], NDArray[_SCT]], a: ArrayLike, axes: int \| Sequence[int], ) -> NDArray[_SCT]: ... @overload def expand_dims( a: _ArrayLike[_SCT], axis: _ShapeLike, ) -> NDArray[_SCT]: ... @overload def expand_dims( a: ArrayLike, axis: _ShapeLike, ) -> NDArray[Any]: ... @overload def column_stack(tup: Sequence[_ArrayLike[_SCT]]) -> NDArray[_SCT]: ... @overload def column_stack(tup: Sequence[ArrayLike]) -> NDArray[Any]: ... @overload def dstack(tup: Sequence[_ArrayLike[_SCT]]) -> NDArray[_SCT]: ... @overload def dstack(tup: Sequence[ArrayLike]) -> NDArray[Any]: ... @overload def array_split( ary: _ArrayLike[_SCT], indices_or_sections: _ShapeLike, axis: SupportsIndex = ..., ) -> list[NDArray[_SCT]]: ... @overload def array_split( ary: ArrayLike, indices_or_sections: _ShapeLike, axis: SupportsIndex = ..., ) -> list[NDArray[Any]]: ... @overload def split( ary: _ArrayLike[_SCT], indices_or_sections: _ShapeLike, axis: SupportsIndex = ..., ) -> list[NDArray[_SCT]]: ... @overload def split( ary: ArrayLike, indices_or_sections: _ShapeLike, axis: SupportsIndex = ..., ) -> list[NDArray[Any]]: ... @overload def hsplit( ary: _ArrayLike[_SCT], indices_or_sections: _ShapeLike, ) -> list[NDArray[_SCT]]: ... @overload def hsplit( ary: ArrayLike, indices_or_sections: _ShapeLike, ) -> list[NDArray[Any]]: ... @overload def vsplit( ary: _ArrayLike[_SCT], indices_or_sections: _ShapeLike, ) -> list[NDArray[_SCT]]: ... @overload def vsplit( ary: ArrayLike, indices_or_sections: _ShapeLike, ) -> list[NDArray[Any]]: ... @overload def dsplit( ary: _ArrayLike[_SCT], indices_or_sections: _ShapeLike, ) -> list[NDArray[_SCT]]: ... @overload def dsplit( ary: ArrayLike, indices_or_sections: _ShapeLike, ) -> list[NDArray[Any]]: ... @overload def get_array_prepare(args: _SupportsArrayPrepare) -> _ArrayPrepare: ... @overload def get_array_prepare(args: object) -> None \| _ArrayPrepare: ... @overload def get_array_wrap(args: _SupportsArrayWrap) -> _ArrayWrap: ... @overload def get_array_wrap(*args: object) -> None \| _ArrayWrap: ... @overload def kron(a: _ArrayLikeBool_co, b: _ArrayLikeBool_co) -> NDArray[bool_]: ... # type: ignore[misc] @overload def kron(a: _ArrayLikeUInt_co, b: _ArrayLikeUInt_co) -> NDArray[unsignedinteger[Any]]: ... # type: ignore[misc] @overload def kron(a: _ArrayLikeInt_co, b: _ArrayLikeInt_co) -> NDArray[signedinteger[Any]]: ... # type: ignore[misc] @overload def kron(a: _ArrayLikeFloat_co, b: _ArrayLikeFloat_co) -> NDArray[floating[Any]]: ... # type: ignore[misc] @overload def kron(a: _ArrayLikeComplex_co, b: _ArrayLikeComplex_co) -> NDArray[complexfloating[Any, Any]]: ... @overload def kron(a: _ArrayLikeObject_co, b: Any) -> NDArray[object_]: ... @overload def kron(a: Any, b: _ArrayLikeObject_co) -> NDArray[object_]: ... @overload def tile( A: _ArrayLike[_SCT], reps: int \| Sequence[int], ) -> NDArray[_SCT]: ... @overload def tile( A: ArrayLike, reps: int \| Sequence[int], ) -> NDArray[Any]: ...	5.06 KB	2026-01-20 12:58
📄 stride_tricks.py """ Utilities that manipulate strides to achieve desirable effects. An explanation of strides can be found in the "ndarray.rst" file in the NumPy reference guide. """ import numpy as np from numpy.core.numeric import normalize_axis_tuple from numpy.core.overrides import array_function_dispatch, set_module __all__ = ['broadcast_to', 'broadcast_arrays', 'broadcast_shapes'] class DummyArray: """Dummy object that just exists to hang __array_interface__ dictionaries and possibly keep alive a reference to a base array. """ def __init__(self, interface, base=None): self.__array_interface__ = interface self.base = base def _maybe_view_as_subclass(original_array, new_array): if type(original_array) is not type(new_array): # if input was an ndarray subclass and subclasses were OK, # then view the result as that subclass. new_array = new_array.view(type=type(original_array)) # Since we have done something akin to a view from original_array, we # should let the subclass finalize (if it has it implemented, i.e., is # not None). if new_array.__array_finalize__: new_array.__array_finalize__(original_array) return new_array def as_strided(x, shape=None, strides=None, subok=False, writeable=True): """ Create a view into the array with the given shape and strides. .. warning:: This function has to be used with extreme care, see notes. Parameters ---------- x : ndarray Array to create a new. shape : sequence of int, optional The shape of the new array. Defaults to ``x.shape``. strides : sequence of int, optional The strides of the new array. Defaults to ``x.strides``. subok : bool, optional .. versionadded:: 1.10 If True, subclasses are preserved. writeable : bool, optional .. versionadded:: 1.12 If set to False, the returned array will always be readonly. Otherwise it will be writable if the original array was. It is advisable to set this to False if possible (see Notes). Returns ------- view : ndarray See also -------- broadcast_to : broadcast an array to a given shape. reshape : reshape an array. lib.stride_tricks.sliding_window_view : userfriendly and safe function for the creation of sliding window views. Notes ----- ``as_strided`` creates a view into the array given the exact strides and shape. This means it manipulates the internal data structure of ndarray and, if done incorrectly, the array elements can point to invalid memory and can corrupt results or crash your program. It is advisable to always use the original ``x.strides`` when calculating new strides to avoid reliance on a contiguous memory layout. Furthermore, arrays created with this function often contain self overlapping memory, so that two elements are identical. Vectorized write operations on such arrays will typically be unpredictable. They may even give different results for small, large, or transposed arrays. Since writing to these arrays has to be tested and done with great care, you may want to use ``writeable=False`` to avoid accidental write operations. For these reasons it is advisable to avoid ``as_strided`` when possible. """ # first convert input to array, possibly keeping subclass x = np.array(x, copy=False, subok=subok) interface = dict(x.__array_interface__) if shape is not None: interface['shape'] = tuple(shape) if strides is not None: interface['strides'] = tuple(strides) array = np.asarray(DummyArray(interface, base=x)) # The route via `__interface__` does not preserve structured # dtypes. Since dtype should remain unchanged, we set it explicitly. array.dtype = x.dtype view = _maybe_view_as_subclass(x, array) if view.flags.writeable and not writeable: view.flags.writeable = False return view def _sliding_window_view_dispatcher(x, window_shape, axis=None, , subok=None, writeable=None): return (x,) @array_function_dispatch(_sliding_window_view_dispatcher) def sliding_window_view(x, window_shape, axis=None, , subok=False, writeable=False): """ Create a sliding window view into the array with the given window shape. Also known as rolling or moving window, the window slides across all dimensions of the array and extracts subsets of the array at all window positions. .. versionadded:: 1.20.0 Parameters ---------- x : array_like Array to create the sliding window view from. window_shape : int or tuple of int Size of window over each axis that takes part in the sliding window. If `axis` is not present, must have same length as the number of input array dimensions. Single integers `i` are treated as if they were the tuple `(i,)`. axis : int or tuple of int, optional Axis or axes along which the sliding window is applied. By default, the sliding window is applied to all axes and `window_shape[i]` will refer to axis `i` of `x`. If `axis` is given as a `tuple of int`, `window_shape[i]` will refer to the axis `axis[i]` of `x`. Single integers `i` are treated as if they were the tuple `(i,)`. subok : bool, optional If True, sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default). writeable : bool, optional When true, allow writing to the returned view. The default is false, as this should be used with caution: the returned view contains the same memory location multiple times, so writing to one location will cause others to change. Returns ------- view : ndarray Sliding window view of the array. The sliding window dimensions are inserted at the end, and the original dimensions are trimmed as required by the size of the sliding window. That is, ``view.shape = x_shape_trimmed + window_shape``, where ``x_shape_trimmed`` is ``x.shape`` with every entry reduced by one less than the corresponding window size. See Also -------- lib.stride_tricks.as_strided: A lower-level and less safe routine for creating arbitrary views from custom shape and strides. broadcast_to: broadcast an array to a given shape. Notes ----- For many applications using a sliding window view can be convenient, but potentially very slow. Often specialized solutions exist, for example: - `scipy.signal.fftconvolve` - filtering functions in `scipy.ndimage` - moving window functions provided by `bottleneck <https://github.com/pydata/bottleneck>`_. As a rough estimate, a sliding window approach with an input size of `N` and a window size of `W` will scale as `O(NW)` where frequently a special algorithm can achieve `O(N)`. That means that the sliding window variant for a window size of 100 can be a 100 times slower than a more specialized version. Nevertheless, for small window sizes, when no custom algorithm exists, or as a prototyping and developing tool, this function can be a good solution. Examples -------- >>> x = np.arange(6) >>> x.shape (6,) >>> v = sliding_window_view(x, 3) >>> v.shape (4, 3) >>> v array([[0, 1, 2], [1, 2, 3], [2, 3, 4], [3, 4, 5]]) This also works in more dimensions, e.g. >>> i, j = np.ogrid[:3, :4] >>> x = 10i + j >>> x.shape (3, 4) >>> x array([[ 0, 1, 2, 3], [10, 11, 12, 13], [20, 21, 22, 23]]) >>> shape = (2,2) >>> v = sliding_window_view(x, shape) >>> v.shape (2, 3, 2, 2) >>> v array([[[[ 0, 1], [10, 11]], [[ 1, 2], [11, 12]], [[ 2, 3], [12, 13]]], [[[10, 11], [20, 21]], [[11, 12], [21, 22]], [[12, 13], [22, 23]]]]) The axis can be specified explicitly: >>> v = sliding_window_view(x, 3, 0) >>> v.shape (1, 4, 3) >>> v array([[[ 0, 10, 20], [ 1, 11, 21], [ 2, 12, 22], [ 3, 13, 23]]]) The same axis can be used several times. In that case, every use reduces the corresponding original dimension: >>> v = sliding_window_view(x, (2, 3), (1, 1)) >>> v.shape (3, 1, 2, 3) >>> v array([[[[ 0, 1, 2], [ 1, 2, 3]]], [[[10, 11, 12], [11, 12, 13]]], [[[20, 21, 22], [21, 22, 23]]]]) Combining with stepped slicing (`::step`), this can be used to take sliding views which skip elements: >>> x = np.arange(7) >>> sliding_window_view(x, 5)[:, ::2] array([[0, 2, 4], [1, 3, 5], [2, 4, 6]]) or views which move by multiple elements >>> x = np.arange(7) >>> sliding_window_view(x, 3)[::2, :] array([[0, 1, 2], [2, 3, 4], [4, 5, 6]]) A common application of `sliding_window_view` is the calculation of running statistics. The simplest example is the `moving average <https://en.wikipedia.org/wiki/Moving_average>`_: >>> x = np.arange(6) >>> x.shape (6,) >>> v = sliding_window_view(x, 3) >>> v.shape (4, 3) >>> v array([[0, 1, 2], [1, 2, 3], [2, 3, 4], [3, 4, 5]]) >>> moving_average = v.mean(axis=-1) >>> moving_average array([1., 2., 3., 4.]) Note that a sliding window approach is often not optimal (see Notes). """ window_shape = (tuple(window_shape) if np.iterable(window_shape) else (window_shape,)) # first convert input to array, possibly keeping subclass x = np.array(x, copy=False, subok=subok) window_shape_array = np.array(window_shape) if np.any(window_shape_array < 0): raise ValueError('`window_shape` cannot contain negative values') if axis is None: axis = tuple(range(x.ndim)) if len(window_shape) != len(axis): raise ValueError(f'Since axis is `None`, must provide ' f'window_shape for all dimensions of `x`; ' f'got {len(window_shape)} window_shape elements ' f'and `x.ndim` is {x.ndim}.') else: axis = normalize_axis_tuple(axis, x.ndim, allow_duplicate=True) if len(window_shape) != len(axis): raise ValueError(f'Must provide matching length window_shape and ' f'axis; got {len(window_shape)} window_shape ' f'elements and {len(axis)} axes elements.') out_strides = x.strides + tuple(x.strides[ax] for ax in axis) # note: same axis can be windowed repeatedly x_shape_trimmed = list(x.shape) for ax, dim in zip(axis, window_shape): if x_shape_trimmed[ax] < dim: raise ValueError( 'window shape cannot be larger than input array shape') x_shape_trimmed[ax] -= dim - 1 out_shape = tuple(x_shape_trimmed) + window_shape return as_strided(x, strides=out_strides, shape=out_shape, subok=subok, writeable=writeable) def _broadcast_to(array, shape, subok, readonly): shape = tuple(shape) if np.iterable(shape) else (shape,) array = np.array(array, copy=False, subok=subok) if not shape and array.shape: raise ValueError('cannot broadcast a non-scalar to a scalar array') if any(size < 0 for size in shape): raise ValueError('all elements of broadcast shape must be non-' 'negative') extras = [] it = np.nditer( (array,), flags=['multi_index', 'refs_ok', 'zerosize_ok'] + extras, op_flags=['readonly'], itershape=shape, order='C') with it: # never really has writebackifcopy semantics broadcast = it.itviews[0] result = _maybe_view_as_subclass(array, broadcast) # In a future version this will go away if not readonly and array.flags._writeable_no_warn: result.flags.writeable = True result.flags._warn_on_write = True return result def _broadcast_to_dispatcher(array, shape, subok=None): return (array,) @array_function_dispatch(_broadcast_to_dispatcher, module='numpy') def broadcast_to(array, shape, subok=False): """Broadcast an array to a new shape. Parameters ---------- array : array_like The array to broadcast. shape : tuple or int The shape of the desired array. A single integer ``i`` is interpreted as ``(i,)``. subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned array will be forced to be a base-class array (default). Returns ------- broadcast : array A readonly view on the original array with the given shape. It is typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. Raises ------ ValueError If the array is not compatible with the new shape according to NumPy's broadcasting rules. See Also -------- broadcast broadcast_arrays broadcast_shapes Notes ----- .. versionadded:: 1.10.0 Examples -------- >>> x = np.array([1, 2, 3]) >>> np.broadcast_to(x, (3, 3)) array([[1, 2, 3], [1, 2, 3], [1, 2, 3]]) """ return _broadcast_to(array, shape, subok=subok, readonly=True) def _broadcast_shape(args): """Returns the shape of the arrays that would result from broadcasting the supplied arrays against each other. """ # use the old-iterator because np.nditer does not handle size 0 arrays # consistently b = np.broadcast(args[:32]) # unfortunately, it cannot handle 32 or more arguments directly for pos in range(32, len(args), 31): # ironically, np.broadcast does not properly handle np.broadcast # objects (it treats them as scalars) # use broadcasting to avoid allocating the full array b = broadcast_to(0, b.shape) b = np.broadcast(b, args[pos:(pos + 31)]) return b.shape @set_module('numpy') def broadcast_shapes(args): """ Broadcast the input shapes into a single shape. :ref:`Learn more about broadcasting here <basics.broadcasting>`. .. versionadded:: 1.20.0 Parameters ---------- `args` : tuples of ints, or ints The shapes to be broadcast against each other. Returns ------- tuple Broadcasted shape. Raises ------ ValueError If the shapes are not compatible and cannot be broadcast according to NumPy's broadcasting rules. See Also -------- broadcast broadcast_arrays broadcast_to Examples -------- >>> np.broadcast_shapes((1, 2), (3, 1), (3, 2)) (3, 2) >>> np.broadcast_shapes((6, 7), (5, 6, 1), (7,), (5, 1, 7)) (5, 6, 7) """ arrays = [np.empty(x, dtype=[]) for x in args] return _broadcast_shape(arrays) def _broadcast_arrays_dispatcher(args, subok=None): return args @array_function_dispatch(_broadcast_arrays_dispatcher, module='numpy') def broadcast_arrays(args, subok=False): """ Broadcast any number of arrays against each other. Parameters ---------- `args` : array_likes The arrays to broadcast. subok : bool, optional If True, then sub-classes will be passed-through, otherwise the returned arrays will be forced to be a base-class array (default). Returns ------- broadcasted : list of arrays These arrays are views on the original arrays. They are typically not contiguous. Furthermore, more than one element of a broadcasted array may refer to a single memory location. If you need to write to the arrays, make copies first. While you can set the ``writable`` flag True, writing to a single output value may end up changing more than one location in the output array. .. deprecated:: 1.17 The output is currently marked so that if written to, a deprecation warning will be emitted. A future version will set the ``writable`` flag False so writing to it will raise an error. See Also -------- broadcast broadcast_to broadcast_shapes Examples -------- >>> x = np.array([[1,2,3]]) >>> y = np.array([[4],[5]]) >>> np.broadcast_arrays(x, y) [array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])] Here is a useful idiom for getting contiguous copies instead of non-contiguous views. >>> [np.array(a) for a in np.broadcast_arrays(x, y)] [array([[1, 2, 3], [1, 2, 3]]), array([[4, 4, 4], [5, 5, 5]])] """ # nditer is not used here to avoid the limit of 32 arrays. # Otherwise, something like the following one-liner would suffice: # return np.nditer(args, flags=['multi_index', 'zerosize_ok'], # order='C').itviews args = [np.array(_m, copy=False, subok=subok) for _m in args] shape = _broadcast_shape(args) if all(array.shape == shape for array in args): # Common case where nothing needs to be broadcasted. return args return [_broadcast_to(array, shape, subok=subok, readonly=False) for array in args]	17.49 KB	2026-01-20 12:58
📄 stride_tricks.pyi from collections.abc import Iterable from typing import Any, TypeVar, overload, SupportsIndex from numpy import generic from numpy._typing import ( NDArray, ArrayLike, _ShapeLike, _Shape, _ArrayLike ) _SCT = TypeVar("_SCT", bound=generic) __all__: list[str] class DummyArray: __array_interface__: dict[str, Any] base: None \| NDArray[Any] def __init__( self, interface: dict[str, Any], base: None \| NDArray[Any] = ..., ) -> None: ... @overload def as_strided( x: _ArrayLike[_SCT], shape: None \| Iterable[int] = ..., strides: None \| Iterable[int] = ..., subok: bool = ..., writeable: bool = ..., ) -> NDArray[_SCT]: ... @overload def as_strided( x: ArrayLike, shape: None \| Iterable[int] = ..., strides: None \| Iterable[int] = ..., subok: bool = ..., writeable: bool = ..., ) -> NDArray[Any]: ... @overload def sliding_window_view( x: _ArrayLike[_SCT], window_shape: int \| Iterable[int], axis: None \| SupportsIndex = ..., , subok: bool = ..., writeable: bool = ..., ) -> NDArray[_SCT]: ... @overload def sliding_window_view( x: ArrayLike, window_shape: int \| Iterable[int], axis: None \| SupportsIndex = ..., , subok: bool = ..., writeable: bool = ..., ) -> NDArray[Any]: ... @overload def broadcast_to( array: _ArrayLike[_SCT], shape: int \| Iterable[int], subok: bool = ..., ) -> NDArray[_SCT]: ... @overload def broadcast_to( array: ArrayLike, shape: int \| Iterable[int], subok: bool = ..., ) -> NDArray[Any]: ... def broadcast_shapes(args: _ShapeLike) -> _Shape: ... def broadcast_arrays( args: ArrayLike, subok: bool = ..., ) -> list[NDArray[Any]]: ...	1.71 KB	2026-01-20 12:58
📁 tests	-	2026-03-21 15:45
📄 twodim_base.py """ Basic functions for manipulating 2d arrays """ import functools import operator from numpy.core.numeric import ( asanyarray, arange, zeros, greater_equal, multiply, ones, asarray, where, int8, int16, int32, int64, intp, empty, promote_types, diagonal, nonzero, indices ) from numpy.core.overrides import set_array_function_like_doc, set_module from numpy.core import overrides from numpy.core import iinfo from numpy.lib.stride_tricks import broadcast_to __all__ = [ 'diag', 'diagflat', 'eye', 'fliplr', 'flipud', 'tri', 'triu', 'tril', 'vander', 'histogram2d', 'mask_indices', 'tril_indices', 'tril_indices_from', 'triu_indices', 'triu_indices_from', ] array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') i1 = iinfo(int8) i2 = iinfo(int16) i4 = iinfo(int32) def _min_int(low, high): """ get small int that fits the range """ if high <= i1.max and low >= i1.min: return int8 if high <= i2.max and low >= i2.min: return int16 if high <= i4.max and low >= i4.min: return int32 return int64 def _flip_dispatcher(m): return (m,) @array_function_dispatch(_flip_dispatcher) def fliplr(m): """ Reverse the order of elements along axis 1 (left/right). For a 2-D array, this flips the entries in each row in the left/right direction. Columns are preserved, but appear in a different order than before. Parameters ---------- m : array_like Input array, must be at least 2-D. Returns ------- f : ndarray A view of `m` with the columns reversed. Since a view is returned, this operation is :math:`\\mathcal O(1)`. See Also -------- flipud : Flip array in the up/down direction. flip : Flip array in one or more dimensions. rot90 : Rotate array counterclockwise. Notes ----- Equivalent to ``m[:,::-1]`` or ``np.flip(m, axis=1)``. Requires the array to be at least 2-D. Examples -------- >>> A = np.diag([1.,2.,3.]) >>> A array([[1., 0., 0.], [0., 2., 0.], [0., 0., 3.]]) >>> np.fliplr(A) array([[0., 0., 1.], [0., 2., 0.], [3., 0., 0.]]) >>> A = np.random.randn(2,3,5) >>> np.all(np.fliplr(A) == A[:,::-1,...]) True """ m = asanyarray(m) if m.ndim < 2: raise ValueError("Input must be >= 2-d.") return m[:, ::-1] @array_function_dispatch(_flip_dispatcher) def flipud(m): """ Reverse the order of elements along axis 0 (up/down). For a 2-D array, this flips the entries in each column in the up/down direction. Rows are preserved, but appear in a different order than before. Parameters ---------- m : array_like Input array. Returns ------- out : array_like A view of `m` with the rows reversed. Since a view is returned, this operation is :math:`\\mathcal O(1)`. See Also -------- fliplr : Flip array in the left/right direction. flip : Flip array in one or more dimensions. rot90 : Rotate array counterclockwise. Notes ----- Equivalent to ``m[::-1, ...]`` or ``np.flip(m, axis=0)``. Requires the array to be at least 1-D. Examples -------- >>> A = np.diag([1.0, 2, 3]) >>> A array([[1., 0., 0.], [0., 2., 0.], [0., 0., 3.]]) >>> np.flipud(A) array([[0., 0., 3.], [0., 2., 0.], [1., 0., 0.]]) >>> A = np.random.randn(2,3,5) >>> np.all(np.flipud(A) == A[::-1,...]) True >>> np.flipud([1,2]) array([2, 1]) """ m = asanyarray(m) if m.ndim < 1: raise ValueError("Input must be >= 1-d.") return m[::-1, ...] @set_array_function_like_doc @set_module('numpy') def eye(N, M=None, k=0, dtype=float, order='C', , like=None): """ Return a 2-D array with ones on the diagonal and zeros elsewhere. Parameters ---------- N : int Number of rows in the output. M : int, optional Number of columns in the output. If None, defaults to `N`. k : int, optional Index of the diagonal: 0 (the default) refers to the main diagonal, a positive value refers to an upper diagonal, and a negative value to a lower diagonal. dtype : data-type, optional Data-type of the returned array. order : {'C', 'F'}, optional Whether the output should be stored in row-major (C-style) or column-major (Fortran-style) order in memory. .. versionadded:: 1.14.0 ${ARRAY_FUNCTION_LIKE} .. versionadded:: 1.20.0 Returns ------- I : ndarray of shape (N,M) An array where all elements are equal to zero, except for the `k`-th diagonal, whose values are equal to one. See Also -------- identity : (almost) equivalent function diag : diagonal 2-D array from a 1-D array specified by the user. Examples -------- >>> np.eye(2, dtype=int) array([[1, 0], [0, 1]]) >>> np.eye(3, k=1) array([[0., 1., 0.], [0., 0., 1.], [0., 0., 0.]]) """ if like is not None: return _eye_with_like(like, N, M=M, k=k, dtype=dtype, order=order) if M is None: M = N m = zeros((N, M), dtype=dtype, order=order) if k >= M: return m # Ensure M and k are integers, so we don't get any surprise casting # results in the expressions `M-k` and `M+1` used below. This avoids # a problem with inputs with type (for example) np.uint64. M = operator.index(M) k = operator.index(k) if k >= 0: i = k else: i = (-k) M m[:M-k].flat[i::M+1] = 1 return m _eye_with_like = array_function_dispatch()(eye) def _diag_dispatcher(v, k=None): return (v,) @array_function_dispatch(_diag_dispatcher) def diag(v, k=0): """ Extract a diagonal or construct a diagonal array. See the more detailed documentation for ``numpy.diagonal`` if you use this function to extract a diagonal and wish to write to the resulting array; whether it returns a copy or a view depends on what version of numpy you are using. Parameters ---------- v : array_like If `v` is a 2-D array, return a copy of its `k`-th diagonal. If `v` is a 1-D array, return a 2-D array with `v` on the `k`-th diagonal. k : int, optional Diagonal in question. The default is 0. Use `k>0` for diagonals above the main diagonal, and `k<0` for diagonals below the main diagonal. Returns ------- out : ndarray The extracted diagonal or constructed diagonal array. See Also -------- diagonal : Return specified diagonals. diagflat : Create a 2-D array with the flattened input as a diagonal. trace : Sum along diagonals. triu : Upper triangle of an array. tril : Lower triangle of an array. Examples -------- >>> x = np.arange(9).reshape((3,3)) >>> x array([[0, 1, 2], [3, 4, 5], [6, 7, 8]]) >>> np.diag(x) array([0, 4, 8]) >>> np.diag(x, k=1) array([1, 5]) >>> np.diag(x, k=-1) array([3, 7]) >>> np.diag(np.diag(x)) array([[0, 0, 0], [0, 4, 0], [0, 0, 8]]) """ v = asanyarray(v) s = v.shape if len(s) == 1: n = s[0]+abs(k) res = zeros((n, n), v.dtype) if k >= 0: i = k else: i = (-k) * n res[:n-k].flat[i::n+1] = v return res elif len(s) == 2: return diagonal(v, k) else: raise ValueError("Input must be 1- or 2-d.") @array_function_dispatch(_diag_dispatcher) def diagflat(v, k=0): """ Create a two-dimensional array with the flattened input as a diagonal. Parameters ---------- v : array_like Input data, which is flattened and set as the `k`-th diagonal of the output. k : int, optional Diagonal to set; 0, the default, corresponds to the "main" diagonal, a positive (negative) `k` giving the number of the diagonal above (below) the main. Returns ------- out : ndarray The 2-D output array. See Also -------- diag : MATLAB work-alike for 1-D and 2-D arrays. diagonal : Return specified diagonals. trace : Sum along diagonals. Examples -------- >>> np.diagflat([[1,2], [3,4]]) array([[1, 0, 0, 0], [0, 2, 0, 0], [0, 0, 3, 0], [0, 0, 0, 4]]) >>> np.diagflat([1,2], 1) array([[0, 1, 0], [0, 0, 2], [0, 0, 0]]) """ try: wrap = v.__array_wrap__ except AttributeError: wrap = None v = asarray(v).ravel() s = len(v) n = s + abs(k) res = zeros((n, n), v.dtype) if (k >= 0): i = arange(0, n-k, dtype=intp) fi = i+k+in else: i = arange(0, n+k, dtype=intp) fi = i+(i-k)n res.flat[fi] = v if not wrap: return res return wrap(res) @set_array_function_like_doc @set_module('numpy') def tri(N, M=None, k=0, dtype=float, , like=None): """ An array with ones at and below the given diagonal and zeros elsewhere. Parameters ---------- N : int Number of rows in the array. M : int, optional Number of columns in the array. By default, `M` is taken equal to `N`. k : int, optional The sub-diagonal at and below which the array is filled. `k` = 0 is the main diagonal, while `k` < 0 is below it, and `k` > 0 is above. The default is 0. dtype : dtype, optional Data type of the returned array. The default is float. ${ARRAY_FUNCTION_LIKE} .. versionadded:: 1.20.0 Returns ------- tri : ndarray of shape (N, M) Array with its lower triangle filled with ones and zero elsewhere; in other words ``T[i,j] == 1`` for ``j <= i + k``, 0 otherwise. Examples -------- >>> np.tri(3, 5, 2, dtype=int) array([[1, 1, 1, 0, 0], [1, 1, 1, 1, 0], [1, 1, 1, 1, 1]]) >>> np.tri(3, 5, -1) array([[0., 0., 0., 0., 0.], [1., 0., 0., 0., 0.], [1., 1., 0., 0., 0.]]) """ if like is not None: return _tri_with_like(like, N, M=M, k=k, dtype=dtype) if M is None: M = N m = greater_equal.outer(arange(N, dtype=_min_int(0, N)), arange(-k, M-k, dtype=_min_int(-k, M - k))) # Avoid making a copy if the requested type is already bool m = m.astype(dtype, copy=False) return m _tri_with_like = array_function_dispatch()(tri) def _trilu_dispatcher(m, k=None): return (m,) @array_function_dispatch(_trilu_dispatcher) def tril(m, k=0): """ Lower triangle of an array. Return a copy of an array with elements above the `k`-th diagonal zeroed. For arrays with ``ndim`` exceeding 2, `tril` will apply to the final two axes. Parameters ---------- m : array_like, shape (..., M, N) Input array. k : int, optional Diagonal above which to zero elements. `k = 0` (the default) is the main diagonal, `k < 0` is below it and `k > 0` is above. Returns ------- tril : ndarray, shape (..., M, N) Lower triangle of `m`, of same shape and data-type as `m`. See Also -------- triu : same thing, only for the upper triangle Examples -------- >>> np.tril([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) array([[ 0, 0, 0], [ 4, 0, 0], [ 7, 8, 0], [10, 11, 12]]) >>> np.tril(np.arange(345).reshape(3, 4, 5)) array([[[ 0, 0, 0, 0, 0], [ 5, 6, 0, 0, 0], [10, 11, 12, 0, 0], [15, 16, 17, 18, 0]], [[20, 0, 0, 0, 0], [25, 26, 0, 0, 0], [30, 31, 32, 0, 0], [35, 36, 37, 38, 0]], [[40, 0, 0, 0, 0], [45, 46, 0, 0, 0], [50, 51, 52, 0, 0], [55, 56, 57, 58, 0]]]) """ m = asanyarray(m) mask = tri(m.shape[-2:], k=k, dtype=bool) return where(mask, m, zeros(1, m.dtype)) @array_function_dispatch(_trilu_dispatcher) def triu(m, k=0): """ Upper triangle of an array. Return a copy of an array with the elements below the `k`-th diagonal zeroed. For arrays with ``ndim`` exceeding 2, `triu` will apply to the final two axes. Please refer to the documentation for `tril` for further details. See Also -------- tril : lower triangle of an array Examples -------- >>> np.triu([[1,2,3],[4,5,6],[7,8,9],[10,11,12]], -1) array([[ 1, 2, 3], [ 4, 5, 6], [ 0, 8, 9], [ 0, 0, 12]]) >>> np.triu(np.arange(345).reshape(3, 4, 5)) array([[[ 0, 1, 2, 3, 4], [ 0, 6, 7, 8, 9], [ 0, 0, 12, 13, 14], [ 0, 0, 0, 18, 19]], [[20, 21, 22, 23, 24], [ 0, 26, 27, 28, 29], [ 0, 0, 32, 33, 34], [ 0, 0, 0, 38, 39]], [[40, 41, 42, 43, 44], [ 0, 46, 47, 48, 49], [ 0, 0, 52, 53, 54], [ 0, 0, 0, 58, 59]]]) """ m = asanyarray(m) mask = tri(m.shape[-2:], k=k-1, dtype=bool) return where(mask, zeros(1, m.dtype), m) def _vander_dispatcher(x, N=None, increasing=None): return (x,) # Originally borrowed from John Hunter and matplotlib @array_function_dispatch(_vander_dispatcher) def vander(x, N=None, increasing=False): """ Generate a Vandermonde matrix. The columns of the output matrix are powers of the input vector. The order of the powers is determined by the `increasing` boolean argument. Specifically, when `increasing` is False, the `i`-th output column is the input vector raised element-wise to the power of ``N - i - 1``. Such a matrix with a geometric progression in each row is named for Alexandre- Theophile Vandermonde. Parameters ---------- x : array_like 1-D input array. N : int, optional Number of columns in the output. If `N` is not specified, a square array is returned (``N = len(x)``). increasing : bool, optional Order of the powers of the columns. If True, the powers increase from left to right, if False (the default) they are reversed. .. versionadded:: 1.9.0 Returns ------- out : ndarray Vandermonde matrix. If `increasing` is False, the first column is ``x^(N-1)``, the second ``x^(N-2)`` and so forth. If `increasing` is True, the columns are ``x^0, x^1, ..., x^(N-1)``. See Also -------- polynomial.polynomial.polyvander Examples -------- >>> x = np.array([1, 2, 3, 5]) >>> N = 3 >>> np.vander(x, N) array([[ 1, 1, 1], [ 4, 2, 1], [ 9, 3, 1], [25, 5, 1]]) >>> np.column_stack([x(N-1-i) for i in range(N)]) array([[ 1, 1, 1], [ 4, 2, 1], [ 9, 3, 1], [25, 5, 1]]) >>> x = np.array([1, 2, 3, 5]) >>> np.vander(x) array([[ 1, 1, 1, 1], [ 8, 4, 2, 1], [ 27, 9, 3, 1], [125, 25, 5, 1]]) >>> np.vander(x, increasing=True) array([[ 1, 1, 1, 1], [ 1, 2, 4, 8], [ 1, 3, 9, 27], [ 1, 5, 25, 125]]) The determinant of a square Vandermonde matrix is the product of the differences between the values of the input vector: >>> np.linalg.det(np.vander(x)) 48.000000000000043 # may vary >>> (5-3)(5-2)(5-1)(3-2)(3-1)(2-1) 48 """ x = asarray(x) if x.ndim != 1: raise ValueError("x must be a one-dimensional array or sequence.") if N is None: N = len(x) v = empty((len(x), N), dtype=promote_types(x.dtype, int)) tmp = v[:, ::-1] if not increasing else v if N > 0: tmp[:, 0] = 1 if N > 1: tmp[:, 1:] = x[:, None] multiply.accumulate(tmp[:, 1:], out=tmp[:, 1:], axis=1) return v def _histogram2d_dispatcher(x, y, bins=None, range=None, density=None, weights=None): yield x yield y # This terrible logic is adapted from the checks in histogram2d try: N = len(bins) except TypeError: N = 1 if N == 2: yield from bins # bins=[x, y] else: yield bins yield weights @array_function_dispatch(_histogram2d_dispatcher) def histogram2d(x, y, bins=10, range=None, density=None, weights=None): """ Compute the bi-dimensional histogram of two data samples. Parameters ---------- x : array_like, shape (N,) An array containing the x coordinates of the points to be histogrammed. y : array_like, shape (N,) An array containing the y coordinates of the points to be histogrammed. bins : int or array_like or [int, int] or [array, array], optional The bin specification: * If int, the number of bins for the two dimensions (nx=ny=bins). * If array_like, the bin edges for the two dimensions (x_edges=y_edges=bins). * If [int, int], the number of bins in each dimension (nx, ny = bins). * If [array, array], the bin edges in each dimension (x_edges, y_edges = bins). * A combination [int, array] or [array, int], where int is the number of bins and array is the bin edges. range : array_like, shape(2,2), optional The leftmost and rightmost edges of the bins along each dimension (if not specified explicitly in the `bins` parameters): ``[[xmin, xmax], [ymin, ymax]]``. All values outside of this range will be considered outliers and not tallied in the histogram. density : bool, optional If False, the default, returns the number of samples in each bin. If True, returns the probability density function at the bin, ``bin_count / sample_count / bin_area``. weights : array_like, shape(N,), optional An array of values ``w_i`` weighing each sample ``(x_i, y_i)``. Weights are normalized to 1 if `density` is True. If `density` is False, the values of the returned histogram are equal to the sum of the weights belonging to the samples falling into each bin. Returns ------- H : ndarray, shape(nx, ny) The bi-dimensional histogram of samples `x` and `y`. Values in `x` are histogrammed along the first dimension and values in `y` are histogrammed along the second dimension. xedges : ndarray, shape(nx+1,) The bin edges along the first dimension. yedges : ndarray, shape(ny+1,) The bin edges along the second dimension. See Also -------- histogram : 1D histogram histogramdd : Multidimensional histogram Notes ----- When `density` is True, then the returned histogram is the sample density, defined such that the sum over bins of the product ``bin_value * bin_area`` is 1. Please note that the histogram does not follow the Cartesian convention where `x` values are on the abscissa and `y` values on the ordinate axis. Rather, `x` is histogrammed along the first dimension of the array (vertical), and `y` along the second dimension of the array (horizontal). This ensures compatibility with `histogramdd`. Examples -------- >>> from matplotlib.image import NonUniformImage >>> import matplotlib.pyplot as plt Construct a 2-D histogram with variable bin width. First define the bin edges: >>> xedges = [0, 1, 3, 5] >>> yedges = [0, 2, 3, 4, 6] Next we create a histogram H with random bin content: >>> x = np.random.normal(2, 1, 100) >>> y = np.random.normal(1, 1, 100) >>> H, xedges, yedges = np.histogram2d(x, y, bins=(xedges, yedges)) >>> # Histogram does not follow Cartesian convention (see Notes), >>> # therefore transpose H for visualization purposes. >>> H = H.T :func:`imshow <matplotlib.pyplot.imshow>` can only display square bins: >>> fig = plt.figure(figsize=(7, 3)) >>> ax = fig.add_subplot(131, title='imshow: square bins') >>> plt.imshow(H, interpolation='nearest', origin='lower', ... extent=[xedges[0], xedges[-1], yedges[0], yedges[-1]]) <matplotlib.image.AxesImage object at 0x...> :func:`pcolormesh <matplotlib.pyplot.pcolormesh>` can display actual edges: >>> ax = fig.add_subplot(132, title='pcolormesh: actual edges', ... aspect='equal') >>> X, Y = np.meshgrid(xedges, yedges) >>> ax.pcolormesh(X, Y, H) <matplotlib.collections.QuadMesh object at 0x...> :class:`NonUniformImage <matplotlib.image.NonUniformImage>` can be used to display actual bin edges with interpolation: >>> ax = fig.add_subplot(133, title='NonUniformImage: interpolated', ... aspect='equal', xlim=xedges[[0, -1]], ylim=yedges[[0, -1]]) >>> im = NonUniformImage(ax, interpolation='bilinear') >>> xcenters = (xedges[:-1] + xedges[1:]) / 2 >>> ycenters = (yedges[:-1] + yedges[1:]) / 2 >>> im.set_data(xcenters, ycenters, H) >>> ax.add_image(im) >>> plt.show() It is also possible to construct a 2-D histogram without specifying bin edges: >>> # Generate non-symmetric test data >>> n = 10000 >>> x = np.linspace(1, 100, n) >>> y = 2np.log(x) + np.random.rand(n) - 0.5 >>> # Compute 2d histogram. Note the order of x/y and xedges/yedges >>> H, yedges, xedges = np.histogram2d(y, x, bins=20) Now we can plot the histogram using :func:`pcolormesh <matplotlib.pyplot.pcolormesh>`, and a :func:`hexbin <matplotlib.pyplot.hexbin>` for comparison. >>> # Plot histogram using pcolormesh >>> fig, (ax1, ax2) = plt.subplots(ncols=2, sharey=True) >>> ax1.pcolormesh(xedges, yedges, H, cmap='rainbow') >>> ax1.plot(x, 2np.log(x), 'k-') >>> ax1.set_xlim(x.min(), x.max()) >>> ax1.set_ylim(y.min(), y.max()) >>> ax1.set_xlabel('x') >>> ax1.set_ylabel('y') >>> ax1.set_title('histogram2d') >>> ax1.grid() >>> # Create hexbin plot for comparison >>> ax2.hexbin(x, y, gridsize=20, cmap='rainbow') >>> ax2.plot(x, 2*np.log(x), 'k-') >>> ax2.set_title('hexbin') >>> ax2.set_xlim(x.min(), x.max()) >>> ax2.set_xlabel('x') >>> ax2.grid() >>> plt.show() """ from numpy import histogramdd if len(x) != len(y): raise ValueError('x and y must have the same length.') try: N = len(bins) except TypeError: N = 1 if N != 1 and N != 2: xedges = yedges = asarray(bins) bins = [xedges, yedges] hist, edges = histogramdd([x, y], bins, range, density, weights) return hist, edges[0], edges[1] @set_module('numpy') def mask_indices(n, mask_func, k=0): """ Return the indices to access (n, n) arrays, given a masking function. Assume `mask_func` is a function that, for a square array a of size ``(n, n)`` with a possible offset argument `k`, when called as ``mask_func(a, k)`` returns a new array with zeros in certain locations (functions like `triu` or `tril` do precisely this). Then this function returns the indices where the non-zero values would be located. Parameters ---------- n : int The returned indices will be valid to access arrays of shape (n, n). mask_func : callable A function whose call signature is similar to that of `triu`, `tril`. That is, ``mask_func(x, k)`` returns a boolean array, shaped like `x`. `k` is an optional argument to the function. k : scalar An optional argument which is passed through to `mask_func`. Functions like `triu`, `tril` take a second argument that is interpreted as an offset. Returns ------- indices : tuple of arrays. The `n` arrays of indices corresponding to the locations where ``mask_func(np.ones((n, n)), k)`` is True. See Also -------- triu, tril, triu_indices, tril_indices Notes ----- .. versionadded:: 1.4.0 Examples -------- These are the indices that would allow you to access the upper triangular part of any 3x3 array: >>> iu = np.mask_indices(3, np.triu) For example, if `a` is a 3x3 array: >>> a = np.arange(9).reshape(3, 3) >>> a array([[0, 1, 2], [3, 4, 5], [6, 7, 8]]) >>> a[iu] array([0, 1, 2, 4, 5, 8]) An offset can be passed also to the masking function. This gets us the indices starting on the first diagonal right of the main one: >>> iu1 = np.mask_indices(3, np.triu, 1) with which we now extract only three elements: >>> a[iu1] array([1, 2, 5]) """ m = ones((n, n), int) a = mask_func(m, k) return nonzero(a != 0) @set_module('numpy') def tril_indices(n, k=0, m=None): """ Return the indices for the lower-triangle of an (n, m) array. Parameters ---------- n : int The row dimension of the arrays for which the returned indices will be valid. k : int, optional Diagonal offset (see `tril` for details). m : int, optional .. versionadded:: 1.9.0 The column dimension of the arrays for which the returned arrays will be valid. By default `m` is taken equal to `n`. Returns ------- inds : tuple of arrays The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array. See also -------- triu_indices : similar function, for upper-triangular. mask_indices : generic function accepting an arbitrary mask function. tril, triu Notes ----- .. versionadded:: 1.4.0 Examples -------- Compute two different sets of indices to access 4x4 arrays, one for the lower triangular part starting at the main diagonal, and one starting two diagonals further right: >>> il1 = np.tril_indices(4) >>> il2 = np.tril_indices(4, 2) Here is how they can be used with a sample array: >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Both for indexing: >>> a[il1] array([ 0, 4, 5, ..., 13, 14, 15]) And for assigning values: >>> a[il1] = -1 >>> a array([[-1, 1, 2, 3], [-1, -1, 6, 7], [-1, -1, -1, 11], [-1, -1, -1, -1]]) These cover almost the whole array (two diagonals right of the main one): >>> a[il2] = -10 >>> a array([[-10, -10, -10, 3], [-10, -10, -10, -10], [-10, -10, -10, -10], [-10, -10, -10, -10]]) """ tri_ = tri(n, m, k=k, dtype=bool) return tuple(broadcast_to(inds, tri_.shape)[tri_] for inds in indices(tri_.shape, sparse=True)) def _trilu_indices_form_dispatcher(arr, k=None): return (arr,) @array_function_dispatch(_trilu_indices_form_dispatcher) def tril_indices_from(arr, k=0): """ Return the indices for the lower-triangle of arr. See `tril_indices` for full details. Parameters ---------- arr : array_like The indices will be valid for square arrays whose dimensions are the same as arr. k : int, optional Diagonal offset (see `tril` for details). Examples -------- Create a 4 by 4 array. >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Pass the array to get the indices of the lower triangular elements. >>> trili = np.tril_indices_from(a) >>> trili (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]), array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3])) >>> a[trili] array([ 0, 4, 5, 8, 9, 10, 12, 13, 14, 15]) This is syntactic sugar for tril_indices(). >>> np.tril_indices(a.shape[0]) (array([0, 1, 1, 2, 2, 2, 3, 3, 3, 3]), array([0, 0, 1, 0, 1, 2, 0, 1, 2, 3])) Use the `k` parameter to return the indices for the lower triangular array up to the k-th diagonal. >>> trili1 = np.tril_indices_from(a, k=1) >>> a[trili1] array([ 0, 1, 4, 5, 6, 8, 9, 10, 11, 12, 13, 14, 15]) See Also -------- tril_indices, tril, triu_indices_from Notes ----- .. versionadded:: 1.4.0 """ if arr.ndim != 2: raise ValueError("input array must be 2-d") return tril_indices(arr.shape[-2], k=k, m=arr.shape[-1]) @set_module('numpy') def triu_indices(n, k=0, m=None): """ Return the indices for the upper-triangle of an (n, m) array. Parameters ---------- n : int The size of the arrays for which the returned indices will be valid. k : int, optional Diagonal offset (see `triu` for details). m : int, optional .. versionadded:: 1.9.0 The column dimension of the arrays for which the returned arrays will be valid. By default `m` is taken equal to `n`. Returns ------- inds : tuple, shape(2) of ndarrays, shape(`n`) The indices for the triangle. The returned tuple contains two arrays, each with the indices along one dimension of the array. Can be used to slice a ndarray of shape(`n`, `n`). See also -------- tril_indices : similar function, for lower-triangular. mask_indices : generic function accepting an arbitrary mask function. triu, tril Notes ----- .. versionadded:: 1.4.0 Examples -------- Compute two different sets of indices to access 4x4 arrays, one for the upper triangular part starting at the main diagonal, and one starting two diagonals further right: >>> iu1 = np.triu_indices(4) >>> iu2 = np.triu_indices(4, 2) Here is how they can be used with a sample array: >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Both for indexing: >>> a[iu1] array([ 0, 1, 2, ..., 10, 11, 15]) And for assigning values: >>> a[iu1] = -1 >>> a array([[-1, -1, -1, -1], [ 4, -1, -1, -1], [ 8, 9, -1, -1], [12, 13, 14, -1]]) These cover only a small part of the whole array (two diagonals right of the main one): >>> a[iu2] = -10 >>> a array([[ -1, -1, -10, -10], [ 4, -1, -1, -10], [ 8, 9, -1, -1], [ 12, 13, 14, -1]]) """ tri_ = ~tri(n, m, k=k - 1, dtype=bool) return tuple(broadcast_to(inds, tri_.shape)[tri_] for inds in indices(tri_.shape, sparse=True)) @array_function_dispatch(_trilu_indices_form_dispatcher) def triu_indices_from(arr, k=0): """ Return the indices for the upper-triangle of arr. See `triu_indices` for full details. Parameters ---------- arr : ndarray, shape(N, N) The indices will be valid for square arrays. k : int, optional Diagonal offset (see `triu` for details). Returns ------- triu_indices_from : tuple, shape(2) of ndarray, shape(N) Indices for the upper-triangle of `arr`. Examples -------- Create a 4 by 4 array. >>> a = np.arange(16).reshape(4, 4) >>> a array([[ 0, 1, 2, 3], [ 4, 5, 6, 7], [ 8, 9, 10, 11], [12, 13, 14, 15]]) Pass the array to get the indices of the upper triangular elements. >>> triui = np.triu_indices_from(a) >>> triui (array([0, 0, 0, 0, 1, 1, 1, 2, 2, 3]), array([0, 1, 2, 3, 1, 2, 3, 2, 3, 3])) >>> a[triui] array([ 0, 1, 2, 3, 5, 6, 7, 10, 11, 15]) This is syntactic sugar for triu_indices(). >>> np.triu_indices(a.shape[0]) (array([0, 0, 0, 0, 1, 1, 1, 2, 2, 3]), array([0, 1, 2, 3, 1, 2, 3, 2, 3, 3])) Use the `k` parameter to return the indices for the upper triangular array from the k-th diagonal. >>> triuim1 = np.triu_indices_from(a, k=1) >>> a[triuim1] array([ 1, 2, 3, 6, 7, 11]) See Also -------- triu_indices, triu, tril_indices_from Notes ----- .. versionadded:: 1.4.0 """ if arr.ndim != 2: raise ValueError("input array must be 2-d") return triu_indices(arr.shape[-2], k=k, m=arr.shape[-1])	32.17 KB	2026-01-20 12:58
📄 twodim_base.pyi from collections.abc import Callable, Sequence from typing import ( Any, overload, TypeVar, Union, ) from numpy import ( generic, number, bool_, timedelta64, datetime64, int_, intp, float64, signedinteger, floating, complexfloating, object_, _OrderCF, ) from numpy._typing import ( DTypeLike, _DTypeLike, ArrayLike, _ArrayLike, NDArray, _SupportsArrayFunc, _ArrayLikeInt_co, _ArrayLikeFloat_co, _ArrayLikeComplex_co, _ArrayLikeObject_co, ) _T = TypeVar("_T") _SCT = TypeVar("_SCT", bound=generic) # The returned arrays dtype must be compatible with `np.equal` _MaskFunc = Callable[ [NDArray[int_], _T], NDArray[Union[number[Any], bool_, timedelta64, datetime64, object_]], ] __all__: list[str] @overload def fliplr(m: _ArrayLike[_SCT]) -> NDArray[_SCT]: ... @overload def fliplr(m: ArrayLike) -> NDArray[Any]: ... @overload def flipud(m: _ArrayLike[_SCT]) -> NDArray[_SCT]: ... @overload def flipud(m: ArrayLike) -> NDArray[Any]: ... @overload def eye( N: int, M: None \| int = ..., k: int = ..., dtype: None = ..., order: _OrderCF = ..., , like: None \| _SupportsArrayFunc = ..., ) -> NDArray[float64]: ... @overload def eye( N: int, M: None \| int = ..., k: int = ..., dtype: _DTypeLike[_SCT] = ..., order: _OrderCF = ..., , like: None \| _SupportsArrayFunc = ..., ) -> NDArray[_SCT]: ... @overload def eye( N: int, M: None \| int = ..., k: int = ..., dtype: DTypeLike = ..., order: _OrderCF = ..., , like: None \| _SupportsArrayFunc = ..., ) -> NDArray[Any]: ... @overload def diag(v: _ArrayLike[_SCT], k: int = ...) -> NDArray[_SCT]: ... @overload def diag(v: ArrayLike, k: int = ...) -> NDArray[Any]: ... @overload def diagflat(v: _ArrayLike[_SCT], k: int = ...) -> NDArray[_SCT]: ... @overload def diagflat(v: ArrayLike, k: int = ...) -> NDArray[Any]: ... @overload def tri( N: int, M: None \| int = ..., k: int = ..., dtype: None = ..., , like: None \| _SupportsArrayFunc = ... ) -> NDArray[float64]: ... @overload def tri( N: int, M: None \| int = ..., k: int = ..., dtype: _DTypeLike[_SCT] = ..., , like: None \| _SupportsArrayFunc = ... ) -> NDArray[_SCT]: ... @overload def tri( N: int, M: None \| int = ..., k: int = ..., dtype: DTypeLike = ..., , like: None \| _SupportsArrayFunc = ... ) -> NDArray[Any]: ... @overload def tril(v: _ArrayLike[_SCT], k: int = ...) -> NDArray[_SCT]: ... @overload def tril(v: ArrayLike, k: int = ...) -> NDArray[Any]: ... @overload def triu(v: _ArrayLike[_SCT], k: int = ...) -> NDArray[_SCT]: ... @overload def triu(v: ArrayLike, k: int = ...) -> NDArray[Any]: ... @overload def vander( # type: ignore[misc] x: _ArrayLikeInt_co, N: None \| int = ..., increasing: bool = ..., ) -> NDArray[signedinteger[Any]]: ... @overload def vander( # type: ignore[misc] x: _ArrayLikeFloat_co, N: None \| int = ..., increasing: bool = ..., ) -> NDArray[floating[Any]]: ... @overload def vander( x: _ArrayLikeComplex_co, N: None \| int = ..., increasing: bool = ..., ) -> NDArray[complexfloating[Any, Any]]: ... @overload def vander( x: _ArrayLikeObject_co, N: None \| int = ..., increasing: bool = ..., ) -> NDArray[object_]: ... @overload def histogram2d( # type: ignore[misc] x: _ArrayLikeFloat_co, y: _ArrayLikeFloat_co, bins: int \| Sequence[int] = ..., range: None \| _ArrayLikeFloat_co = ..., density: None \| bool = ..., weights: None \| _ArrayLikeFloat_co = ..., ) -> tuple[ NDArray[float64], NDArray[floating[Any]], NDArray[floating[Any]], ]: ... @overload def histogram2d( x: _ArrayLikeComplex_co, y: _ArrayLikeComplex_co, bins: int \| Sequence[int] = ..., range: None \| _ArrayLikeFloat_co = ..., density: None \| bool = ..., weights: None \| _ArrayLikeFloat_co = ..., ) -> tuple[ NDArray[float64], NDArray[complexfloating[Any, Any]], NDArray[complexfloating[Any, Any]], ]: ... @overload # TODO: Sort out `bins` def histogram2d( x: _ArrayLikeComplex_co, y: _ArrayLikeComplex_co, bins: Sequence[_ArrayLikeInt_co], range: None \| _ArrayLikeFloat_co = ..., density: None \| bool = ..., weights: None \| _ArrayLikeFloat_co = ..., ) -> tuple[ NDArray[float64], NDArray[Any], NDArray[Any], ]: ... # NOTE: we're assuming/demanding here the `mask_func` returns # an ndarray of shape `(n, n)`; otherwise there is the possibility # of the output tuple having more or less than 2 elements @overload def mask_indices( n: int, mask_func: _MaskFunc[int], k: int = ..., ) -> tuple[NDArray[intp], NDArray[intp]]: ... @overload def mask_indices( n: int, mask_func: _MaskFunc[_T], k: _T, ) -> tuple[NDArray[intp], NDArray[intp]]: ... def tril_indices( n: int, k: int = ..., m: None \| int = ..., ) -> tuple[NDArray[int_], NDArray[int_]]: ... def tril_indices_from( arr: NDArray[Any], k: int = ..., ) -> tuple[NDArray[int_], NDArray[int_]]: ... def triu_indices( n: int, k: int = ..., m: None \| int = ..., ) -> tuple[NDArray[int_], NDArray[int_]]: ... def triu_indices_from( arr: NDArray[Any], k: int = ..., ) -> tuple[NDArray[int_], NDArray[int_]]: ...	5.24 KB	2026-01-20 12:58
📄 type_check.py """Automatically adapted for numpy Sep 19, 2005 by convertcode.py """ import functools __all__ = ['iscomplexobj', 'isrealobj', 'imag', 'iscomplex', 'isreal', 'nan_to_num', 'real', 'real_if_close', 'typename', 'asfarray', 'mintypecode', 'common_type'] from .._utils import set_module import numpy.core.numeric as _nx from numpy.core.numeric import asarray, asanyarray, isnan, zeros from numpy.core import overrides, getlimits from .ufunclike import isneginf, isposinf array_function_dispatch = functools.partial( overrides.array_function_dispatch, module='numpy') _typecodes_by_elsize = 'GDFgdfQqLlIiHhBb?' @set_module('numpy') def mintypecode(typechars, typeset='GDFgdf', default='d'): """ Return the character for the minimum-size type to which given types can be safely cast. The returned type character must represent the smallest size dtype such that an array of the returned type can handle the data from an array of all types in `typechars` (or if `typechars` is an array, then its dtype.char). Parameters ---------- typechars : list of str or array_like If a list of strings, each string should represent a dtype. If array_like, the character representation of the array dtype is used. typeset : str or list of str, optional The set of characters that the returned character is chosen from. The default set is 'GDFgdf'. default : str, optional The default character, this is returned if none of the characters in `typechars` matches a character in `typeset`. Returns ------- typechar : str The character representing the minimum-size type that was found. See Also -------- dtype, sctype2char, maximum_sctype Examples -------- >>> np.mintypecode(['d', 'f', 'S']) 'd' >>> x = np.array([1.1, 2-3.j]) >>> np.mintypecode(x) 'D' >>> np.mintypecode('abceh', default='G') 'G' """ typecodes = ((isinstance(t, str) and t) or asarray(t).dtype.char for t in typechars) intersection = set(t for t in typecodes if t in typeset) if not intersection: return default if 'F' in intersection and 'd' in intersection: return 'D' return min(intersection, key=_typecodes_by_elsize.index) def _asfarray_dispatcher(a, dtype=None): return (a,) @array_function_dispatch(_asfarray_dispatcher) def asfarray(a, dtype=_nx.float_): """ Return an array converted to a float type. Parameters ---------- a : array_like The input array. dtype : str or dtype object, optional Float type code to coerce input array `a`. If `dtype` is one of the 'int' dtypes, it is replaced with float64. Returns ------- out : ndarray The input `a` as a float ndarray. Examples -------- >>> np.asfarray([2, 3]) array([2., 3.]) >>> np.asfarray([2, 3], dtype='float') array([2., 3.]) >>> np.asfarray([2, 3], dtype='int8') array([2., 3.]) """ if not _nx.issubdtype(dtype, _nx.inexact): dtype = _nx.float_ return asarray(a, dtype=dtype) def _real_dispatcher(val): return (val,) @array_function_dispatch(_real_dispatcher) def real(val): """ Return the real part of the complex argument. Parameters ---------- val : array_like Input array. Returns ------- out : ndarray or scalar The real component of the complex argument. If `val` is real, the type of `val` is used for the output. If `val` has complex elements, the returned type is float. See Also -------- real_if_close, imag, angle Examples -------- >>> a = np.array([1+2j, 3+4j, 5+6j]) >>> a.real array([1., 3., 5.]) >>> a.real = 9 >>> a array([9.+2.j, 9.+4.j, 9.+6.j]) >>> a.real = np.array([9, 8, 7]) >>> a array([9.+2.j, 8.+4.j, 7.+6.j]) >>> np.real(1 + 1j) 1.0 """ try: return val.real except AttributeError: return asanyarray(val).real def _imag_dispatcher(val): return (val,) @array_function_dispatch(_imag_dispatcher) def imag(val): """ Return the imaginary part of the complex argument. Parameters ---------- val : array_like Input array. Returns ------- out : ndarray or scalar The imaginary component of the complex argument. If `val` is real, the type of `val` is used for the output. If `val` has complex elements, the returned type is float. See Also -------- real, angle, real_if_close Examples -------- >>> a = np.array([1+2j, 3+4j, 5+6j]) >>> a.imag array([2., 4., 6.]) >>> a.imag = np.array([8, 10, 12]) >>> a array([1. +8.j, 3.+10.j, 5.+12.j]) >>> np.imag(1 + 1j) 1.0 """ try: return val.imag except AttributeError: return asanyarray(val).imag def _is_type_dispatcher(x): return (x,) @array_function_dispatch(_is_type_dispatcher) def iscomplex(x): """ Returns a bool array, where True if input element is complex. What is tested is whether the input has a non-zero imaginary part, not if the input type is complex. Parameters ---------- x : array_like Input array. Returns ------- out : ndarray of bools Output array. See Also -------- isreal iscomplexobj : Return True if x is a complex type or an array of complex numbers. Examples -------- >>> np.iscomplex([1+1j, 1+0j, 4.5, 3, 2, 2j]) array([ True, False, False, False, False, True]) """ ax = asanyarray(x) if issubclass(ax.dtype.type, _nx.complexfloating): return ax.imag != 0 res = zeros(ax.shape, bool) return res[()] # convert to scalar if needed @array_function_dispatch(_is_type_dispatcher) def isreal(x): """ Returns a bool array, where True if input element is real. If element has complex type with zero complex part, the return value for that element is True. Parameters ---------- x : array_like Input array. Returns ------- out : ndarray, bool Boolean array of same shape as `x`. Notes ----- `isreal` may behave unexpectedly for string or object arrays (see examples) See Also -------- iscomplex isrealobj : Return True if x is not a complex type. Examples -------- >>> a = np.array([1+1j, 1+0j, 4.5, 3, 2, 2j], dtype=complex) >>> np.isreal(a) array([False, True, True, True, True, False]) The function does not work on string arrays. >>> a = np.array([2j, "a"], dtype="U") >>> np.isreal(a) # Warns about non-elementwise comparison False Returns True for all elements in input array of ``dtype=object`` even if any of the elements is complex. >>> a = np.array([1, "2", 3+4j], dtype=object) >>> np.isreal(a) array([ True, True, True]) isreal should not be used with object arrays >>> a = np.array([1+2j, 2+1j], dtype=object) >>> np.isreal(a) array([ True, True]) """ return imag(x) == 0 @array_function_dispatch(_is_type_dispatcher) def iscomplexobj(x): """ Check for a complex type or an array of complex numbers. The type of the input is checked, not the value. Even if the input has an imaginary part equal to zero, `iscomplexobj` evaluates to True. Parameters ---------- x : any The input can be of any type and shape. Returns ------- iscomplexobj : bool The return value, True if `x` is of a complex type or has at least one complex element. See Also -------- isrealobj, iscomplex Examples -------- >>> np.iscomplexobj(1) False >>> np.iscomplexobj(1+0j) True >>> np.iscomplexobj([3, 1+0j, True]) True """ try: dtype = x.dtype type_ = dtype.type except AttributeError: type_ = asarray(x).dtype.type return issubclass(type_, _nx.complexfloating) @array_function_dispatch(_is_type_dispatcher) def isrealobj(x): """ Return True if x is a not complex type or an array of complex numbers. The type of the input is checked, not the value. So even if the input has an imaginary part equal to zero, `isrealobj` evaluates to False if the data type is complex. Parameters ---------- x : any The input can be of any type and shape. Returns ------- y : bool The return value, False if `x` is of a complex type. See Also -------- iscomplexobj, isreal Notes ----- The function is only meant for arrays with numerical values but it accepts all other objects. Since it assumes array input, the return value of other objects may be True. >>> np.isrealobj('A string') True >>> np.isrealobj(False) True >>> np.isrealobj(None) True Examples -------- >>> np.isrealobj(1) True >>> np.isrealobj(1+0j) False >>> np.isrealobj([3, 1+0j, True]) False """ return not iscomplexobj(x) #----------------------------------------------------------------------------- def _getmaxmin(t): from numpy.core import getlimits f = getlimits.finfo(t) return f.max, f.min def _nan_to_num_dispatcher(x, copy=None, nan=None, posinf=None, neginf=None): return (x,) @array_function_dispatch(_nan_to_num_dispatcher) def nan_to_num(x, copy=True, nan=0.0, posinf=None, neginf=None): """ Replace NaN with zero and infinity with large finite numbers (default behaviour) or with the numbers defined by the user using the `nan`, `posinf` and/or `neginf` keywords. If `x` is inexact, NaN is replaced by zero or by the user defined value in `nan` keyword, infinity is replaced by the largest finite floating point values representable by ``x.dtype`` or by the user defined value in `posinf` keyword and -infinity is replaced by the most negative finite floating point values representable by ``x.dtype`` or by the user defined value in `neginf` keyword. For complex dtypes, the above is applied to each of the real and imaginary components of `x` separately. If `x` is not inexact, then no replacements are made. Parameters ---------- x : scalar or array_like Input data. copy : bool, optional Whether to create a copy of `x` (True) or to replace values in-place (False). The in-place operation only occurs if casting to an array does not require a copy. Default is True. .. versionadded:: 1.13 nan : int, float, optional Value to be used to fill NaN values. If no value is passed then NaN values will be replaced with 0.0. .. versionadded:: 1.17 posinf : int, float, optional Value to be used to fill positive infinity values. If no value is passed then positive infinity values will be replaced with a very large number. .. versionadded:: 1.17 neginf : int, float, optional Value to be used to fill negative infinity values. If no value is passed then negative infinity values will be replaced with a very small (or negative) number. .. versionadded:: 1.17 Returns ------- out : ndarray `x`, with the non-finite values replaced. If `copy` is False, this may be `x` itself. See Also -------- isinf : Shows which elements are positive or negative infinity. isneginf : Shows which elements are negative infinity. isposinf : Shows which elements are positive infinity. isnan : Shows which elements are Not a Number (NaN). isfinite : Shows which elements are finite (not NaN, not infinity) Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). This means that Not a Number is not equivalent to infinity. Examples -------- >>> np.nan_to_num(np.inf) 1.7976931348623157e+308 >>> np.nan_to_num(-np.inf) -1.7976931348623157e+308 >>> np.nan_to_num(np.nan) 0.0 >>> x = np.array([np.inf, -np.inf, np.nan, -128, 128]) >>> np.nan_to_num(x) array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary -1.28000000e+002, 1.28000000e+002]) >>> np.nan_to_num(x, nan=-9999, posinf=33333333, neginf=33333333) array([ 3.3333333e+07, 3.3333333e+07, -9.9990000e+03, -1.2800000e+02, 1.2800000e+02]) >>> y = np.array([complex(np.inf, np.nan), np.nan, complex(np.nan, np.inf)]) array([ 1.79769313e+308, -1.79769313e+308, 0.00000000e+000, # may vary -1.28000000e+002, 1.28000000e+002]) >>> np.nan_to_num(y) array([ 1.79769313e+308 +0.00000000e+000j, # may vary 0.00000000e+000 +0.00000000e+000j, 0.00000000e+000 +1.79769313e+308j]) >>> np.nan_to_num(y, nan=111111, posinf=222222) array([222222.+111111.j, 111111. +0.j, 111111.+222222.j]) """ x = _nx.array(x, subok=True, copy=copy) xtype = x.dtype.type isscalar = (x.ndim == 0) if not issubclass(xtype, _nx.inexact): return x[()] if isscalar else x iscomplex = issubclass(xtype, _nx.complexfloating) dest = (x.real, x.imag) if iscomplex else (x,) maxf, minf = _getmaxmin(x.real.dtype) if posinf is not None: maxf = posinf if neginf is not None: minf = neginf for d in dest: idx_nan = isnan(d) idx_posinf = isposinf(d) idx_neginf = isneginf(d) _nx.copyto(d, nan, where=idx_nan) _nx.copyto(d, maxf, where=idx_posinf) _nx.copyto(d, minf, where=idx_neginf) return x[()] if isscalar else x #----------------------------------------------------------------------------- def _real_if_close_dispatcher(a, tol=None): return (a,) @array_function_dispatch(_real_if_close_dispatcher) def real_if_close(a, tol=100): """ If input is complex with all imaginary parts close to zero, return real parts. "Close to zero" is defined as `tol` * (machine epsilon of the type for `a`). Parameters ---------- a : array_like Input array. tol : float Tolerance in machine epsilons for the complex part of the elements in the array. If the tolerance is <=1, then the absolute tolerance is used. Returns ------- out : ndarray If `a` is real, the type of `a` is used for the output. If `a` has complex elements, the returned type is float. See Also -------- real, imag, angle Notes ----- Machine epsilon varies from machine to machine and between data types but Python floats on most platforms have a machine epsilon equal to 2.2204460492503131e-16. You can use 'np.finfo(float).eps' to print out the machine epsilon for floats. Examples -------- >>> np.finfo(float).eps 2.2204460492503131e-16 # may vary >>> np.real_if_close([2.1 + 4e-14j, 5.2 + 3e-15j], tol=1000) array([2.1, 5.2]) >>> np.real_if_close([2.1 + 4e-13j, 5.2 + 3e-15j], tol=1000) array([2.1+4.e-13j, 5.2 + 3e-15j]) """ a = asanyarray(a) type_ = a.dtype.type if not issubclass(type_, _nx.complexfloating): return a if tol > 1: f = getlimits.finfo(type_) tol = f.eps * tol if _nx.all(_nx.absolute(a.imag) < tol): a = a.real return a #----------------------------------------------------------------------------- _namefromtype = {'S1': 'character', '?': 'bool', 'b': 'signed char', 'B': 'unsigned char', 'h': 'short', 'H': 'unsigned short', 'i': 'integer', 'I': 'unsigned integer', 'l': 'long integer', 'L': 'unsigned long integer', 'q': 'long long integer', 'Q': 'unsigned long long integer', 'f': 'single precision', 'd': 'double precision', 'g': 'long precision', 'F': 'complex single precision', 'D': 'complex double precision', 'G': 'complex long double precision', 'S': 'string', 'U': 'unicode', 'V': 'void', 'O': 'object' } @set_module('numpy') def typename(char): """ Return a description for the given data type code. Parameters ---------- char : str Data type code. Returns ------- out : str Description of the input data type code. See Also -------- dtype, typecodes Examples -------- >>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q', ... 'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q'] >>> for typechar in typechars: ... print(typechar, ' : ', np.typename(typechar)) ... S1 : character ? : bool B : unsigned char D : complex double precision G : complex long double precision F : complex single precision I : unsigned integer H : unsigned short L : unsigned long integer O : object Q : unsigned long long integer S : string U : unicode V : void b : signed char d : double precision g : long precision f : single precision i : integer h : short l : long integer q : long long integer """ return _namefromtype[char] #----------------------------------------------------------------------------- #determine the "minimum common type" for a group of arrays. array_type = [[_nx.half, _nx.single, _nx.double, _nx.longdouble], [None, _nx.csingle, _nx.cdouble, _nx.clongdouble]] array_precision = {_nx.half: 0, _nx.single: 1, _nx.double: 2, _nx.longdouble: 3, _nx.csingle: 1, _nx.cdouble: 2, _nx.clongdouble: 3} def _common_type_dispatcher(arrays): return arrays @array_function_dispatch(_common_type_dispatcher) def common_type(arrays): """ Return a scalar type which is common to the input arrays. The return type will always be an inexact (i.e. floating point) scalar type, even if all the arrays are integer arrays. If one of the inputs is an integer array, the minimum precision type that is returned is a 64-bit floating point dtype. All input arrays except int64 and uint64 can be safely cast to the returned dtype without loss of information. Parameters ---------- array1, array2, ... : ndarrays Input arrays. Returns ------- out : data type code Data type code. See Also -------- dtype, mintypecode Examples -------- >>> np.common_type(np.arange(2, dtype=np.float32)) <class 'numpy.float32'> >>> np.common_type(np.arange(2, dtype=np.float32), np.arange(2)) <class 'numpy.float64'> >>> np.common_type(np.arange(4), np.array([45, 6.j]), np.array([45.0])) <class 'numpy.complex128'> """ is_complex = False precision = 0 for a in arrays: t = a.dtype.type if iscomplexobj(a): is_complex = True if issubclass(t, _nx.integer): p = 2 # array_precision[_nx.double] else: p = array_precision.get(t, None) if p is None: raise TypeError("can't get common type for non-numeric array") precision = max(precision, p) if is_complex: return array_type[1][precision] else: return array_type[0][precision]	19.49 KB	2026-01-20 12:58
📄 type_check.pyi from collections.abc import Container, Iterable from typing import ( Literal as L, Any, overload, TypeVar, Protocol, ) from numpy import ( dtype, generic, bool_, floating, float64, complexfloating, integer, ) from numpy._typing import ( ArrayLike, DTypeLike, NBitBase, NDArray, _64Bit, _SupportsDType, _ScalarLike_co, _ArrayLike, _DTypeLikeComplex, ) _T = TypeVar("_T") _T_co = TypeVar("_T_co", covariant=True) _SCT = TypeVar("_SCT", bound=generic) _NBit1 = TypeVar("_NBit1", bound=NBitBase) _NBit2 = TypeVar("_NBit2", bound=NBitBase) class _SupportsReal(Protocol[_T_co]): @property def real(self) -> _T_co: ... class _SupportsImag(Protocol[_T_co]): @property def imag(self) -> _T_co: ... __all__: list[str] def mintypecode( typechars: Iterable[str \| ArrayLike], typeset: Container[str] = ..., default: str = ..., ) -> str: ... # `asfarray` ignores dtypes if they're not inexact @overload def asfarray( a: object, dtype: None \| type[float] = ..., ) -> NDArray[float64]: ... @overload def asfarray( # type: ignore[misc] a: Any, dtype: _DTypeLikeComplex, ) -> NDArray[complexfloating[Any, Any]]: ... @overload def asfarray( a: Any, dtype: DTypeLike, ) -> NDArray[floating[Any]]: ... @overload def real(val: _SupportsReal[_T]) -> _T: ... @overload def real(val: ArrayLike) -> NDArray[Any]: ... @overload def imag(val: _SupportsImag[_T]) -> _T: ... @overload def imag(val: ArrayLike) -> NDArray[Any]: ... @overload def iscomplex(x: _ScalarLike_co) -> bool_: ... # type: ignore[misc] @overload def iscomplex(x: ArrayLike) -> NDArray[bool_]: ... @overload def isreal(x: _ScalarLike_co) -> bool_: ... # type: ignore[misc] @overload def isreal(x: ArrayLike) -> NDArray[bool_]: ... def iscomplexobj(x: _SupportsDType[dtype[Any]] \| ArrayLike) -> bool: ... def isrealobj(x: _SupportsDType[dtype[Any]] \| ArrayLike) -> bool: ... @overload def nan_to_num( # type: ignore[misc] x: _SCT, copy: bool = ..., nan: float = ..., posinf: None \| float = ..., neginf: None \| float = ..., ) -> _SCT: ... @overload def nan_to_num( x: _ScalarLike_co, copy: bool = ..., nan: float = ..., posinf: None \| float = ..., neginf: None \| float = ..., ) -> Any: ... @overload def nan_to_num( x: _ArrayLike[_SCT], copy: bool = ..., nan: float = ..., posinf: None \| float = ..., neginf: None \| float = ..., ) -> NDArray[_SCT]: ... @overload def nan_to_num( x: ArrayLike, copy: bool = ..., nan: float = ..., posinf: None \| float = ..., neginf: None \| float = ..., ) -> NDArray[Any]: ... # If one passes a complex array to `real_if_close`, then one is reasonably # expected to verify the output dtype (so we can return an unsafe union here) @overload def real_if_close( # type: ignore[misc] a: _ArrayLike[complexfloating[_NBit1, _NBit1]], tol: float = ..., ) -> NDArray[floating[_NBit1]] \| NDArray[complexfloating[_NBit1, _NBit1]]: ... @overload def real_if_close( a: _ArrayLike[_SCT], tol: float = ..., ) -> NDArray[_SCT]: ... @overload def real_if_close( a: ArrayLike, tol: float = ..., ) -> NDArray[Any]: ... @overload def typename(char: L['S1']) -> L['character']: ... @overload def typename(char: L['?']) -> L['bool']: ... @overload def typename(char: L['b']) -> L['signed char']: ... @overload def typename(char: L['B']) -> L['unsigned char']: ... @overload def typename(char: L['h']) -> L['short']: ... @overload def typename(char: L['H']) -> L['unsigned short']: ... @overload def typename(char: L['i']) -> L['integer']: ... @overload def typename(char: L['I']) -> L['unsigned integer']: ... @overload def typename(char: L['l']) -> L['long integer']: ... @overload def typename(char: L['L']) -> L['unsigned long integer']: ... @overload def typename(char: L['q']) -> L['long long integer']: ... @overload def typename(char: L['Q']) -> L['unsigned long long integer']: ... @overload def typename(char: L['f']) -> L['single precision']: ... @overload def typename(char: L['d']) -> L['double precision']: ... @overload def typename(char: L['g']) -> L['long precision']: ... @overload def typename(char: L['F']) -> L['complex single precision']: ... @overload def typename(char: L['D']) -> L['complex double precision']: ... @overload def typename(char: L['G']) -> L['complex long double precision']: ... @overload def typename(char: L['S']) -> L['string']: ... @overload def typename(char: L['U']) -> L['unicode']: ... @overload def typename(char: L['V']) -> L['void']: ... @overload def typename(char: L['O']) -> L['object']: ... @overload def common_type( # type: ignore[misc] arrays: _SupportsDType[dtype[ integer[Any] ]] ) -> type[floating[_64Bit]]: ... @overload def common_type( # type: ignore[misc] arrays: _SupportsDType[dtype[ floating[_NBit1] ]] ) -> type[floating[_NBit1]]: ... @overload def common_type( # type: ignore[misc] arrays: _SupportsDType[dtype[ integer[Any] \| floating[_NBit1] ]] ) -> type[floating[_NBit1 \| _64Bit]]: ... @overload def common_type( # type: ignore[misc] arrays: _SupportsDType[dtype[ floating[_NBit1] \| complexfloating[_NBit2, _NBit2] ]] ) -> type[complexfloating[_NBit1 \| _NBit2, _NBit1 \| _NBit2]]: ... @overload def common_type( *arrays: _SupportsDType[dtype[ integer[Any] \| floating[_NBit1] \| complexfloating[_NBit2, _NBit2] ]] ) -> type[complexfloating[_64Bit \| _NBit1 \| _NBit2, _64Bit \| _NBit1 \| _NBit2]]: ...	5.44 KB	2026-01-20 12:58
📄 ufunclike.py """ Module of functions that are like ufuncs in acting on arrays and optionally storing results in an output array. """ __all__ = ['fix', 'isneginf', 'isposinf'] import numpy.core.numeric as nx from numpy.core.overrides import array_function_dispatch import warnings import functools def _dispatcher(x, out=None): return (x, out) @array_function_dispatch(_dispatcher, verify=False, module='numpy') def fix(x, out=None): """ Round to nearest integer towards zero. Round an array of floats element-wise to nearest integer towards zero. The rounded values are returned as floats. Parameters ---------- x : array_like An array of floats to be rounded out : ndarray, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated array is returned. Returns ------- out : ndarray of floats A float array with the same dimensions as the input. If second argument is not supplied then a float array is returned with the rounded values. If a second argument is supplied the result is stored there. The return value `out` is then a reference to that array. See Also -------- rint, trunc, floor, ceil around : Round to given number of decimals Examples -------- >>> np.fix(3.14) 3.0 >>> np.fix(3) 3.0 >>> np.fix([2.1, 2.9, -2.1, -2.9]) array([ 2., 2., -2., -2.]) """ # promote back to an array if flattened res = nx.asanyarray(nx.ceil(x, out=out)) res = nx.floor(x, out=res, where=nx.greater_equal(x, 0)) # when no out argument is passed and no subclasses are involved, flatten # scalars if out is None and type(res) is nx.ndarray: res = res[()] return res @array_function_dispatch(_dispatcher, verify=False, module='numpy') def isposinf(x, out=None): """ Test element-wise for positive infinity, return result as bool array. Parameters ---------- x : array_like The input array. out : array_like, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated boolean array is returned. Returns ------- out : ndarray A boolean array with the same dimensions as the input. If second argument is not supplied then a boolean array is returned with values True where the corresponding element of the input is positive infinity and values False where the element of the input is not positive infinity. If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value `out` is then a reference to that array. See Also -------- isinf, isneginf, isfinite, isnan Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). Errors result if the second argument is also supplied when x is a scalar input, if first and second arguments have different shapes, or if the first argument has complex values Examples -------- >>> np.isposinf(np.PINF) True >>> np.isposinf(np.inf) True >>> np.isposinf(np.NINF) False >>> np.isposinf([-np.inf, 0., np.inf]) array([False, False, True]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isposinf(x, y) array([0, 0, 1]) >>> y array([0, 0, 1]) """ is_inf = nx.isinf(x) try: signbit = ~nx.signbit(x) except TypeError as e: dtype = nx.asanyarray(x).dtype raise TypeError(f'This operation is not supported for {dtype} values ' 'because it would be ambiguous.') from e else: return nx.logical_and(is_inf, signbit, out) @array_function_dispatch(_dispatcher, verify=False, module='numpy') def isneginf(x, out=None): """ Test element-wise for negative infinity, return result as bool array. Parameters ---------- x : array_like The input array. out : array_like, optional A location into which the result is stored. If provided, it must have a shape that the input broadcasts to. If not provided or None, a freshly-allocated boolean array is returned. Returns ------- out : ndarray A boolean array with the same dimensions as the input. If second argument is not supplied then a numpy boolean array is returned with values True where the corresponding element of the input is negative infinity and values False where the element of the input is not negative infinity. If a second argument is supplied the result is stored there. If the type of that array is a numeric type the result is represented as zeros and ones, if the type is boolean then as False and True. The return value `out` is then a reference to that array. See Also -------- isinf, isposinf, isnan, isfinite Notes ----- NumPy uses the IEEE Standard for Binary Floating-Point for Arithmetic (IEEE 754). Errors result if the second argument is also supplied when x is a scalar input, if first and second arguments have different shapes, or if the first argument has complex values. Examples -------- >>> np.isneginf(np.NINF) True >>> np.isneginf(np.inf) False >>> np.isneginf(np.PINF) False >>> np.isneginf([-np.inf, 0., np.inf]) array([ True, False, False]) >>> x = np.array([-np.inf, 0., np.inf]) >>> y = np.array([2, 2, 2]) >>> np.isneginf(x, y) array([1, 0, 0]) >>> y array([1, 0, 0]) """ is_inf = nx.isinf(x) try: signbit = nx.signbit(x) except TypeError as e: dtype = nx.asanyarray(x).dtype raise TypeError(f'This operation is not supported for {dtype} values ' 'because it would be ambiguous.') from e else: return nx.logical_and(is_inf, signbit, out)	6.18 KB	2026-01-20 12:58
📄 ufunclike.pyi from typing import Any, overload, TypeVar from numpy import floating, bool_, object_, ndarray from numpy._typing import ( NDArray, _FloatLike_co, _ArrayLikeFloat_co, _ArrayLikeObject_co, ) _ArrayType = TypeVar("_ArrayType", bound=ndarray[Any, Any]) __all__: list[str] @overload def fix( # type: ignore[misc] x: _FloatLike_co, out: None = ..., ) -> floating[Any]: ... @overload def fix( x: _ArrayLikeFloat_co, out: None = ..., ) -> NDArray[floating[Any]]: ... @overload def fix( x: _ArrayLikeObject_co, out: None = ..., ) -> NDArray[object_]: ... @overload def fix( x: _ArrayLikeFloat_co \| _ArrayLikeObject_co, out: _ArrayType, ) -> _ArrayType: ... @overload def isposinf( # type: ignore[misc] x: _FloatLike_co, out: None = ..., ) -> bool_: ... @overload def isposinf( x: _ArrayLikeFloat_co, out: None = ..., ) -> NDArray[bool_]: ... @overload def isposinf( x: _ArrayLikeFloat_co, out: _ArrayType, ) -> _ArrayType: ... @overload def isneginf( # type: ignore[misc] x: _FloatLike_co, out: None = ..., ) -> bool_: ... @overload def isneginf( x: _ArrayLikeFloat_co, out: None = ..., ) -> NDArray[bool_]: ... @overload def isneginf( x: _ArrayLikeFloat_co, out: _ArrayType, ) -> _ArrayType: ...	1.26 KB	2026-01-20 12:58
📄 user_array.py """ Standard container-class for easy multiple-inheritance. Try to inherit from the ndarray instead of using this class as this is not complete. """ from numpy.core import ( array, asarray, absolute, add, subtract, multiply, divide, remainder, power, left_shift, right_shift, bitwise_and, bitwise_or, bitwise_xor, invert, less, less_equal, not_equal, equal, greater, greater_equal, shape, reshape, arange, sin, sqrt, transpose ) class container: """ container(data, dtype=None, copy=True) Standard container-class for easy multiple-inheritance. Methods ------- copy tostring byteswap astype """ def __init__(self, data, dtype=None, copy=True): self.array = array(data, dtype, copy=copy) def __repr__(self): if self.ndim > 0: return self.__class__.__name__ + repr(self.array)[len("array"):] else: return self.__class__.__name__ + "(" + repr(self.array) + ")" def __array__(self, t=None): if t: return self.array.astype(t) return self.array # Array as sequence def __len__(self): return len(self.array) def __getitem__(self, index): return self._rc(self.array[index]) def __setitem__(self, index, value): self.array[index] = asarray(value, self.dtype) def __abs__(self): return self._rc(absolute(self.array)) def __neg__(self): return self._rc(-self.array) def __add__(self, other): return self._rc(self.array + asarray(other)) __radd__ = __add__ def __iadd__(self, other): add(self.array, other, self.array) return self def __sub__(self, other): return self._rc(self.array - asarray(other)) def __rsub__(self, other): return self._rc(asarray(other) - self.array) def __isub__(self, other): subtract(self.array, other, self.array) return self def __mul__(self, other): return self._rc(multiply(self.array, asarray(other))) __rmul__ = __mul__ def __imul__(self, other): multiply(self.array, other, self.array) return self def __div__(self, other): return self._rc(divide(self.array, asarray(other))) def __rdiv__(self, other): return self._rc(divide(asarray(other), self.array)) def __idiv__(self, other): divide(self.array, other, self.array) return self def __mod__(self, other): return self._rc(remainder(self.array, other)) def __rmod__(self, other): return self._rc(remainder(other, self.array)) def __imod__(self, other): remainder(self.array, other, self.array) return self def __divmod__(self, other): return (self._rc(divide(self.array, other)), self._rc(remainder(self.array, other))) def __rdivmod__(self, other): return (self._rc(divide(other, self.array)), self._rc(remainder(other, self.array))) def __pow__(self, other): return self._rc(power(self.array, asarray(other))) def __rpow__(self, other): return self._rc(power(asarray(other), self.array)) def __ipow__(self, other): power(self.array, other, self.array) return self def __lshift__(self, other): return self._rc(left_shift(self.array, other)) def __rshift__(self, other): return self._rc(right_shift(self.array, other)) def __rlshift__(self, other): return self._rc(left_shift(other, self.array)) def __rrshift__(self, other): return self._rc(right_shift(other, self.array)) def __ilshift__(self, other): left_shift(self.array, other, self.array) return self def __irshift__(self, other): right_shift(self.array, other, self.array) return self def __and__(self, other): return self._rc(bitwise_and(self.array, other)) def __rand__(self, other): return self._rc(bitwise_and(other, self.array)) def __iand__(self, other): bitwise_and(self.array, other, self.array) return self def __xor__(self, other): return self._rc(bitwise_xor(self.array, other)) def __rxor__(self, other): return self._rc(bitwise_xor(other, self.array)) def __ixor__(self, other): bitwise_xor(self.array, other, self.array) return self def __or__(self, other): return self._rc(bitwise_or(self.array, other)) def __ror__(self, other): return self._rc(bitwise_or(other, self.array)) def __ior__(self, other): bitwise_or(self.array, other, self.array) return self def __pos__(self): return self._rc(self.array) def __invert__(self): return self._rc(invert(self.array)) def _scalarfunc(self, func): if self.ndim == 0: return func(self[0]) else: raise TypeError( "only rank-0 arrays can be converted to Python scalars.") def __complex__(self): return self._scalarfunc(complex) def __float__(self): return self._scalarfunc(float) def __int__(self): return self._scalarfunc(int) def __hex__(self): return self._scalarfunc(hex) def __oct__(self): return self._scalarfunc(oct) def __lt__(self, other): return self._rc(less(self.array, other)) def __le__(self, other): return self._rc(less_equal(self.array, other)) def __eq__(self, other): return self._rc(equal(self.array, other)) def __ne__(self, other): return self._rc(not_equal(self.array, other)) def __gt__(self, other): return self._rc(greater(self.array, other)) def __ge__(self, other): return self._rc(greater_equal(self.array, other)) def copy(self): "" return self._rc(self.array.copy()) def tostring(self): "" return self.array.tostring() def tobytes(self): "" return self.array.tobytes() def byteswap(self): "" return self._rc(self.array.byteswap()) def astype(self, typecode): "" return self._rc(self.array.astype(typecode)) def _rc(self, a): if len(shape(a)) == 0: return a else: return self.__class__(a) def __array_wrap__(self, args): return self.__class__(args[0]) def __setattr__(self, attr, value): if attr == 'array': object.__setattr__(self, attr, value) return try: self.array.__setattr__(attr, value) except AttributeError: object.__setattr__(self, attr, value) # Only called after other approaches fail. def __getattr__(self, attr): if (attr == 'array'): return object.__getattribute__(self, attr) return self.array.__getattribute__(attr) ############################################################# # Test of class container ############################################################# if __name__ == '__main__': temp = reshape(arange(10000), (100, 100)) ua = container(temp) # new object created begin test print(dir(ua)) print(shape(ua), ua.shape) # I have changed Numeric.py ua_small = ua[:3, :5] print(ua_small) # this did not change ua[0,0], which is not normal behavior ua_small[0, 0] = 10 print(ua_small[0, 0], ua[0, 0]) print(sin(ua_small) / 3. 6. + sqrt(ua_small ** 2)) print(less(ua_small, 103), type(less(ua_small, 103))) print(type(ua_small * reshape(arange(15), shape(ua_small)))) print(reshape(ua_small, (5, 3))) print(transpose(ua_small))	7.54 KB	2026-01-20 12:58
📄 utils.py import os import sys import textwrap import types import re import warnings import functools import platform from .._utils import set_module from numpy.core.numerictypes import issubclass_, issubsctype, issubdtype from numpy.core import ndarray, ufunc, asarray import numpy as np __all__ = [ 'issubclass_', 'issubsctype', 'issubdtype', 'deprecate', 'deprecate_with_doc', 'get_include', 'info', 'source', 'who', 'lookfor', 'byte_bounds', 'safe_eval', 'show_runtime' ] def show_runtime(): """ Print information about various resources in the system including available intrinsic support and BLAS/LAPACK library in use .. versionadded:: 1.24.0 See Also -------- show_config : Show libraries in the system on which NumPy was built. Notes ----- 1. Information is derived with the help of `threadpoolctl <https://pypi.org/project/threadpoolctl/>`_ library if available. 2. SIMD related information is derived from ``__cpu_features__``, ``__cpu_baseline__`` and ``__cpu_dispatch__`` """ from numpy.core._multiarray_umath import ( __cpu_features__, __cpu_baseline__, __cpu_dispatch__ ) from pprint import pprint config_found = [{ "numpy_version": np.__version__, "python": sys.version, "uname": platform.uname(), }] features_found, features_not_found = [], [] for feature in __cpu_dispatch__: if __cpu_features__[feature]: features_found.append(feature) else: features_not_found.append(feature) config_found.append({ "simd_extensions": { "baseline": __cpu_baseline__, "found": features_found, "not_found": features_not_found } }) try: from threadpoolctl import threadpool_info config_found.extend(threadpool_info()) except ImportError: print("WARNING: `threadpoolctl` not found in system!" " Install it by `pip install threadpoolctl`." " Once installed, try `np.show_runtime` again" " for more detailed build information") pprint(config_found) def get_include(): """ Return the directory that contains the NumPy \\.h header files. Extension modules that need to compile against NumPy should use this function to locate the appropriate include directory. Notes ----- When using ``distutils``, for example in ``setup.py``:: import numpy as np ... Extension('extension_name', ... include_dirs=[np.get_include()]) ... """ import numpy if numpy.show_config is None: # running from numpy source directory d = os.path.join(os.path.dirname(numpy.__file__), 'core', 'include') else: # using installed numpy core headers import numpy.core as core d = os.path.join(os.path.dirname(core.__file__), 'include') return d class _Deprecate: """ Decorator class to deprecate old functions. Refer to `deprecate` for details. See Also -------- deprecate """ def __init__(self, old_name=None, new_name=None, message=None): self.old_name = old_name self.new_name = new_name self.message = message def __call__(self, func, args, *kwargs): """ Decorator call. Refer to ``decorate``. """ old_name = self.old_name new_name = self.new_name message = self.message if old_name is None: old_name = func.__name__ if new_name is None: depdoc = "`%s` is deprecated!" % old_name else: depdoc = "`%s` is deprecated, use `%s` instead!" % \ (old_name, new_name) if message is not None: depdoc += "\n" + message @functools.wraps(func) def newfunc(args, *kwds): warnings.warn(depdoc, DeprecationWarning, stacklevel=2) return func(args, *kwds) newfunc.__name__ = old_name doc = func.__doc__ if doc is None: doc = depdoc else: lines = doc.expandtabs().split('\n') indent = _get_indent(lines[1:]) if lines[0].lstrip(): # Indent the original first line to let inspect.cleandoc() # dedent the docstring despite the deprecation notice. doc = indent ' ' + doc else: # Remove the same leading blank lines as cleandoc() would. skip = len(lines[0]) + 1 for line in lines[1:]: if len(line) > indent: break skip += len(line) + 1 doc = doc[skip:] depdoc = textwrap.indent(depdoc, ' ' * indent) doc = '\n\n'.join([depdoc, doc]) newfunc.__doc__ = doc return newfunc def _get_indent(lines): """ Determines the leading whitespace that could be removed from all the lines. """ indent = sys.maxsize for line in lines: content = len(line.lstrip()) if content: indent = min(indent, len(line) - content) if indent == sys.maxsize: indent = 0 return indent def deprecate(args, kwargs): """ Issues a DeprecationWarning, adds warning to `old_name`'s docstring, rebinds ``old_name.__name__`` and returns the new function object. This function may also be used as a decorator. Parameters ---------- func : function The function to be deprecated. old_name : str, optional The name of the function to be deprecated. Default is None, in which case the name of `func` is used. new_name : str, optional The new name for the function. Default is None, in which case the deprecation message is that `old_name` is deprecated. If given, the deprecation message is that `old_name` is deprecated and `new_name` should be used instead. message : str, optional Additional explanation of the deprecation. Displayed in the docstring after the warning. Returns ------- old_func : function The deprecated function. Examples -------- Note that ``olduint`` returns a value after printing Deprecation Warning: >>> olduint = np.deprecate(np.uint) DeprecationWarning: `uint64` is deprecated! # may vary >>> olduint(6) 6 """ # Deprecate may be run as a function or as a decorator # If run as a function, we initialise the decorator class # and execute its __call__ method. if args: fn = args[0] args = args[1:] return _Deprecate(args, *kwargs)(fn) else: return _Deprecate(args, *kwargs) def deprecate_with_doc(msg): """ Deprecates a function and includes the deprecation in its docstring. This function is used as a decorator. It returns an object that can be used to issue a DeprecationWarning, by passing the to-be decorated function as argument, this adds warning to the to-be decorated function's docstring and returns the new function object. See Also -------- deprecate : Decorate a function such that it issues a `DeprecationWarning` Parameters ---------- msg : str Additional explanation of the deprecation. Displayed in the docstring after the warning. Returns ------- obj : object """ return _Deprecate(message=msg) #-------------------------------------------- # Determine if two arrays can share memory #-------------------------------------------- def byte_bounds(a): """ Returns pointers to the end-points of an array. Parameters ---------- a : ndarray Input array. It must conform to the Python-side of the array interface. Returns ------- (low, high) : tuple of 2 integers The first integer is the first byte of the array, the second integer is just past the last byte of the array. If `a` is not contiguous it will not use every byte between the (`low`, `high`) values. Examples -------- >>> I = np.eye(2, dtype='f'); I.dtype dtype('float32') >>> low, high = np.byte_bounds(I) >>> high - low == I.sizeI.itemsize True >>> I = np.eye(2); I.dtype dtype('float64') >>> low, high = np.byte_bounds(I) >>> high - low == I.sizeI.itemsize True """ ai = a.__array_interface__ a_data = ai['data'][0] astrides = ai['strides'] ashape = ai['shape'] bytes_a = asarray(a).dtype.itemsize a_low = a_high = a_data if astrides is None: # contiguous case a_high += a.size bytes_a else: for shape, stride in zip(ashape, astrides): if stride < 0: a_low += (shape-1)stride else: a_high += (shape-1)stride a_high += bytes_a return a_low, a_high #----------------------------------------------------------------------------- # Function for output and information on the variables used. #----------------------------------------------------------------------------- def who(vardict=None): """ Print the NumPy arrays in the given dictionary. If there is no dictionary passed in or `vardict` is None then returns NumPy arrays in the globals() dictionary (all NumPy arrays in the namespace). Parameters ---------- vardict : dict, optional A dictionary possibly containing ndarrays. Default is globals(). Returns ------- out : None Returns 'None'. Notes ----- Prints out the name, shape, bytes and type of all of the ndarrays present in `vardict`. Examples -------- >>> a = np.arange(10) >>> b = np.ones(20) >>> np.who() Name Shape Bytes Type =========================================================== a 10 80 int64 b 20 160 float64 Upper bound on total bytes = 240 >>> d = {'x': np.arange(2.0), 'y': np.arange(3.0), 'txt': 'Some str', ... 'idx':5} >>> np.who(d) Name Shape Bytes Type =========================================================== x 2 16 float64 y 3 24 float64 Upper bound on total bytes = 40 """ if vardict is None: frame = sys._getframe().f_back vardict = frame.f_globals sta = [] cache = {} for name in vardict.keys(): if isinstance(vardict[name], ndarray): var = vardict[name] idv = id(var) if idv in cache.keys(): namestr = name + " (%s)" % cache[idv] original = 0 else: cache[idv] = name namestr = name original = 1 shapestr = " x ".join(map(str, var.shape)) bytestr = str(var.nbytes) sta.append([namestr, shapestr, bytestr, var.dtype.name, original]) maxname = 0 maxshape = 0 maxbyte = 0 totalbytes = 0 for val in sta: if maxname < len(val[0]): maxname = len(val[0]) if maxshape < len(val[1]): maxshape = len(val[1]) if maxbyte < len(val[2]): maxbyte = len(val[2]) if val[4]: totalbytes += int(val[2]) if len(sta) > 0: sp1 = max(10, maxname) sp2 = max(10, maxshape) sp3 = max(10, maxbyte) prval = "Name %s Shape %s Bytes %s Type" % (sp1' ', sp2' ', sp3' ') print(prval + "\n" + "="(len(prval)+5) + "\n") for val in sta: print("%s %s %s %s %s %s %s" % (val[0], ' '(sp1-len(val[0])+4), val[1], ' '(sp2-len(val[1])+5), val[2], ' '(sp3-len(val[2])+5), val[3])) print("\nUpper bound on total bytes = %d" % totalbytes) return #----------------------------------------------------------------------------- # NOTE: pydoc defines a help function which works similarly to this # except it uses a pager to take over the screen. # combine name and arguments and split to multiple lines of width # characters. End lines on a comma and begin argument list indented with # the rest of the arguments. def _split_line(name, arguments, width): firstwidth = len(name) k = firstwidth newstr = name sepstr = ", " arglist = arguments.split(sepstr) for argument in arglist: if k == firstwidth: addstr = "" else: addstr = sepstr k = k + len(argument) + len(addstr) if k > width: k = firstwidth + 1 + len(argument) newstr = newstr + ",\n" + " "(firstwidth+2) + argument else: newstr = newstr + addstr + argument return newstr _namedict = None _dictlist = None # Traverse all module directories underneath globals # to see if something is defined def _makenamedict(module='numpy'): module = __import__(module, globals(), locals(), []) thedict = {module.__name__:module.__dict__} dictlist = [module.__name__] totraverse = [module.__dict__] while True: if len(totraverse) == 0: break thisdict = totraverse.pop(0) for x in thisdict.keys(): if isinstance(thisdict[x], types.ModuleType): modname = thisdict[x].__name__ if modname not in dictlist: moddict = thisdict[x].__dict__ dictlist.append(modname) totraverse.append(moddict) thedict[modname] = moddict return thedict, dictlist def _info(obj, output=None): """Provide information about ndarray obj. Parameters ---------- obj : ndarray Must be ndarray, not checked. output Where printed output goes. Notes ----- Copied over from the numarray module prior to its removal. Adapted somewhat as only numpy is an option now. Called by info. """ extra = "" tic = "" bp = lambda x: x cls = getattr(obj, '__class__', type(obj)) nm = getattr(cls, '__name__', cls) strides = obj.strides endian = obj.dtype.byteorder if output is None: output = sys.stdout print("class: ", nm, file=output) print("shape: ", obj.shape, file=output) print("strides: ", strides, file=output) print("itemsize: ", obj.itemsize, file=output) print("aligned: ", bp(obj.flags.aligned), file=output) print("contiguous: ", bp(obj.flags.contiguous), file=output) print("fortran: ", obj.flags.fortran, file=output) print( "data pointer: %s%s" % (hex(obj.ctypes._as_parameter_.value), extra), file=output ) print("byteorder: ", end=' ', file=output) if endian in ['\|', '=']: print("%s%s%s" % (tic, sys.byteorder, tic), file=output) byteswap = False elif endian == '>': print("%sbig%s" % (tic, tic), file=output) byteswap = sys.byteorder != "big" else: print("%slittle%s" % (tic, tic), file=output) byteswap = sys.byteorder != "little" print("byteswap: ", bp(byteswap), file=output) print("type: %s" % obj.dtype, file=output) @set_module('numpy') def info(object=None, maxwidth=76, output=None, toplevel='numpy'): """ Get help information for an array, function, class, or module. Parameters ---------- object : object or str, optional Input object or name to get information about. If `object` is an `ndarray` instance, information about the array is printed. If `object` is a numpy object, its docstring is given. If it is a string, available modules are searched for matching objects. If None, information about `info` itself is returned. maxwidth : int, optional Printing width. output : file like object, optional File like object that the output is written to, default is ``None``, in which case ``sys.stdout`` will be used. The object has to be opened in 'w' or 'a' mode. toplevel : str, optional Start search at this level. See Also -------- source, lookfor Notes ----- When used interactively with an object, ``np.info(obj)`` is equivalent to ``help(obj)`` on the Python prompt or ``obj?`` on the IPython prompt. Examples -------- >>> np.info(np.polyval) # doctest: +SKIP polyval(p, x) Evaluate the polynomial p at x. ... When using a string for `object` it is possible to get multiple results. >>> np.info('fft') # doctest: +SKIP * Found in numpy * Core FFT routines ... * Found in numpy.fft * fft(a, n=None, axis=-1) ... * Repeat reference found in numpy.fft.fftpack * * Total of 3 references found. * When the argument is an array, information about the array is printed. >>> a = np.array([[1 + 2j, 3, -4], [-5j, 6, 0]], dtype=np.complex64) >>> np.info(a) class: ndarray shape: (2, 3) strides: (24, 8) itemsize: 8 aligned: True contiguous: True fortran: False data pointer: 0x562b6e0d2860 # may vary byteorder: little byteswap: False type: complex64 """ global _namedict, _dictlist # Local import to speed up numpy's import time. import pydoc import inspect if (hasattr(object, '_ppimport_importer') or hasattr(object, '_ppimport_module')): object = object._ppimport_module elif hasattr(object, '_ppimport_attr'): object = object._ppimport_attr if output is None: output = sys.stdout if object is None: info(info) elif isinstance(object, ndarray): _info(object, output=output) elif isinstance(object, str): if _namedict is None: _namedict, _dictlist = _makenamedict(toplevel) numfound = 0 objlist = [] for namestr in _dictlist: try: obj = _namedict[namestr][object] if id(obj) in objlist: print("\n " "* Repeat reference found in %s * " % namestr, file=output ) else: objlist.append(id(obj)) print(" * Found in %s " % namestr, file=output) info(obj) print("-"maxwidth, file=output) numfound += 1 except KeyError: pass if numfound == 0: print("Help for %s not found." % object, file=output) else: print("\n " "* Total of %d references found. " % numfound, file=output ) elif inspect.isfunction(object) or inspect.ismethod(object): name = object.__name__ try: arguments = str(inspect.signature(object)) except Exception: arguments = "()" if len(name+arguments) > maxwidth: argstr = _split_line(name, arguments, maxwidth) else: argstr = name + arguments print(" " + argstr + "\n", file=output) print(inspect.getdoc(object), file=output) elif inspect.isclass(object): name = object.__name__ try: arguments = str(inspect.signature(object)) except Exception: arguments = "()" if len(name+arguments) > maxwidth: argstr = _split_line(name, arguments, maxwidth) else: argstr = name + arguments print(" " + argstr + "\n", file=output) doc1 = inspect.getdoc(object) if doc1 is None: if hasattr(object, '__init__'): print(inspect.getdoc(object.__init__), file=output) else: print(inspect.getdoc(object), file=output) methods = pydoc.allmethods(object) public_methods = [meth for meth in methods if meth[0] != '_'] if public_methods: print("\n\nMethods:\n", file=output) for meth in public_methods: thisobj = getattr(object, meth, None) if thisobj is not None: methstr, other = pydoc.splitdoc( inspect.getdoc(thisobj) or "None" ) print(" %s -- %s" % (meth, methstr), file=output) elif hasattr(object, '__doc__'): print(inspect.getdoc(object), file=output) @set_module('numpy') def source(object, output=sys.stdout): """ Print or write to a file the source code for a NumPy object. The source code is only returned for objects written in Python. Many functions and classes are defined in C and will therefore not return useful information. Parameters ---------- object : numpy object Input object. This can be any object (function, class, module, ...). output : file object, optional If `output` not supplied then source code is printed to screen (sys.stdout). File object must be created with either write 'w' or append 'a' modes. See Also -------- lookfor, info Examples -------- >>> np.source(np.interp) #doctest: +SKIP In file: /usr/lib/python2.6/dist-packages/numpy/lib/function_base.py def interp(x, xp, fp, left=None, right=None): \"\"\".... (full docstring printed)\"\"\" if isinstance(x, (float, int, number)): return compiled_interp([x], xp, fp, left, right).item() else: return compiled_interp(x, xp, fp, left, right) The source code is only returned for objects written in Python. >>> np.source(np.array) #doctest: +SKIP Not available for this object. """ # Local import to speed up numpy's import time. import inspect try: print("In file: %s\n" % inspect.getsourcefile(object), file=output) print(inspect.getsource(object), file=output) except Exception: print("Not available for this object.", file=output) # Cache for lookfor: {id(module): {name: (docstring, kind, index), ...}...} # where kind: "func", "class", "module", "object" # and index: index in breadth-first namespace traversal _lookfor_caches = {} # regexp whose match indicates that the string may contain a function # signature _function_signature_re = re.compile(r"[a-z0-9_]+$.[,=].$", re.I) @set_module('numpy') def lookfor(what, module=None, import_modules=True, regenerate=False, output=None): """ Do a keyword search on docstrings. A list of objects that matched the search is displayed, sorted by relevance. All given keywords need to be found in the docstring for it to be returned as a result, but the order does not matter. Parameters ---------- what : str String containing words to look for. module : str or list, optional Name of module(s) whose docstrings to go through. import_modules : bool, optional Whether to import sub-modules in packages. Default is True. regenerate : bool, optional Whether to re-generate the docstring cache. Default is False. output : file-like, optional File-like object to write the output to. If omitted, use a pager. See Also -------- source, info Notes ----- Relevance is determined only roughly, by checking if the keywords occur in the function name, at the start of a docstring, etc. Examples -------- >>> np.lookfor('binary representation') # doctest: +SKIP Search results for 'binary representation' ------------------------------------------ numpy.binary_repr Return the binary representation of the input number as a string. numpy.core.setup_common.long_double_representation Given a binary dump as given by GNU od -b, look for long double numpy.base_repr Return a string representation of a number in the given base system. ... """ import pydoc # Cache cache = _lookfor_generate_cache(module, import_modules, regenerate) # Search # XXX: maybe using a real stemming search engine would be better? found = [] whats = str(what).lower().split() if not whats: return for name, (docstring, kind, index) in cache.items(): if kind in ('module', 'object'): # don't show modules or objects continue doc = docstring.lower() if all(w in doc for w in whats): found.append(name) # Relevance sort # XXX: this is full Harrison-Stetson heuristics now, # XXX: it probably could be improved kind_relevance = {'func': 1000, 'class': 1000, 'module': -1000, 'object': -1000} def relevance(name, docstr, kind, index): r = 0 # do the keywords occur within the start of the docstring? first_doc = "\n".join(docstr.lower().strip().split("\n")[:3]) r += sum([200 for w in whats if w in first_doc]) # do the keywords occur in the function name? r += sum([30 for w in whats if w in name]) # is the full name long? r += -len(name) 5 # is the object of bad type? r += kind_relevance.get(kind, -1000) # is the object deep in namespace hierarchy? r += -name.count('.') * 10 r += max(-index / 100, -100) return r def relevance_value(a): return relevance(a, cache[a]) found.sort(key=relevance_value) # Pretty-print s = "Search results for '%s'" % (' '.join(whats)) help_text = [s, "-"len(s)] for name in found[::-1]: doc, kind, ix = cache[name] doclines = [line.strip() for line in doc.strip().split("\n") if line.strip()] # find a suitable short description try: first_doc = doclines[0].strip() if _function_signature_re.search(first_doc): first_doc = doclines[1].strip() except IndexError: first_doc = "" help_text.append("%s\n %s" % (name, first_doc)) if not found: help_text.append("Nothing found.") # Output if output is not None: output.write("\n".join(help_text)) elif len(help_text) > 10: pager = pydoc.getpager() pager("\n".join(help_text)) else: print("\n".join(help_text)) def _lookfor_generate_cache(module, import_modules, regenerate): """ Generate docstring cache for given module. Parameters ---------- module : str, None, module Module for which to generate docstring cache import_modules : bool Whether to import sub-modules in packages. regenerate : bool Re-generate the docstring cache Returns ------- cache : dict {obj_full_name: (docstring, kind, index), ...} Docstring cache for the module, either cached one (regenerate=False) or newly generated. """ # Local import to speed up numpy's import time. import inspect from io import StringIO if module is None: module = "numpy" if isinstance(module, str): try: __import__(module) except ImportError: return {} module = sys.modules[module] elif isinstance(module, list) or isinstance(module, tuple): cache = {} for mod in module: cache.update(_lookfor_generate_cache(mod, import_modules, regenerate)) return cache if id(module) in _lookfor_caches and not regenerate: return _lookfor_caches[id(module)] # walk items and collect docstrings cache = {} _lookfor_caches[id(module)] = cache seen = {} index = 0 stack = [(module.__name__, module)] while stack: name, item = stack.pop(0) if id(item) in seen: continue seen[id(item)] = True index += 1 kind = "object" if inspect.ismodule(item): kind = "module" try: _all = item.__all__ except AttributeError: _all = None # import sub-packages if import_modules and hasattr(item, '__path__'): for pth in item.__path__: for mod_path in os.listdir(pth): this_py = os.path.join(pth, mod_path) init_py = os.path.join(pth, mod_path, '__init__.py') if (os.path.isfile(this_py) and mod_path.endswith('.py')): to_import = mod_path[:-3] elif os.path.isfile(init_py): to_import = mod_path else: continue if to_import == '__init__': continue try: old_stdout = sys.stdout old_stderr = sys.stderr try: sys.stdout = StringIO() sys.stderr = StringIO() __import__("%s.%s" % (name, to_import)) finally: sys.stdout = old_stdout sys.stderr = old_stderr except KeyboardInterrupt: # Assume keyboard interrupt came from a user raise except BaseException: # Ignore also SystemExit and pytests.importorskip # `Skipped` (these are BaseExceptions; gh-22345) continue for n, v in _getmembers(item): try: item_name = getattr(v, '__name__', "%s.%s" % (name, n)) mod_name = getattr(v, '__module__', None) except NameError: # ref. SWIG's global cvars # NameError: Unknown C global variable item_name = "%s.%s" % (name, n) mod_name = None if '.' not in item_name and mod_name: item_name = "%s.%s" % (mod_name, item_name) if not item_name.startswith(name + '.'): # don't crawl "foreign" objects if isinstance(v, ufunc): # ... unless they are ufuncs pass else: continue elif not (inspect.ismodule(v) or _all is None or n in _all): continue stack.append(("%s.%s" % (name, n), v)) elif inspect.isclass(item): kind = "class" for n, v in _getmembers(item): stack.append(("%s.%s" % (name, n), v)) elif hasattr(item, "__call__"): kind = "func" try: doc = inspect.getdoc(item) except NameError: # ref SWIG's NameError: Unknown C global variable doc = None if doc is not None: cache[name] = (doc, kind, index) return cache def _getmembers(item): import inspect try: members = inspect.getmembers(item) except Exception: members = [(x, getattr(item, x)) for x in dir(item) if hasattr(item, x)] return members def safe_eval(source): """ Protected string evaluation. Evaluate a string containing a Python literal expression without allowing the execution of arbitrary non-literal code. .. warning:: This function is identical to :py:meth:`ast.literal_eval` and has the same security implications. It may not always be safe to evaluate large input strings. Parameters ---------- source : str The string to evaluate. Returns ------- obj : object The result of evaluating `source`. Raises ------ SyntaxError If the code has invalid Python syntax, or if it contains non-literal code. Examples -------- >>> np.safe_eval('1') 1 >>> np.safe_eval('[1, 2, 3]') [1, 2, 3] >>> np.safe_eval('{"foo": ("bar", 10.0)}') {'foo': ('bar', 10.0)} >>> np.safe_eval('import os') Traceback (most recent call last): ... SyntaxError: invalid syntax >>> np.safe_eval('open("/home/user/.ssh/id_dsa").read()') Traceback (most recent call last): ... ValueError: malformed node or string: <_ast.Call object at 0x...> """ # Local import to speed up numpy's import time. import ast return ast.literal_eval(source) def _median_nancheck(data, result, axis): """ Utility function to check median result from data for NaN values at the end and return NaN in that case. Input result can also be a MaskedArray. Parameters ---------- data : array Sorted input data to median function result : Array or MaskedArray Result of median function. axis : int Axis along which the median was computed. Returns ------- result : scalar or ndarray Median or NaN in axes which contained NaN in the input. If the input was an array, NaN will be inserted in-place. If a scalar, either the input itself or a scalar NaN. """ if data.size == 0: return result potential_nans = data.take(-1, axis=axis) n = np.isnan(potential_nans) # masked NaN values are ok, although for masked the copyto may fail for # unmasked ones (this was always broken) when the result is a scalar. if np.ma.isMaskedArray(n): n = n.filled(False) if not n.any(): return result # Without given output, it is possible that the current result is a # numpy scalar, which is not writeable. If so, just return nan. if isinstance(result, np.generic): return potential_nans # Otherwise copy NaNs (if there are any) np.copyto(result, potential_nans, where=n) return result def _opt_info(): """ Returns a string contains the supported CPU features by the current build. The string format can be explained as follows: - dispatched features that are supported by the running machine end with ``. - dispatched features that are "not" supported by the running machine end with `?`. - remained features are representing the baseline. """ from numpy.core._multiarray_umath import ( __cpu_features__, __cpu_baseline__, __cpu_dispatch__ ) if len(__cpu_baseline__) == 0 and len(__cpu_dispatch__) == 0: return '' enabled_features = ' '.join(__cpu_baseline__) for feature in __cpu_dispatch__: if __cpu_features__[feature]: enabled_features += f" {feature}" else: enabled_features += f" {feature}?" return enabled_features def drop_metadata(dtype, /): """ Returns the dtype unchanged if it contained no metadata or a copy of the dtype if it (or any of its structure dtypes) contained metadata. This utility is used by `np.save` and `np.savez` to drop metadata before saving. .. note:: Due to its limitation this function may move to a more appropriate home or change in the future and is considered semi-public API only. .. warning:: This function does not preserve more strange things like record dtypes and user dtypes may simply return the wrong thing. If you need to be sure about the latter, check the result with: ``np.can_cast(new_dtype, dtype, casting="no")``. """ if dtype.fields is not None: found_metadata = dtype.metadata is not None names = [] formats = [] offsets = [] titles = [] for name, field in dtype.fields.items(): field_dt = drop_metadata(field[0]) if field_dt is not field[0]: found_metadata = True names.append(name) formats.append(field_dt) offsets.append(field[1]) titles.append(None if len(field) < 3 else field[2]) if not found_metadata: return dtype structure = dict( names=names, formats=formats, offsets=offsets, titles=titles, itemsize=dtype.itemsize) # NOTE: Could pass (dtype.type, structure) to preserve record dtypes... return np.dtype(structure, align=dtype.isalignedstruct) elif dtype.subdtype is not None: # subarray dtype subdtype, shape = dtype.subdtype new_subdtype = drop_metadata(subdtype) if dtype.metadata is None and new_subdtype is subdtype: return dtype return np.dtype((new_subdtype, shape)) else: # Normal unstructured dtype if dtype.metadata is None: return dtype # Note that `dt.str` doesn't round-trip e.g. for user-dtypes. return np.dtype(dtype.str)	36.92 KB	2026-01-20 12:58
📄 utils.pyi from ast import AST from collections.abc import Callable, Mapping, Sequence from typing import ( Any, overload, TypeVar, Protocol, ) from numpy import ndarray, generic from numpy.core.numerictypes import ( issubclass_ as issubclass_, issubdtype as issubdtype, issubsctype as issubsctype, ) _T_contra = TypeVar("_T_contra", contravariant=True) _FuncType = TypeVar("_FuncType", bound=Callable[..., Any]) # A file-like object opened in `w` mode class _SupportsWrite(Protocol[_T_contra]): def write(self, s: _T_contra, /) -> Any: ... __all__: list[str] class _Deprecate: old_name: None \| str new_name: None \| str message: None \| str def __init__( self, old_name: None \| str = ..., new_name: None \| str = ..., message: None \| str = ..., ) -> None: ... # NOTE: `__call__` can in principle take arbitrary `args` and `kwargs`, # even though they aren't used for anything def __call__(self, func: _FuncType) -> _FuncType: ... def get_include() -> str: ... @overload def deprecate( , old_name: None \| str = ..., new_name: None \| str = ..., message: None \| str = ..., ) -> _Deprecate: ... @overload def deprecate( func: _FuncType, /, old_name: None \| str = ..., new_name: None \| str = ..., message: None \| str = ..., ) -> _FuncType: ... def deprecate_with_doc(msg: None \| str) -> _Deprecate: ... # NOTE: In practice `byte_bounds` can (potentially) take any object # implementing the `__array_interface__` protocol. The caveat is # that certain keys, marked as optional in the spec, must be present for # `byte_bounds`. This concerns `"strides"` and `"data"`. def byte_bounds(a: generic \| ndarray[Any, Any]) -> tuple[int, int]: ... def who(vardict: None \| Mapping[str, ndarray[Any, Any]] = ...) -> None: ... def info( object: object = ..., maxwidth: int = ..., output: None \| _SupportsWrite[str] = ..., toplevel: str = ..., ) -> None: ... def source( object: object, output: None \| _SupportsWrite[str] = ..., ) -> None: ... def lookfor( what: str, module: None \| str \| Sequence[str] = ..., import_modules: bool = ..., regenerate: bool = ..., output: None \| _SupportsWrite[str] =..., ) -> None: ... def safe_eval(source: str \| AST) -> Any: ... def show_runtime() -> None: ...	2.3 KB	2026-01-20 12:58

Edit File:

Terminal