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        # print('init xnd', full_name, nda.to_json(), links, meta)
 61        if isinstance(full_name, Xndarray):
 62            self.name = full_name.name
 63            self.add_name = full_name.add_name
 64            self.nda = full_name.nda
 65            self.links = full_name.links
 66            self.meta = full_name.meta
 67            return
 68        self.name, self.add_name = Nutil.split_name(full_name)
 69        self.nda = Ndarray(nda) if not nda is None else None
 70        self.links = sorted(links) if links else None
 71        self.meta = meta if meta else None
 72        if self.meta is None and self.nda is None:
 73            raise NdarrayError('A Xndarray has to have metadata or Ndarray')
 74
 75    def __repr__(self):
 76        '''return classname and number of value'''
 77        return self.__class__.__name__ + '[' + self.full_name + ']'
 78
 79    def __str__(self):
 80        '''return json string format'''
 81        return json.dumps(self.to_json())
 82
 83    def __eq__(self, other):
 84        ''' equal if attributes are equal'''
 85        if self.name != other.name or self.add_name != other.add_name:
 86            return False
 87        if self.links != other.links or self.meta != other.meta:
 88            return False
 89        if self.nda is None and other.nda is None:
 90            return True
 91        if self.nda is None or other.nda is None:
 92            return False
 93        return self.nda == other.nda
 94
 95    def __len__(self):
 96        ''' len of ndarray'''
 97        return len(self.nda) if self.nda is not None else 0
 98
 99    def __contains__(self, item):
100        ''' item of ndarray values'''
101        return item in self.nda if self.nda is not None else None
102
103    def __getitem__(self, ind):
104        ''' return ndarray value item'''
105        if self.nda is None:
106            return None
107        if isinstance(ind, tuple):
108            return [self.nda[i] for i in ind]
109            # return [copy(self.values[i]) for i in ind]
110        return self.nda[ind]
111        # return copy(self.values[ind])
112
113    def __copy__(self):
114        ''' Copy all the data '''
115        return self.__class__(self)
116
117    @property
118    def darray(self):
119        '''return the darray of the ndarray'''
120        return self.nda.darray if self.nda is not None else None
121
122    @property
123    def ndarray(self):
124        '''return the darray of the ndarray'''
125        return self.nda.ndarray if self.nda is not None else None
126
127    @property
128    def uri(self):
129        '''return the uri of the ndarray'''
130        return self.nda.uri if self.nda is not None else None
131
132    @property
133    def shape(self):
134        '''return the shape of the ndarray'''
135        return self.nda.shape if self.nda is not None else None
136
137    @property
138    def ntv_type(self):
139        '''return the ntv_type of the ndarray'''
140        return self.nda.ntv_type if self.nda is not None else None
141
142    @property
143    def mode(self):
144        '''return the mode of the ndarray'''
145        return self.nda.mode if self.nda is not None else 'undefined'
146
147    @property
148    def info(self):
149        ''' infos of the Xndarray'''
150        inf = {'name': self.full_name}
151        inf['length'] = len(self)
152        if self.nda:
153            inf['mode'] = self.mode
154            inf['ntvtype'] = self.ntv_type
155            inf['shape'] = self.shape
156        inf['xtype'] = self.xtype
157        inf['links'] = self.links
158        return {key: val for key, val in inf.items() if val}
159
160    @property
161    def xtype(self):
162        '''nature of the Xndarray (undefined, namedarray, variable, additional,
163        inconsistent)'''
164        match [self.links, self.add_name, self.mode]:
165            case [_, _, 'inconsistent']:
166                return 'inconsistent'
167            case [_, _, 'undefined']:
168                return 'metadata'
169            case [None, '', _]:
170                return 'namedarray'
171            case [_, '', _]:
172                return 'variable'
173            case [_, str(), _]:
174                return 'additional'
175            case _:
176                return 'inconsistent'
177
178    @property
179    def full_name(self):
180        '''concatenation of name and additional name'''
181        add_name = '.' + self.add_name if self.add_name else ''
182        return self.name + add_name
183
184    @property
185    def json_name(self):
186        '''concatenation of full_name and ntv_type'''
187        add_ntv_type = ':' + self.ntv_type if self.ntv_type else ''
188        return self.full_name + add_ntv_type
189
190    @staticmethod
191    def read_json(jsn, **kwargs):
192        ''' convert json data into a Xndarray.
193
194        *Parameters*
195
196        - **convert** : boolean (default True) - If True, convert json data with
197        non Numpy ntv_type into data with python type
198        '''
199        option = {'convert': True} | kwargs
200        jso = json.loads(jsn) if isinstance(jsn, str) else jsn
201        value, full_name = Ntv.decode_json(jso)[:2]
202
203        meta = links = nda = None
204        match value:
205            case str(meta) | dict(meta): ...
206            case [list(nda)]: ...
207            case [list(nda), list(links)]: ...
208            case [list(nda), dict(meta)] | [list(nda), str(meta)]: ...
209            case [list(nda), list(links), dict(meta)]: ...
210            case [list(nda), list(links), str(meta)]: ...
211            case _:
212                return None
213        nda = Ndarray.read_json(nda, **option) if nda else None
214        return Xndarray(full_name, links=links, meta=meta, nda=nda)
215
216    def set_ndarray(self, ndarray, nda_uri=True):
217        '''set a new ndarray (nda) and return the result (True, False)
218
219        *Parameters*
220
221        - **ndarray** : string, list, np.ndarray, Ndarray - data to include
222        - **nda_uri** : boolean (default True) - if True, existing shape and
223        ntv_type are not updated (but are created if not existing)'''
224        ndarray = Ndarray(ndarray)
225        if not self.nda is None:
226            return self.nda.update(ndarray, nda_uri=nda_uri)
227        self.nda = ndarray
228        return True
229
230    def to_json(self, **kwargs):
231        ''' convert a Xndarray into json-value.
232
233        *Parameters*
234
235        - **encoded** : Boolean (default False) - json-value if False else json-text
236        - **header** : Boolean (default True) - including xndarray type
237        - **noname** : Boolean (default False) - including data type and name if False
238        - **notype** : Boolean (default False) - including data type if False
239        - **novalue** : Boolean (default False) - including value if False
240        - **noshape** : Boolean (default True) - if True, without shape if dim < 1
241        - **format** : string (default 'full') - representation format of the ndarray,
242        - **extension** : string (default None) - type extension
243        '''
244        option = {'notype': False, 'format': 'full',
245                  'noshape': True, 'header': True, 'encoded': False,
246                  'novalue': False, 'noname': False} | kwargs
247        if not option['format'] in ['full', 'complete']:
248            option['noshape'] = False
249        opt_nda = option | {'header': False}
250        # nda_str = Ndarray.to_json(self.nda,
251        nda_str = self.nda.to_json(**opt_nda) if not self.nda is None else None
252        lis = [nda_str, self.links, self.meta]
253        lis = [val for val in lis if not val is None]
254        return Nutil.json_ntv(None if option['noname'] else self.full_name,
255                              None if option['noname'] else 'xndarray',
256                              lis[0] if lis == [self.meta] else lis,
257                              header=option['header'], encoded=option['encoded'])
258
259    def _to_json(self):
260        '''return dict of attributes'''
261        return {'name': self.name, 'ntv_type': self.ntv_type, 'uri': self.uri,
262                'nda': self.nda, 'meta': self.meta, 'links': self.links}