The select Reference Manual

This is the select Reference Manual, version 1.2.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Dec 08 19:32:54 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 select

DSL for array and data-frame slices

Long Name

Slicing and selection library for Data Frames

Author

Steve Nunez <>

Home Page

https://lisp-stat.dev/docs/manuals/select

Source Control

(GIT git://github.com/Lisp-Stat/select)

Bug Tracker

https://github.com/Lisp-Stat/select/issues/

License

MS-PL

Long Description

Select is a facility for selecting portions of sequences, arrays or data-frames. It provides:

An API for taking slices (elements selected by the Cartesian product of vectors of subscripts for each axis) of array-like objects. The most important function is ‘select‘. Unless you want to define additional methods for ‘select‘, this is pretty much all you need from this library. See the documentation at https://lisp-stat.github.io/select/ for a tutorial.

An extensible DSL for selecting a subset of valid subscripts. This is useful if, for example, you want to resolve column names in a data frame in your implementation of slice.

A set of utility functions for traversing slices in array-like objects.

Version

1.2.0

Dependencies
  • alexandria (system).
  • alexandria+ (system).
  • anaphora (system).
  • let-plus (system).
Source

select.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 select/select.asd

Source

select.asd.

Parent Component

select (system).

ASDF Systems

select.


3.1.2 select/pkgdcl.lisp

Source

select.asd.

Parent Component

select (system).

Packages

3.1.3 select/select-dev.lisp

Dependency

pkgdcl.lisp (file).

Source

select.asd.

Parent Component

select (system).

Public Interface
Internals

3.1.4 select/select.lisp

Dependency

select-dev.lisp (file).

Source

select.asd.

Parent Component

select (system).

Public Interface
Internals

3.1.5 select/sample.lisp

Dependency

select.lisp (file).

Source

select.asd.

Parent Component

select (system).

Public Interface

sample (generic function).

Internals

4 Packages

Packages are listed by definition order.


4.1 select-dev

SELECT-DEV is used to implement SELECT operations on data structures other than arrays.

Source

pkgdcl.lisp.

Use List
  • alexandria.
  • alexandria+.
  • anaphora.
  • common-lisp.
  • let-plus.
Used By List

select.

Public Interface
Internals

4.2 select

SELECT is a facility for selecting portions of sequences or arrays.

Source

pkgdcl.lisp.

Nickname

slct

Use List
  • alexandria.
  • alexandria+.
  • anaphora.
  • common-lisp.
  • let-plus.
  • select-dev.
Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Macros

Macro: traverse-representations ((subscripts representations &key index setup) &body body)

Loops over all possible subscripts in REPRESENTAITONS, making them available in SUBSCRIPTS during the execution of BODY. The iterator is constructed using the function SETUP (see for example ROW-MAJOR-SETUP). When INDEX is given, a variable with that name is provided, containing an index that counts iterations.

Package

select-dev.

Source

select-dev.lisp.


5.1.2 Ordinary functions

Function: all-singleton-representations? (representations)

Test if all canonical representations are singletons.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-range (start end)

Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-representations (axes selections)

Return the canonical representations of SELECTIONS given the corresponding AXES, checking for matching length.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-sequence (sequence)

Canonical representation of array indexes from canonical-sequence SEQUENCE.

May share structure. Vectors of the upgraded type of (SIMPLE-ARRAY ARRAY-INDEX (*)) are preferred for efficiency, otherwise they are coerced.

Package

select-dev.

Source

select-dev.lisp.

Function: canonical-singleton (index)

Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).

Package

select-dev.

Source

select-dev.lisp.

Function: column-major-setup (representations terminator)

Return SUBSCRIPTS (a list) and ITERATOR (a closure, no arguments) that increments the contents of SUBSCRIPTS in column-major order. TERMINATOR is called when all subscripts have been visited.

Package

select-dev.

Source

select-dev.lisp.

Function: including (start end)

Range, including both ends.

Package

select.

Source

select.lisp.

Function: nodrop (index)

Select a single index, but do not drop a dimension.

Package

select.

Source

select.lisp.

Function: range (start end)

Range, including START, excluding END.

Package

select.

Source

