ntv-numpy.ntv_numpy.xndarray

  1# -*- coding: utf-8 -*-
  2"""
  3@author: Philippe@loco-labs.io
  4
  5The `xndarray` module is part of the `ntv-numpy.ntv_numpy` package ([specification document](
  6https://loco-philippe.github.io/ES/JSON%20semantic%20format%20(JSON-NTV).htm)).
  7
  8It contains the classes `Xndarray` for the labeled multidimensional array.
  9
 10For more information, see the
 11[user guide](https://loco-philippe.github.io/ntv-numpy/docs/user_guide.html)
 12 or the [github repository](https://github.com/loco-philippe/ntv-numpy).
 13"""
 14
 15import json
 16from json_ntv import Ntv
 17from ntv_numpy.ndarray import Ndarray, Nutil, NdarrayError
 18
 19
 20class Xndarray:
 21    ''' Representation of a labelled multidimensional Array
 22
 23    *Attributes :*
 24    - **name** :  string - name of the Xndarray
 25    - **add_name** :  string - additional name of the Xndarray
 26    - **nda**: Ndarray - ndarray data
 27    - **links**: list of string - links to other Xndarray
 28    - **meta** : JsonValue - informations
 29
 30    *dynamic values (@property)*
 31    - `darray`
 32    - `ndarray`
 33    - `uri`
 34    - `shape`
 35    - `ntv_type`
 36    - `info`
 37    - `mode`
 38    - `xtype`
 39    - `full_name`
 40    - `json_name`
 41
 42    *methods*
 43    - `to_json`
 44    - `read_json (static method)`
 45    - `set_ndarray`
 46    '''
 47
 48    def __init__(self, full_name, nda=None, links=None,
 49                 meta=None):
 50        '''Xndarray constructor.
 51
 52        *Parameters*
 53
 54        - **full_name**: string (default None) - name with additional name
 55        - **nda** : Ndarray (default None) - data
 56        - **links**: List of string (default None) - dims or other names of associated Xndarray
 57        - **ntv_type**: string (default None) - ntv_type to apply to data
 58        - **meta**: dict (default None) - information
 59        '''
 60        if isinstance(full_name, Xndarray):
 61            self.name = full_name.name
 62            self.add_name = full_name.add_name
 63            self.nda = full_name.nda
 64            self.links = full_name.links
 65            self.meta = full_name.meta
 66            return
 67        self.name, self.add_name = Nutil.split_name(full_name)
 68        self.nda = Ndarray(nda) if not nda is None else None
 69        self.links = links if links else None
 70        self.meta = meta if meta else None
 71        if self.meta is None and self.nda is None:
 72            raise NdarrayError('A Xndarray has to have metadata or Ndarray')
 73
 74    def __repr__(self):
 75        '''return classname and number of value'''
 76        return self.__class__.__name__ + '[' + self.full_name + ']'
 77
 78    def __str__(self):
 79        '''return json string format'''
 80        return json.dumps(self.to_json())
 81
 82    def __eq__(self, other):
 83        ''' equal if attributes are equal'''
 84        if self.name != other.name or self.add_name != other.add_name:
 85            return False
 86        if self.links != other.links or self.meta != other.meta:
 87            return False
 88        if self.nda is None and other.nda is None:
 89            return True
 90        if self.nda is None or other.nda is None:
 91            return False
 92        return self.nda == other.nda
 93
 94    def __len__(self):
 95        ''' len of ndarray'''
 96        return len(self.nda) if self.nda is not None else 0
 97
 98    def __contains__(self, item):
 99        ''' item of ndarray values'''
