This is the Select Reference Manual, version 1.0.0, generated automatically by Declt version 4.0b2.
Copyright © 2019-2022 Steve Nunez
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled “Copying” is included exactly as in the original.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be translated as well.
This program is distributed under the terms of the Microsoft Public License.
Select is a library for taking slices from array-like objects. The most frequently used form is:
(select object selection1 selection2 ...)
where each selection specifies a set of subscripts along the corresponding axis. The selection specifications are found below.
A non-negative integer selects the corresponding index, while a negative integer selects an index counting backwards from the last index. For example:
(select #(0 1 2 3) 1) ; => 1 (select #(0 1 2 3) -2) ; => 2
These are called singleton slices. Each singleton slice drops the dimension: vectors become atoms, matrices become vectors, etc..
(range start end) selects subscripts i where start <= i <
end. When end is nil, the last index is included (cf. subseq). Each
boundary is resolved according to the other rules if applicable, so
you can use negative integers:
(select #(0 1 2 3) (range 1 3)) ; => #(1 2) (select #(0 1 2 3) (range 1 -1)) ; => #(1 2)
t selects all subscripts:
(select #2A((0 1 2)
(3 4 5))
t 1) ; => #(1 4)
Sequences can be used to make specific selections from the object. For example:
(select #(0 1 2 3 4 5 6 7 8 9) (vector (range 1 3) 6 (range -2 -1))) ; => #(1 2 3 6 8 9) (select #(0 1 2) '(2 2 1 0 0)) ; => #(2 2 1 0 0)
Bit vectors can be used to select elements of arrays and sequences as well:
(select #(0 1 2 3 4) #*00110) ; => #(2 3)
Section 1.1 describes the core functionality. The semantics can be extended, as you will see in the next section. The extensions in this section are provided by the library and prove useful in practice. Their implementation provides good examples of extending the library.
including is convenient if you want the selection to include
the end of the range:
(select #(0 1 2 3) (including 1 2))
; => #(1 2), cf. (select ... (range 1 3))
nodrop is useful if you do not want to drop dimensions:
(select #(0 1 2 3) (nodrop 2))
; => #(2), cf. (select ... (range 2 3))
head and tail do the obvious:
(select #(0 1 2 3) (head 2)) ; => #(0 1) (select #(0 1 2 3) (tail 2)) ; => #(2 3)
All of these are trivial to implement. If there is something you are
missing, you can easily extend select. Pull request are welcome.
ref is a version of select that always returns a single
element, so it can only be used with singleton slices.
Arguments of select, except the first one, are meant to be
resolved using canonical-representation, in the
select-dev package. If you want to extend select, you
should define methods for canonical-representation. See the
source code for the best examples. Below is a simple example that
extends the semantics with ordinal numbers.
(defmacro define-ordinal-selection (number)
(check-type number (integer 0))
`(defmethod select-dev:canonical-representation
((axis integer)
(slice (eql ',(intern (format nil \"~:@(~:r~)\" number)))))
(assert (< ,number axis))
(select-dev:canonical-singleton ,number)))
(define-ordinal-selection 1)
(define-ordinal-selection 2)
(define-ordinal-selection 3)
(select #(0 1 2 3 4 5) (range 'first 'third)) ; => #(1 2)
Note the following:
canonical-representation needs to be
constructed using canonical-singleton, canonical-range,
or canonical-sequence. You should not use the internal
representation directly as it is subject to change.
axis is an integer: this is the default. An
object may define a more complex mapping (such as, for example, named
rows & columns), but unless a method specialized to that is found,
canonical-representation will just query its dimension (with
axis-dimension) and try to find a method that works on
integers.
The main system appears first, followed by any subsystem dependency.
DSL for array and data-frame slices
Slicing for Data Frames
Steve Nunez <steve@symbolics.tech>
(GIT git://github.com/Lisp-Stat/select)
MS-PL
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.
1.0.0
Files are sorted by type and then listed depth-first from the systems components trees.
package.lisp (file).
select (system).
select-dev.lisp (file).
select (system).
Packages are listed by definition order.
SELECT is a facility for selecting portions of sequences or arrays.
slct
SELECT-DEV is used to implement SELECT operations on data structures other than arrays.
Definitions are sorted by export status, category, package, and then by lexicographic order.
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.
Test if all canonical representations are singletons.
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
Return the canonical representations of SELECTIONS given the corresponding AXES, checking for matching length.
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.
Canonical representation of a singleton index (a nonnegative integer, which is a valid array index).
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.
Range, including both ends.
Select a single index, but do not drop a dimension.
Range, including START, excluding END.
Return a list for the dimensions of canonical representations, dropping singletons.
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.
Test if SYMBOL has special semantics for SELECTION.
Test if a canonical REPRESENTATION is a singleton.
Return the dimension of axis. Needs to be defined for non-integer axes.
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.
The canonical representation for NODROP.
The canonical representation for RANGE.
The canonical representation for INCLUDING.
Map sequence into a simple-bit-vector, using 1 when PREDICATE yields true, 0 otherwise.
Return the element of OBJECT specified by SUBSCRIPTS.
Stores VALUE into the place specified by SUBSCRIPTS.
Return the slices of OBJECT specified by SELECTIONS.
Stores VALUES into the locations given by SELECTIONS.
Return an index of the positions in SEQUENCE which satisfy PREDICATE. Defaults to return non-NIL indices.
Canonical representation of a contiguous set of array indices from START (inclusive) to END (exclusive).
Canonical representation of a sequence of array indexes.
structure-object.
common-lisp.
(simple-array alexandria:array-index (*))
Range, including both ends.
Select a single index, but don’t drop a dimension.
structure-object.
Range, including start, excluding end.
end.
end.
end.
Return the dimension of a canonical-representation, or NIL for singleton selections (they are dropped).
Initial value for iteration.
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.
select was originally called slice and written by Tamas K. Papp. Since it was abandoned in 2017, I have taken it over to be part of a rebooted Common Lisp statistics library. Changes in this version include:
| Jump to: | (
A C F G I M N R S T W |
|---|
| Jump to: | (
A C F G I M N R S T W |
|---|
| Jump to: | E I S V |
|---|
| Jump to: | E I S V |
|---|
| Jump to: | C F I N P R S |
|---|
| Jump to: | C F I N P R S |
|---|