select.lisp.

Function: representation-dimensions (representations)

Return a list for the dimensions of canonical representations, dropping singletons.

Package

select-dev.

Source

select-dev.lisp.

Function: row-major-setup (representations terminator)

Return SUBSCRIPTS (a list) and ITERATOR (a closure, no arguments) that increments the contents of SUBSCRIPTS in row-major order. TERMINATOR is called when all subscripts have been visited.

Package

select-dev.

Source

select-dev.lisp.

Function: select-reserved-symbol? (symbol)

Test if SYMBOL has special semantics for SELECTION.

Package

select-dev.

Source

select-dev.lisp.

Function: singleton-representation? (representation)

Test if a canonical REPRESENTATION is a singleton.

Package

select-dev.

Source

select-dev.lisp.


5.1.3 Generic functions

Generic Function: axis-dimension (axis)

Return the dimension of axis. Needs to be defined for non-integer axes.

Package

select-dev.

Source

select-dev.lisp.

Generic Function: canonical-representation (axis selection)

Canonical representation of SELECTION, given information in AXIS. The default methods use dimensions as AXIS.

Each selection needs to be resolved into a canonical representation, which is either a singleton, a range, or a sequence of subscripts. They should only be constructed with the corresponding CANONICAL-SINGLETION, CANONICAL-RANGE and CANONICAL-SEQUENCE functions.

@c(CANONICAL-REPRESENTATION) needs to ensure that the represented subscripts are valid for the axis.

Unless a specialized method is found, the dimension of the axis is queried with AXIS-DIMENSION and resolution is attempted using the latter. Methods that resolve symbols should test them with SELECT-RESERVED-SYMBOL? and use CALL-NEXT-METHOD.

Package

select-dev.

Source

select-dev.lisp.

Methods
Method: canonical-representation (axis (selection nodrop))

The canonical representation for NODROP.

Source

select.lisp.

Method: canonical-representation (axis (selection range))

The canonical representation for RANGE.

Source

select.lisp.

Method: canonical-representation (axis (selection including))

The canonical representation for INCLUDING.

Source

select.lisp.

Method: canonical-representation (axis selection)
Method: canonical-representation (axis (canonical-range canonical-range))
Method: canonical-representation (axis (canonical-sequence canonical-sequence))
Method: canonical-representation ((axis integer) (slice null))
Method: canonical-representation ((axis integer) (selection integer))
Method: canonical-representation (axis (selection sequence))
Method: canonical-representation ((axis integer) (selection (eql t)))
Method: canonical-representation (axis (selection bit-vector))
Generic Function: mask (sequence predicate)

Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.

Package

select.

Source

select.lisp.

Methods
Method: mask ((sequence sequence) predicate)
Generic Function: ref (object &rest subscripts)

Return the element of OBJECT specified by SUBSCRIPTS.

Package

select.

Source

select.lisp.

Methods
Method: ref ((array array) &rest subscripts)
Generic Function: (setf ref) (object &rest subscripts)

Stores VALUE into the place specified by SUBSCRIPTS.

Package

select.

Source

select.lisp.

Methods
Method: (setf ref) ((array array) &rest subscripts)
Generic Function: sample (data n &key with-replacement skip-unselected)

Return a random sample of SEQ of size N.

If WITH-REPLACEMENT is true, return a random sample with
replacement (a "draw").

If WITH-REPLACEMENT is false, return a random sample without
replacement (a "deal").

If SKIP-UNSELECTED is non-NIL, do not return the elements of DF that we not part of the selection. Non-NIL by default, as the typical use case is to split a data set into training and test data sets.

Package

select.

Source

sample.lisp.

Methods
Method: sample ((seq cons) n &key with-replacement skip-unselected)
Method: sample ((seq vector) n &key with-replacement skip-unselected)
Method: sample ((arr array) n &key with-replacement skip-unselected)
Generic Function: select (object &rest selections)

Return the slices of OBJECT specified by SELECTIONS.

Package

select.

Source

select.lisp.

Methods
Method: select ((lst list) &rest selections)

Select from LST the subscripts or range specified in SELECTIONS. SELECTIONS must be a VECTOR, LIST or RANGE.

