Package: attensors
Using attrs and numpy to define clear data structures containing multiple tensors.OverviewAttensors was born out of the need to work with multiple input data for machine learning models, while keeping things tidy and having self-documented code.Working with mixed input data, we know theshapeof each tensor component of a single input. This is often times found specified in intermediary preprocessing or data loading mechanisms (e.g. dataset schemas, tensor specs). All these tensors would eventually gain the same"prefix" shapereferring global dimensions (such as abatch_sizeor asequence_size).As problems and models get more complicated, so, too, do their inputs. These collections of input tensors are almost never defined as separate entities, instead being grouped in generic data structures such as dictionaries, lists or tuples.Through this package we propose the combined usage ofattrsandnumpy's structured arrays to provide easy definition of tensor collections and intuitive means to work with them.Furthermore, we can also make use of type hints (specificallyAnnotated) to provide the metadata describing the tensors' dtypes and shapes.Quick exampleIn general, the minimum types we need to import are thetensorsdecorator from our package andAnnotatedfrom typing if we plan to define fields via annotations.fromattensorsimporttensorsfromtypingimportAnnotatedIf we were to take for example the New York Real Estate Data as inthistutorial, there are multiple ways we could define our multi-tensor:# Following the tutorial, 2 tensors are needed:# one for image data, one for tabular data@tensorsclassNYRealEstateData:image:Annotated[np.ndarray,{"dtype":np.float32,"shape":(3,224,224)}]tabular:Annotated[np.ndarray,{"dtype":np.float32,"shape":(5,)}]# If we'd encode each scalar feature separately, we could define it as such@tensorsclassNYRealEstateData:image:Annotated[np.ndarray,{"dtype":np.float32,"shape":(3,224,224)}]latitude:floatlongitude:floatzpid:intbeds:intbaths:int# We could also group latitude and longitude separately and nest types@tensorsclassCoordinates:latitude:floatlongitude:float@tensorsclassNYRealEstateData:image:Annotated[np.ndarray,{"dtype":np.float32,"shape":(3,224,224)}]location:Coordinateszpid:intbeds:intbaths:intInstantiating can be done by simply providing the data, or via numpy styled routines. In the following contexts we consider the first definition provided above and 2 samples given with their respective tensorsi1,t1andi2,t2.>>>sample=NYRealEstateData(image=[i1,i2],tabular=[t1,t2])SinceNYRealEstateDatais actually anumpy.ndarraysubclass, you could also define using numpy>>>sample=np.array([(i1,t1),(i2,t2)],dtype=NYRealEstateData._dtype).view(NYRealEstateData)Generating dummy data can be accomplished via shortcutted numpy routines.>>>sample=NYRealEstateData.empty((2,))All above examples will result in a sample with a prefix shape of (2,).>>> sample.shape
(2,)
>>> sample.image.shape
(2,3,224,224)
>>> sample.tabular.shape
(2,5)Of course, indexing,universal functionsand classic array manipulation routines such asreshape,stack,concatenateare also supported.
You can read more about this in thedocumentation.DocumentationType DefinitionTensorsis the baseclass used for defining tensor collection types. It is created as a subclass of numpy'sndarray, using the functionality of structured arrays. On top of this, some specific rules are implemented to handle broadcasting, universal functions and shortcutting some numpy routines given the underlying dtype definition given by provided attributes.DefiningTensorstypes is done via the@tensorsdecorator which is a wrapper over attrs'@define.
The decorator provides the same functionality, however it also subclasses the decorated class fromTensors.All arguments available for@defineare forwarded, with the exception of the following:slots: forced to False due to Tensors being a subclass of np.ndarrayinit: forced to False due to Tensors having a dedicated constructor which
handles expected attr wrapped subclasseson_setattr: makes sure setting attributes are mapped to the underlying np.ndarray fields.
Adding more is possible as attrs supports thisfield_transformer: default field transformer to translate annotated fields to metadata.
Adding more is possible and works in the same manner as on_setattrUsing this decorator will also translate annotated fields to metadata.
Annotated fields are expected to have a dictionary metadata withdtypeandshapedefined.If fields are defined through type hints, but not usingAnnotatedthe type will be considered as the dtype of the underlying tensor and it's shape will be ().Fields can also be defined using attrs'fieldfunction.InstantiationDirectly instantiating Tensors is possible. In this case, you provide the fields and values
you want as keyword arguments. Eithershapeordtypemust be provided. Providing one
will cause the other to be inferred.If onlyshapeis provided, this will be considered the shape of the instance, which must
prefix all included tensors shapes. Thedtypewill be inferred based on the provided values.
If onlydtypeis provided, the instance'sshapewill be considered () as long asmc_shapeis False. Ifmc_shapeis set to True, the instance'sshapewill be computed as the
maximum common shape amongst the provided values, while respecting the provideddtype.Providing both is exhaustive and will cause validation of the providedshapeasdtypetakes precedence.Argumentsshape,dtype,mc_shapeare NOT available for subclasses of Tensors.
Instead, the dtype is inferred from the class fields information (type and metadata).Indexing and attributesClasses defined with@tensors, in the style of attrs, will provide attributes corresponding to the underlying ndarray structured array fields. Besides this, classic ndarray attributes such asshapeanddtypewill also be available. Types defined with the decorator will also contain a_dtypeattribute corresponding to the inferred numpy dtype, which is used upon instantiation.Indexing works in the same manner as it does with structured numpy arrays, however some type casting may occur, in the following manner:Any indexing that would result in an unstructured array will be cast to ndarrayAny indexing that would result in a structured array which has a different dtype than the class, will be cast to TensorsAny indexing that would extract a single element (type numpy.void) will be cast to the source class.Broadcast rulesAdditional broadcasting rules have been implemented through the class methodbroadcast_tensors.Tensorstypes cannot be broadcast together unless they have the same field identifiers.Scalars and non-structured ndarrays broadcast withTensorstypes will be brought to that type's structure by broadcasting independently with each tensor component.Tensorswith the same fields will broadcast the base shape of each coresponding component and then also broadcast the prefix shape as well.Universal functionsNumpy provides an API for the multitude of mathematical operations viauniversal functions. However, these do not work for structured arrays, perahps due to the impossibility to define a universal standard approach for these.In this package, universal functions are implemented for given types that can be broadcast following the above rules and will work as such:Any universal function called onTensorstypes will essentially be called on each underlying tensor component.The result(s) will be one or moreTensorstypes, having the same field identifiers, resulting dtypes based on the operation and broadcast shapes.