100        return item in self.nda if self.nda is not None else None
101
102    def __getitem__(self, ind):
103        ''' return ndarray value item'''
104        if self.nda is None:
105            return None
106        if isinstance(ind, tuple):
107            return [self.nda[i] for i in ind]
108        return self.nda[ind]
109
110    def __copy__(self):
111        ''' Copy all the data '''
112        return self.__class__(self)
113
114    @property
115    def darray(self):
116        '''return the darray of the ndarray'''
117        return self.nda.darray if self.nda is not None else None
118
119    @property
120    def ndarray(self):
121        '''return the darray of the ndarray'''
122        return self.nda.ndarray if self.nda is not None else None
123
124    @property
125    def uri(self):
126        '''return the uri of the ndarray'''
127        return self.nda.uri if self.nda is not None else None
128
129    @property
130    def shape(self):
131        '''return the shape of the ndarray'''
132        return self.nda.shape if self.nda is not None else None
133
134    @property
135    def ntv_type(self):
136        '''return the ntv_type of the ndarray'''
137        return self.nda.ntv_type if self.nda is not None else None
138
139    @property
140    def mode(self):
141        '''return the mode of the ndarray'''
142        return self.nda.mode if self.nda is not None else 'undefined'
143
144    @property
145    def info(self):
146        ''' infos of the Xndarray'''
147        inf = {'name': self.full_name}
148        inf['length'] = len(self)
149        if self.nda:
150            inf['mode'] = self.mode
151            inf['ntvtype'] = self.ntv_type
152            inf['shape'] = self.shape
153        inf['uri'] = self.uri
154        inf['meta'] = self.meta
155        inf['xtype'] = self.xtype
156        inf['links'] = self.links
157        return {key: val for key, val in inf.items() if val}
158
159    @property
160    def xtype(self):
161        '''nature of the Xndarray (undefined, namedarray, variable, additional,
162        meta, inconsistent)'''
163        match [self.links, self.add_name, self.mode]:
164            case [_, _, 'inconsistent']:
165                return 'inconsistent'
166            case [_, _, 'undefined']:
167                return 'meta'
168            case [None, '', _]:
169                return 'namedarray'
170            case [_, '', _]:
171                return 'variable'
172            case [_, str(), _]:
173                return 'additional'
174            case _:
175                return 'inconsistent'
176
177    @property
178    def full_name(self):
179        '''concatenation of name and additional name'''
180        add_name = '.' + self.add_name if self.add_name else ''
181        return self.name + add_name
182
183    @property
184    def json_name(self):
185        '''concatenation of full_name and ntv_type'''
186        add_ntv_type = ':' + self.ntv_type if self.ntv_type else ''
187        return self.full_name + add_ntv_type
188
189    @staticmethod
190    def read_json(jsn, **kwargs):
191        ''' convert json data into a Xndarray.
192
193        *Parameters*
194
195        - **convert** : boolean (default True) - If True, convert json data with
196        non Numpy ntv_type into data with python type
197        '''
198        option = {'convert': True} | kwargs
199        jso = json.loads(jsn) if isinstance(jsn, str) else jsn
200        value, full_name = Ntv.decode_json(jso)[:2]
201
202        meta = links = nda = None
203        match value:
204            case str(meta) | dict(meta): ...
205            case [list(nda)]: ...
206            case [list(nda), list(links)]: ...
207            case [list(nda), dict(meta)] | [list(nda), str(meta)]: ...
208            case [list(nda), list(links), dict(meta)]: ...
209            case [list(nda), list(links), str(meta)]: ...
210            case _:
211                return None
212        nda = Ndarray.read_json(nda, **option) if nda else None
213        return Xndarray(full_name, links=links, meta=meta, nda=nda)
214
215    def set_ndarray(self, ndarray, nda_uri=True):
216        '''set a new ndarray (nda) and return the result (True, False)
217
218        *Parameters*
219
220        - **ndarray** : string, list, np.ndarray, Ndarray - data to include
221        - **nda_uri** : boolean (default True) - if True, existing shape and
222        ntv_type are not updated (but are created if not existing)'''
223        ndarray = Ndarray(ndarray)
224        if not self.nda is None:
225            return self.nda.update(ndarray, nda_uri=nda_uri)
226        self.nda = ndarray
227        return True
228
229    def to_json(self, **kwargs):
230        ''' convert a Xndarray into json-value.
231
232        *Parameters*
233
234        - **encoded** : Boolean (default False) - json-value if False else json-text
235        - **header** : Boolean (default True) - including xndarray type
236        - **noname** : Boolean (default False) - including data type and name if False
237        - **notype** : Boolean (default False) - including data type if False
238        - **novalue** : Boolean (default False) - including value if False
239        - **noshape** : Boolean (default True) - if True, without shape if dim < 1
240        - **format** : string (default 'full') - representation format of the ndarray,
241        - **extension** : string (default None) - type extension
242        '''
243        option = {'notype': False, 'format': 'full',
244                  'noshape': True, 'header': True, 'encoded': False,
245                  'novalue': False, 'noname': False} | kwargs
246        if not option['format'] in ['full', 'complete']:
247            option['noshape'] = False
248        opt_nda = option | {'header': False}
249        nda_str = self.nda.to_json(**opt_nda) if not self.nda is None else None
250        lis = [nda_str, self.links, self.meta]
251        lis = [val for val in lis if not val is None]
252        return Nutil.json_ntv(None if option['noname'] else self.full_name,
253                              None if option['noname'] else 'xndarray',
254                              lis[0] if lis == [self.meta] else lis,
255                              header=option['header'], encoded=option['encoded'])
256
257    def _to_json(self):
258        '''return dict of attributes'''
259        return {'name': self.name, 'ntv_type': self.ntv_type, 'uri': self.uri,
260                'nda': self.nda, 'meta': self.meta, 'links': self.links}