Method: select ((array array) &rest selections)

Return the SELECTIONS in the given ARRAY.

Generic Function: (setf select) (object &rest selections)

Stores VALUES into the locations given by SELECTIONS.

Package

select.

Source

select.lisp.

Methods
Method: (setf select) ((array array) &rest selections)
Method: (setf select) ((array array) &rest selections)
Generic Function: which (sequence &key predicate)

Return an index of the positions in SEQUENCE which satisfy PREDICATE. Defaults to return non-NIL indices.

Package

select.

Source

select.lisp.

Methods
Method: which ((sequence sequence) &key predicate)

5.1.4 Structures

Structure: canonical-range

Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).

Package

select-dev.

Source

select-dev.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Type

alexandria:array-index

Readers

canonical-range-start.

Writers

(setf canonical-range-start).

Slot: end
Type

alexandria:array-index

Readers

canonical-range-end.

Writers

(setf canonical-range-end).

Structure: canonical-sequence

Canonical representation of a sequence of array indexes.

Package

select-dev.

Source

select-dev.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: vector
Package

common-lisp.

Type

(simple-array alexandria:array-index (*))

Readers

canonical-sequence-vector.

Writers

(setf canonical-sequence-vector).

Structure: including

Range, including both ends.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Readers

including-start.

Writers

(setf including-start).

Slot: end
Readers

including-end.

Writers

(setf including-end).

Structure: nodrop

Select a single index, but don’t drop a dimension.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: index
Readers

nodrop-index.

Writers

(setf nodrop-index).

Structure: range

Range, including start, excluding end.

Package

select.

Source

select.lisp.

Direct superclasses

structure-object.

Direct methods

canonical-representation.

Direct slots
Slot: start
Readers

range-start.

Writers

(setf range-start).

Slot: end
Readers

range-end.

Writers

(setf range-end).


5.2 Internals


5.2.1 Constants

Constant: +alpha+

The parameter that decides whether to use method A or method D. Typical values of α are in the range 0.05-0.15.

Package

select.

Source

sample.lisp.


5.2.2 Ordinary functions

Reader: canonical-range-end (instance)
Writer: (setf canonical-range-end) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

end.

Function: canonical-range-p (object)
Package

select-dev.

Source

select-dev.lisp.

Reader: canonical-range-start (instance)
Writer: (setf canonical-range-start) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

start.

Function: canonical-sequence-p (object)
Package

select-dev.

Source

select-dev.lisp.

Reader: canonical-sequence-vector (instance)
Writer: (setf canonical-sequence-vector) (instance)
Package

select-dev.

Source

select-dev.lisp.

Target Slot

vector.

Function: collect-sample (seq index-array)
Package

select.

Source

sample.lisp.

Function: copy-canonical-range (instance)
Package

select-dev.

Source

select-dev.lisp.

Function: copy-canonical-sequence (instance)
Package

select-dev.

Source

select-dev.lisp.

Function: copy-including (instance)
Package

select.

Source

select.lisp.

Function: copy-nodrop (instance)
Package

select.

Source

select.lisp.

Function: copy-range (instance)
Package

select.

Source

select.lisp.

Function: generate-index-array (n len)
Package

select.

Source

sample.lisp.

Function: generate-index-array/replacement (n len)
Package

select.

Source

sample.lisp.

Function: head (count)

First COUNT indexes.

Package

select.

Source

select.lisp.

Reader: including-end (instance)
Writer: (setf including-end) (instance)
Package

select.

Source

select.lisp.

Target Slot

end.

Function: including-p (object)
Package

select.

Source

select.lisp.

Reader: including-start (instance)
Writer: (setf including-start) (instance)
Package

select.

Source

select.lisp.

Target Slot

start.

Function: make-canonical-range (&key start end)
Package

select-dev.

Source

select-dev.lisp.

Function: make-canonical-sequence (&key vector)
Package

select-dev.

Source

select-dev.lisp.

Function: make-including (&key start end)
Package

select.

Source

select.lisp.

Function: make-nodrop (&key index)
Package

select.

Source

select.lisp.

Function: make-range (&key start end)
Package

select.

