115 def extract(self, *patterns, **kwds):
116 """Extract a dictionary of {<name>: <column-array>} in which the field
117 names match the given shell-style glob pattern(s).
118
119 Any number of glob patterns may be passed (including none); the result
120 will be the union of all the result of each glob considered separately.
121
122 Note that extract("*", copy=True) provides an easy way to transform a
123 row-major ColumnView into a possibly more efficient set of contiguous
124 NumPy arrays.
125
126 String fields are silently ignored. Support for `Flag` columns is
127 deprecated; at present they are copied into full boolean arrays, but
128 after v26 they will be silently ignored as well.
129
130 Parameters
131 ----------
132 patterns : Array of `str`
133 List of glob patterns to use to select field names.
134 kwds : `dict`
135 Dictionary of additional keyword arguments. May contain:
136
137 ``items`` : `list`
138 The result of a call to self.schema.extract(); this will be
139 used instead of doing any new matching, and allows the pattern
140 matching to be reused to extract values from multiple records.
141 This keyword is incompatible with any position arguments and
142 the regex, sub, and ordered keyword arguments.
143 ``where`` : array index expression
144 Any expression that can be passed as indices to a NumPy array,
145 including slices, boolean arrays, and index arrays, that will
146 be used to index each column array. This is applied before
147 arrays are copied when copy is True, so if the indexing results
148 in an implicit copy no unnecessary second copy is performed.
149 ``copy`` : `bool`
150 If True, the returned arrays will be contiguous copies rather
151 than strided views into the catalog. This ensures that the
152 lifetime of the catalog is not tied to the lifetime of a
153 particular catalog, and it also may improve the performance if
154 the array is used repeatedly. Default is False.
155 ``regex`` : `str` or `re` pattern
156 A regular expression to be used in addition to any glob
157 patterns passed as positional arguments. Note that this will
158 be compared with re.match, not re.search.
159 ``sub`` : `str`
160 A replacement string (see re.MatchObject.expand) used to set
161 the dictionary keys of any fields matched by regex.
162 ``ordered`` : `bool`
163 If True, a collections.OrderedDict will be returned instead of
164 a standard dict, with the order corresponding to the definition
165 order of the Schema. Default is False.
166
167 Returns
168 -------
169 d : `dict`
170 Dictionary of extracted name-column array sets.
171
172 Raises
173 ------
174 ValueError
175 Raised if a list of ``items`` is supplied with additional keywords.
176 """
177
178
179 copy = kwds.pop("copy", False)
180 where = kwds.pop("where", None)
181 d = kwds.pop("items", None)
182
183
184
185 if d is None:
186 d = self.schema.extract(*patterns, **kwds).copy()
187 elif kwds:
188 raise ValueError(
189 "kwd 'items' was specified, which is not compatible with additional keywords")
190
191 def processArray(a):
192 if where is not None:
193 a = a[where]
194 if copy:
195 a = np.ascontiguousarray(a)
196 return a
197
198
199 for name, schemaItem in list(d.items()):
200 key = schemaItem.key
201 if key.getTypeString() == "String":
202 del d[name]
203 else:
204 d[name] = processArray(self.get(schemaItem.key))
205 return d