Source

select.lisp.

Function: map-random-below (fn n len)

Generate N random indices for a sequence of length LEN, in ascending order, calling FN on each index as it is generated.

Package

select.

Source

sample.lisp.

Reader: nodrop-index (instance)
Writer: (setf nodrop-index) (instance)
Package

select.

Source

select.lisp.

Target Slot

index.

Function: nodrop-p (object)
Package

select.

Source

select.lisp.

Reader: range-end (instance)
Writer: (setf range-end) (instance)
Package

select.

Source

select.lisp.

Target Slot

end.

Function: range-p (object)
Package

select.

Source

select.lisp.

Reader: range-start (instance)
Writer: (setf range-start) (instance)
Package

select.

Source

select.lisp.

Target Slot

start.

Function: representation-dimension (representation)

Return the dimension of a canonical-representation, or NIL for singleton selections (they are dropped).

Package

select-dev.

Source

select-dev.lisp.

Function: representation-initial-value (representation)

Initial value for iteration.

Package

select-dev.

Source

select-dev.lisp.

Function: representation-iterator (representation carry cons)

Return a closure that sets the car of CONS to the next value each time it is called, resetting and calling CARRY when it reaches the end of its range.

Package

select-dev.

Source

select-dev.lisp.

Function: tail (count)

Last COUNT indexes.

Package

select.

Source

select.lisp.

Function: uniformrv ()
Package

select.

Source

sample.lisp.

Function: vitter-method-a (fn n not-processed)

Vitter’s Method A.

Mostly faithful to Vitter’s Pascal code, but uses advanced Common Lisp features like exponents and subtraction.

Package

select.

Source

sample.lisp.

Function: vitter-method-d (fn n not-processed)

Vitter’s Method D

Package

select.

Source

sample.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   F   G   H   I   M   N   R   S   T   U   V   W  
Index Entry  Section

(
(setf canonical-range-end): Private ordinary functions
(setf canonical-range-start): Private ordinary functions
(setf canonical-sequence-vector): Private ordinary functions
(setf including-end): Private ordinary functions
(setf including-start): Private ordinary functions
(setf nodrop-index): Private ordinary functions
(setf range-end): Private ordinary functions
(setf range-start): Private ordinary functions
(setf ref): Public generic functions
(setf ref): Public generic functions
(setf select): Public generic functions
(setf select): Public generic functions
(setf select): Public generic functions

A
all-singleton-representations?: Public ordinary functions
axis-dimension: Public generic functions

C
canonical-range: Public ordinary functions
canonical-range-end: Private ordinary functions
canonical-range-p: Private ordinary functions
canonical-range-start: Private ordinary functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representation: Public generic functions
canonical-representations: Public ordinary functions
canonical-sequence: Public ordinary functions
canonical-sequence-p: Private ordinary functions
canonical-sequence-vector: Private ordinary functions
canonical-singleton: Public ordinary functions
collect-sample: Private ordinary functions
column-major-setup: Public ordinary functions
copy-canonical-range: Private ordinary functions
copy-canonical-sequence: Private ordinary functions
copy-including: Private ordinary functions
copy-nodrop: Private ordinary functions
copy-range: Private ordinary functions

F
Function, (setf canonical-range-end): Private ordinary functions
Function, (setf canonical-range-start): Private ordinary functions
Function, (setf canonical-sequence-vector): Private ordinary functions
Function, (setf including-end): Private ordinary functions
Function, (setf including-start): Private ordinary functions
Function, (setf nodrop-index): Private ordinary functions
Function, (setf range-end): Private ordinary functions
Function, (setf range-start): Private ordinary functions
Function, all-singleton-representations?: Public ordinary functions
Function, canonical-range: Public ordinary functions
Function, canonical-range-end: Private ordinary functions
Function, canonical-range-p: Private ordinary functions
Function, canonical-range-start: Private ordinary functions
Function, canonical-representations: Public ordinary functions
Function, canonical-sequence: Public ordinary functions
Function, canonical-sequence-p: Private ordinary functions
Function, canonical-sequence-vector: Private ordinary functions
Function, canonical-singleton: Public ordinary functions
Function, collect-sample: Private ordinary functions
Function, column-major-setup: Public ordinary functions
Function, copy-canonical-range: Private ordinary functions
Function, copy-canonical-sequence: Private ordinary functions
Function, copy-including: Private ordinary functions
Function, copy-nodrop: Private ordinary functions
Function, copy-range: Private ordinary functions
Function, generate-index-array: Private ordinary functions
Function, generate-index-array/replacement: Private ordinary functions
Function, head: Private ordinary functions
Function, including: Public ordinary functions
Function, including-end: Private ordinary functions
Function, including-p: Private ordinary functions
Function, including-start: Private ordinary functions
Function, make-canonical-range: Private ordinary functions
Function, make-canonical-sequence: Private ordinary functions
Function, make-including: Private ordinary functions
Function, make-nodrop: Private ordinary functions
Function, make-range: Private ordinary functions
Function, map-random-below: Private ordinary functions
Function, nodrop: Public ordinary functions
Function, nodrop-index: Private ordinary functions
Function, nodrop-p: Private ordinary functions
Function, range: Public ordinary functions
Function, range-end: Private ordinary functions
Function, range-p: Private ordinary functions
Function, range-start: Private ordinary functions
Function, representation-dimension: Private ordinary functions
Function, representation-dimensions: Public ordinary functions
Function, representation-initial-value: Private ordinary functions
Function, representation-iterator: Private ordinary functions
Function, row-major-setup: Public ordinary functions
Function, select-reserved-symbol?: Public ordinary functions
Function, singleton-representation?: Public ordinary functions
Function, tail: Private ordinary functions
Function, uniformrv: Private ordinary functions
Function, vitter-method-a: Private ordinary functions
Function, vitter-method-d: Private ordinary functions

G
generate-index-array: Private ordinary functions
generate-index-array/replacement: Private ordinary functions
Generic Function, (setf ref): Public generic functions
Generic Function, (setf select): Public generic functions
Generic Function, axis-dimension: Public generic functions
Generic Function, canonical-representation: Public generic functions
Generic Function, mask: Public generic functions
Generic Function, ref: Public generic functions
Generic Function, sample: Public generic functions
Generic Function, select: Public generic functions
Generic Function, which: Public generic functions

H
head: Private ordinary functions

I
including: Public ordinary functions
including-end: Private ordinary functions
including-p: Private ordinary functions
including-start: Private ordinary functions

M
Macro, traverse-representations: Public macros
make-canonical-range: Private ordinary functions
make-canonical-sequence: Private ordinary functions
make-including: Private ordinary functions
make-nodrop: Private ordinary functions
make-range: Private ordinary functions
map-random-below: Private ordinary functions
mask: Public generic functions
mask: Public generic functions
Method, (setf ref): Public generic functions
Method, (setf select): Public generic functions
Method, (setf select): Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, canonical-representation: Public generic functions
Method, mask: Public generic functions
Method, ref: Public generic functions
Method, sample: Public generic functions
Method, sample: Public generic functions
Method, sample: Public generic functions
Method, select: Public generic functions
Method, select: Public generic functions
Method, which: Public generic functions

N
nodrop: Public ordinary functions
nodrop-index: Private ordinary functions
nodrop-p: Private ordinary functions

R
range: Public ordinary functions
range-end: Private ordinary functions
range-p: Private ordinary functions
range-start: Private ordinary functions
ref: Public generic functions
ref: Public generic functions
representation-dimension: Private ordinary functions
representation-dimensions: Public ordinary functions
representation-initial-value: Private ordinary functions
representation-iterator: Private ordinary functions
row-major-setup: Public ordinary functions

S
sample: Public generic functions
sample: Public generic functions
sample: Public generic functions
sample: Public generic functions
select: Public generic functions
select: Public generic functions
select: Public generic functions
select-reserved-symbol?: Public ordinary functions
singleton-representation?: Public ordinary functions

T
tail: Private ordinary functions
traverse-representations: Public macros

U
uniformrv: Private ordinary functions

V
vitter-method-a: Private ordinary functions
vitter-method-d: Private ordinary functions

W
which: Public generic functions
which: Public generic functions