Coverage for src / thunderlab / datawriter.py: 87%

1"""Writing numpy arrays of floats to data files. 

2 

3- `write_data()`: write data into a file. 

4- `available_formats()`: supported data and audio file formats. 

5- `available_encodings()`: encodings of a data file format. 

6- `format_from_extension()`: deduce data file format from file extension. 

7- `recode_array()`: recode array of floats. 

8- `insert_container_metadata()`: insert flattened metadata to data dictionary for a container file format. 

9""" 

10 

11import sys 

12import datetime as dt 

13 

14from pathlib import Path 

15from copy import deepcopy 

16from audioio import find_key, add_metadata, move_metadata 

17from audioio import get_datetime, default_gain_keys 

18 

19data_modules = {} 

20"""Dictionary with availability of various modules needed for writing data. 

21Keys are the module names, values are booleans. 

22""" 

23 

24try: 

25 import pickle 

26 data_modules['pickle'] = True 

27except ImportError: 

28 data_modules['pickle'] = False 

29 

30try: 

31 import numpy as np 

32 data_modules['numpy'] = True 

33except ImportError: 

34 data_modules['numpy'] = False 

35 

36try: 

37 import scipy.io as sio 

38 data_modules['scipy'] = True 

39except ImportError: 

40 data_modules['scipy'] = False 

41 

42try: 

43 import audioio.audiowriter as aw 

44 import audioio.audiometadata as am 

45 from audioio import write_metadata_text, flatten_metadata 

46 data_modules['audioio'] = True 

47except ImportError: 

48 data_modules['audioio'] = False 

49 

50 

51def format_from_extension(filepath): 

52 """Deduce data file format from file extension. 

53 

54 Parameters 

55 ---------- 

56 filepath: str or Path or None 

57 Path and name of the data file. 

58 

59 Returns 

60 ------- 

61 format: str 

62 Data format deduced from file extension. 

63 """ 

64 if filepath is None: 

65 return None 

66 filepath = Path(filepath) 

67 ext = filepath.suffix 

68 if not ext: 

69 return None 

70 if ext[0] == '.': 

71 ext = ext[1:] 

72 if not ext: 

73 return None 

74 ext = ext.upper() 

75 if ext == 'SCANDAT': 

76 return 'RAW' 

77 if data_modules['audioio']: 

78 ext = aw.format_from_extension(filepath) 

79 return ext 

80 

81 

82def recode_array(data, amax, encoding): 

83 """Recode array of floats. 

84 

85 Parameters 

86 ---------- 

87 data: array of floats 

88 Data array with values ranging between -1 and 1 

89 amax: float 

90 Maximum amplitude of data range. 

91 encoding: str 

92 Encoding, one of PCM_16, PCM_32, PCM_64, FLOAT or DOUBLE. 

93 

94 Returns 

95 ------- 

96 buffer: array 

97 The data recoded according to `encoding`. 

98 """ 

99 

100 encodings = {'PCM_16': (2, 'i2'), 

101 'PCM_32': (4, 'i4'), 

102 'PCM_64': (8, 'i8'), 

103 'FLOAT': (4, 'f'), 

104 'DOUBLE': (8, 'd')} 

105 

106 if not encoding in encodings: 

107 return data 

108 dtype = encodings[encoding][1] 

109 if dtype[0] == 'i': 

110 sampwidth = encodings[encoding][0] 

111 factor = 2**(sampwidth*8-1) 

112 buffer = np.round(data/amax*factor).astype(dtype) 

113 buffer[data >= +amax] = factor - 1 

114 buffer[data <= -amax] = -(factor - 1) 

115 else: 

116 buffer = data.astype(dtype, copy=False) 

117 return buffer 

118 

119 

120def formats_relacs(): 

121 """Data format of the relacs file format. 

122 

123 Returns 

124 ------- 

125 formats: list of str 

126 List of supported file formats as strings. 

127 """ 

128 return ['RELACS'] 

129 

130 

131def encodings_relacs(format=None): 

132 """Encodings of the relacs file format. 

133 

134 Parameters 

135 ---------- 

136 format: str 

137 The file format. 

138 

139 Returns 

140 ------- 

141 encodings: list of str 

142 List of supported encodings as strings. 

143 """ 

144 if not format: 

145 format = 'RELACS' 

146 if format.upper() != 'RELACS': 

147 return [] 

148 else: 

149 return ['FLOAT'] 

150 

151 

152def write_relacs(filepath, data, rate, amax=1.0, unit=None, 

153 metadata=None, locs=None, labels=None, format=None, 

154 encoding=None): 

155 """Write data as relacs raw files. 

156 

157 Parameters 

158 ---------- 

159 filepath: str or Path 

160 Full path of folder where to write relacs files. 

161 data: 1-D or 2-D array of floats 

162 Array with the data (first index time, optional second index channel). 

163 rate: float 

164 Sampling rate of the data in Hertz. 

165 amax: float 

166 Maximum possible amplitude of the data in `unit`. 

167 unit: str 

168 Unit of the data. 

169 metadata: nested dict 

170 Additional metadata saved into `info.dat`. 

171 locs: None or 1-D or 2-D array of ints 

172 Marker positions (first column) and spans (optional second column) 

173 for each marker (rows). 

174 labels: None or 2-D array of string objects 

175 Labels (first column) and texts (optional second column) 

176 for each marker (rows). 

177 format: str or None 

178 File format, only None or 'RELACS' are supported. 

179 encoding: str or None 

180 Encoding of the data. Only None or 'FLOAT' are supported. 

181 

182 Returns 

183 ------- 

184 filepath: Path 

185 The actual folder used for writing the data. 

186 

187 Raises 

188 ------ 

189 ValueError 

190 File format or encoding not supported. 

191 """ 

192 if format is None: 

193 format = 'RELACS' 

194 if format.upper() != 'RELACS': 

195 raise ValueError(f'file format {format} not supported by relacs file format') 

196 if encoding is None: 

197 encoding = 'FLOAT' 

198 if encoding.upper() != 'FLOAT': 

199 raise ValueError(f'file encoding {encoding} not supported by relacs file format') 

200 filepath = Path(filepath) 

201 if not filepath.exists(): 

202 filepath.mkdir() 

203 # write data: 

204 if data.ndim == 1: 

205 with open(filepath / f'trace-1.raw', 'wb') as df: 

206 df.write(data.astype(np.float32).tobytes()) 

207 else: 

208 for c in range(data.shape[1]): 

209 with open(filepath / f'trace-{c+1}.raw', 'wb') as df: 

210 df.write(data[:, c].astype(np.float32).tobytes()) 

211 if unit is None: 

212 unit = 'V' 

213 # write data format: 

214 df = open(filepath / 'stimuli.dat', 'w') 

215 df.write('# analog input traces:\n') 

216 for c in range(data.shape[1] if data.ndim > 1 else 1): 

217 df.write(f'# identifier{c+1} : V-{c+1}\n') 

218 df.write(f'# data file{c+1} : trace-{{c+1}}.raw\n') 

219 df.write(f'# sample interval{c+1} : {1000.0/rate:.4f}ms\n') 

220 df.write(f'# sampling rate{c+1} : {rate:.2f}Hz\n') 

221 df.write(f'# unit{c+1} : {unit}\n') 

222 df.write('# event lists:\n') 

223 df.write('# event file1: stimulus-events.dat\n') 

224 df.write('# event file2: restart-events.dat\n') 

225 df.write('# event file3: recording-events.dat\n') 

226 df.close() 

227 # write empty event files: 

228 for events in ['Recording', 'Restart', 'Stimulus']: 

229 df = open(filepath / f'{events.lower()}-events.dat', 'w') 

230 df.write(f'# events: {events}\n\n') 

231 df.write('#Key\n') 

232 if events == 'Stimulus': 

233 df.write('# t duration\n') 

234 df.write('# sec s\n') 

235 df.write('# 1 2\n') 

236 else: 

237 df.write('# t\n') 

238 df.write('# sec\n') 

239 df.write('# 1\n') 

240 if events == 'Recording': 

241 df.write(' 0.0\n') 

242 df.close() 

243 # write metadata: 

244 if metadata: 

245 write_metadata_text(filepath / 'info.dat', 

246 metadata, prefix='# ') 

247 return filepath 

248 

249 

250def formats_fishgrid(): 

251 """Data format of the fishgrid file format. 

252 

253 Returns 

254 ------- 

255 formats: list of str 

256 List of supported file formats as strings. 

257 """ 

258 return ['FISHGRID'] 

259 

260 

261def encodings_fishgrid(format=None): 

262 """Encodings of the fishgrid file format. 

263 

264 Parameters 

265 ---------- 

266 format: str 

267 The file format. 

268 

269 Returns 

270 ------- 

271 encodings: list of str 

272 List of supported encodings as strings. 

273 """ 

274 if not format: 

275 format = 'FISHGRID' 

276 if format.upper() != 'FISHGRID': 

277 return [] 

278 else: 

279 return ['FLOAT'] 

280 

281 

282def write_fishgrid(filepath, data, rate, amax=1.0, unit=None, 

283 metadata=None, locs=None, labels=None, format=None, 

284 encoding=None): 

285 """Write data as fishgrid raw files. 

286 

287 Parameters 

288 ---------- 

289 filepath: str or Path 

290 Full path of the folder where to write fishgrid files. 

291 data: 1-D or 2-D array of floats 

292 Array with the data (first index time, optional second index channel). 

293 rate: float 

294 Sampling rate of the data in Hertz. 

295 amax: float 

296 Maximum possible amplitude of the data in `unit`. 

297 unit: str 

298 Unit of the data. 

299 metadata: nested dict 

300 Additional metadata saved into the `fishgrid.cfg`. 

301 locs: None or 1-D or 2-D array of ints 

302 Marker positions (first column) and spans (optional second column) 

303 for each marker (rows). 

304 labels: None or 2-D array of string objects 

305 Labels (first column) and texts (optional second column) 

306 for each marker (rows). 

307 format: str or None 

308 File format, only None or 'FISHGRID' are supported. 

309 encoding: str or None 

310 Encoding of the data. Only None or 'FLOAT' are supported. 

311 

312 Returns 

313 ------- 

314 filepath: Path 

315 The actual folder used for writing the data. 

316 

317 Raises 

318 ------ 

319 ValueError 

320 File format or encoding not supported. 

321 """ 

322 def write_timestamp(df, count, index, span, rate, starttime, 

323 label, comment): 

324 datetime = starttime + dt.timedelta(seconds=index/rate) 

325 df.write(f' Num: {count}\n') 

326 df.write(f' Index1: {index}\n') 

327 #df.write(f' Index2: 0\n') 

328 #df.write(f' Index3: 0\n') 

329 #df.write(f' Index4: 0\n') 

330 if span > 0: 

331 df.write(f' Span1: {span}\n') 

332 df.write(f' Date: {datetime.date().isoformat()}\n') 

333 df.write(f' Time: {datetime.time().isoformat(timespec="seconds")}\n') 

334 if label: 

335 df.write(f' Label: {label}\n') 

336 df.write(f'Comment: {comment}\n') 

337 df.write('\n') 

338 

339 if format is None: 

340 format = 'FISHGRID' 

341 if format.upper() != 'FISHGRID': 

342 raise ValueError(f'file format {format} not supported by fishgrid file format') 

343 if encoding is None: 

344 encoding = 'FLOAT' 

345 if encoding.upper() != 'FLOAT': 

346 raise ValueError(f'file encoding {encoding} not supported by fishgrid file format') 

347 filepath = Path(filepath) 

348 if not filepath.exists(): 

349 filepath.mkdir() 

350 # write data: 

351 with open(filepath / 'traces-grid1.raw', 'wb') as df: 

352 df.write(data.astype(np.float32).tobytes()) 

353 # write metadata: 

354 if unit is None: 

355 unit = 'mV' 

356 cfgfile = filepath / 'fishgrid.cfg' 

357 nchannels = data.shape[1] if data.ndim > 1 else 1 

358 ncols = int(np.ceil(np.sqrt(nchannels))) 

359 nrows = int(np.ceil(nchannels/ncols)) 

360 if metadata is None: 

361 metadata = {} 

362 if 'FishGrid' in metadata: 

363 md = {} 

364 rmd = {} 

365 for k in metadata: 

366 if isinstance(metadata[k], dict): 

367 md[k] = deepcopy(metadata[k]) 

368 else: 

369 rmd[k] = metadata[k] 

370 if len(rmd) > 0: 

371 m, k = find_key(md, 'FishGrid.Recording') 

372 if k in m: 

373 m[k].update(rmd) 

374 else: 

375 m[k] = rmd 

376 else: 

377 smd = deepcopy(metadata) 

378 gm = dict(Used1='true', Columns1=f'{ncols}', Rows1=f'{nrows}') 

379 hm = {'DAQ board': dict()} 

380 if not move_metadata(smd, hm, 'Amplifier'): 

381 am = {} 

382 move_metadata(smd, am, ['Amplifier.Name', 'AmplName'], 'AmplName') 

383 move_metadata(smd, am, ['Amplifier.Model', 'AmplModel'], 'AmplModel') 

384 move_metadata(smd, am, 'Amplifier.Type') 

385 move_metadata(smd, am, 'Gain') 

386 move_metadata(smd, am, 'HighpassCutoff') 

387 move_metadata(smd, am, 'LowpassCutoff') 

388 if len(am) > 0: 

389 hm['Amplifier'] = am 

390 md = dict(FishGrid={'Grid 1': gm, 'Hardware Settings': hm}) 

391 move_metadata(smd, md['FishGrid'], 'Recording') 

392 gm = {} 

393 starttime = get_datetime(smd, remove=True) 

394 if not starttime is None: 

395 gm['StartDate'] = starttime.date().isoformat() 

396 gm['StartTime'] = starttime.time().isoformat(timespec='seconds') 

397 move_metadata(smd, gm, 'Location') 

398 move_metadata(smd, gm, 'Position') 

399 move_metadata(smd, gm, 'WaterTemperature') 

400 move_metadata(smd, gm, 'WaterConductivity') 

401 move_metadata(smd, gm, 'WaterpH') 

402 move_metadata(smd, gm, 'WaterOxygen') 

403 move_metadata(smd, gm, 'Temperature') 

404 move_metadata(smd, gm, 'Humidity') 

405 move_metadata(smd, gm, 'Pressure') 

406 move_metadata(smd, gm, 'Comment') 

407 move_metadata(smd, gm, 'Experimenter') 

408 if len(gm) > 0: 

409 if not 'Recording' in md['FishGrid']: 

410 md['FishGrid']['Recording'] = {} 

411 md['FishGrid']['Recording'].update({'General': gm}) 

412 bm = {} 

413 move_metadata(smd, bm, 'DataTime') 

414 move_metadata(smd, bm, 'DataInterval') 

415 move_metadata(smd, bm, 'BufferTime') 

416 move_metadata(smd, bm, 'BufferInterval') 

417 if len(bm) > 0: 

418 if not 'Recording' in md['FishGrid']: 

419 md['FishGrid']['Recording'] = {} 

420 md['FishGrid']['Recording'].update({'Buffers and timing': bm}) 

421 if smd: 

422 md['FishGrid']['Other'] = smd 

423 add_metadata(md, 

424 [f'FishGrid.Hardware Settings.DAQ board.AISampleRate={0.001*rate:.3f}kHz', 

425 f'FishGrid.Hardware Settings.DAQ board.AIMaxVolt={amax:g}{unit}']) 

426 with open(cfgfile, 'w') as df: 

427 for k in md: 

428 df.write(f'*{k}\n') 

429 write_metadata_text(df, md[k], prefix=' ') 

430 # write markers: 

431 filename = filepath / 'timestamps.dat' 

432 starttime = get_datetime(metadata, (('DateTimeOriginal',), 

433 ('OriginationDate', 'OriginationTime'), 

434 ('StartDate', 'StartTime'), 

435 ('Location_Time',)), 

436 default=dt.datetime.fromtimestamp(0, dt.timezone.utc)) 

437 with open(filename, 'w') as df: 

438 count = 0 

439 write_timestamp(df, count, 0, 0, rate, starttime, 

440 '', 'begin of recording') 

441 count += 1 

442 if locs is not None: 

443 for i in range(len(locs)): 

444 label = '' 

445 comment = '' 

446 if labels is not None and len(labels) > i: 

447 label = labels[i,0] if labels.ndim > 1 else labels[i] 

448 comment = labels[i,1] if labels.ndim > 1 else '' 

449 index = locs[i,0] if locs.ndim > 1 else locs[i] 

450 span = locs[i,1] if locs.ndim > 1 else 0 

451 write_timestamp(df, count, index*nchannels, 

452 span*nchannels, rate, 

453 starttime, label, comment) 

454 count += 1 

455 write_timestamp(df, count, len(data)*nchannels, 0, rate, 

456 starttime, '', 'end of recording') 

457 return filepath 

458 

459 

460def formats_pickle(): 

461 """Data formats supported by pickle.dump(). 

462 

463 Returns 

464 ------- 

465 formats: list of str 

466 List of supported file formats as strings. 

467 """ 

468 if not data_modules['pickle']: 

469 return [] 

470 else: 

471 return ['PKL'] 

472 

473 

474def encodings_pickle(format=None): 

475 """Encodings of the pickle format. 

476 

477 Parameters 

478 ---------- 

479 format: str 

480 The file format. 

481 

482 Returns 

483 ------- 

484 encodings: list of str 

485 List of supported encodings as strings. 

486 """ 

487 if not format: 

488 format = 'PKL' 

489 if format.upper() != 'PKL': 

490 return [] 

491 else: 

492 return ['PCM_16', 'PCM_32', 'FLOAT', 'DOUBLE'] 

493 

494 

495def write_pickle(filepath, data, rate, amax=1.0, unit=None, 

496 metadata=None, locs=None, labels=None, format=None, 

497 encoding=None): 

498 """Write data into python pickle file. 

499  

500 Documentation 

501 ------------- 

502 https://docs.python.org/3/library/pickle.html 

503 

504 Parameters 

505 ---------- 

506 filepath: str or Path 

507 Full path and name of the file to write. 

508 data: 1-D or 2-D array of floats 

509 Array with the data (first index time, optional second index channel). 

510 Stored under the key "data". 

511 rate: float 

512 Sampling rate of the data in Hertz. 

513 Stored under the key "rate". 

514 amax: float 

515 Maximum possible amplitude of the data in `unit`. 

516 Stored under the key "amax". 

517 unit: str 

518 Unit of the data. 

519 Stored under the key "unit". 

520 metadata: nested dict 

521 Additional metadata saved into the pickle. 

522 Stored under the key "metadata". 

523 locs: None or 1-D or 2-D array of ints 

524 Marker positions (first column) and spans (optional second column) 

525 for each marker (rows). 

526 labels: None or 2-D array of string objects 

527 Labels (first column) and texts (optional second column) 

528 for each marker (rows). 

529 format: str or None 

530 File format, only None or 'PKL' are supported. 

531 encoding: str or None 

532 Encoding of the data. 

533 

534 Returns 

535 ------- 

536 filepath: Path 

537 The actual file name used for writing the data. 

538 

539 Raises 

540 ------ 

541 ImportError 

542 The pickle module is not available. 

543 ValueError 

544 File format or encoding not supported. 

545 """ 

546 if not data_modules['pickle']: 

547 raise ImportError 

548 if format is None: 

549 format = 'PKL' 

550 if format.upper() != 'PKL': 

551 raise ValueError(f'file format {format} not supported by pickle file format') 

552 filepath = Path(filepath) 

553 ext = filepath.suffix 

554 if len(ext) <= 1 or ext[1].upper() != 'P': 

555 filepath = filepath.with_suffix('.pkl') 

556 if encoding is None: 

557 encoding = 'DOUBLE' 

558 encoding = encoding.upper() 

559 if not encoding in encodings_pickle(format): 

560 raise ValueError(f'file encoding {encoding} not supported by pickle file format') 

561 buffer = recode_array(data, amax, encoding) 

562 ddict = dict(data=buffer, rate=rate) 

563 ddict['amax'] = amax 

564 if unit: 

565 ddict['unit'] = unit 

566 if metadata: 

567 ddict['metadata'] = metadata 

568 if locs is not None and len(locs) > 0: 

569 if locs.ndim == 1: 

570 ddict['positions'] = locs 

571 else: 

572 ddict['positions'] = locs[:,0] 

573 if locs.shape[1] > 1: 

574 ddict['spans'] = locs[:,1] 

575 if labels is not None and len(labels) > 0: 

576 if labels.ndim == 1: 

577 ddict['labels'] = labels 

578 else: 

579 ddict['labels'] = labels[:,0] 

580 if labels.shape[1] > 1: 

581 ddict['descriptions'] = labels[:,1] 

582 with open(filepath, 'wb') as df: 

583 pickle.dump(ddict, df) 

584 return filepath 

585 

586 

587def insert_container_metadata(metadata, data_dict, metadatakey='metadata'): 

588 """Insert flattened metadata to data dictionary for a container file format. 

589 

590 Parameters 

591 ---------- 

592 metadata: nested dict 

593 Nested dictionary with key-value pairs of the meta data. 

594 data_dict: dict 

595 Dictionary of the data items contained in the container to 

596 which the metadata should be added. 

597 metadatakey: str or list of str 

598 Name of the variable holding the metadata. 

599 """ 

600 fmeta = flatten_metadata(metadata, True, sep='__') 

601 for k in list(fmeta): 

602 fmeta[metadatakey + '__' + k] = fmeta.pop(k) 

603 data_dict.update(fmeta) 

604 

605 

606def formats_numpy(): 

607 """Data formats supported by numpy.savez(). 

608 

609 Returns 

610 ------- 

611 formats: list of str 

612 List of supported file formats as strings. 

613 """ 

614 if not data_modules['numpy']: 

615 return [] 

616 else: 

617 return ['NPZ'] 

618 

619 

620def encodings_numpy(format=None): 

621 """Encodings of the numpy file format. 

622 

623 Parameters 

624 ---------- 

625 format: str 

626 The file format. 

627 

628 Returns 

629 ------- 

630 encodings: list of str 

631 List of supported encodings as strings. 

632 """ 

633 if not format: 

634 format = 'NPZ' 

635 if format.upper() != 'NPZ': 

636 return [] 

637 else: 

638 return ['PCM_16', 'PCM_32', 'FLOAT', 'DOUBLE'] 

639 

640 

641def write_numpy(filepath, data, rate, amax=1.0, unit=None, 

642 metadata=None, locs=None, labels=None, format=None, 

643 encoding=None): 

644 """Write data into numpy npz file. 

645  

646 Documentation 

647 ------------- 

648 https://numpy.org/doc/stable/reference/generated/numpy.savez.html 

649 

650 Parameters 

651 ---------- 

652 filepath: str or Path 

653 Full path and name of the file to write. 

654 data: 1-D or 2-D array of floats 

655 Array with the data (first index time, optional second index channel). 

656 Stored under the key "data". 

657 rate: float 

658 Sampling rate of the data in Hertz. 

659 Stored under the key "rate". 

660 amax: float 

661 Maximum possible amplitude of the data in `unit`. 

662 Stored under the key "amax". 

663 unit: str 

664 Unit of the data. 

665 Stored under the key "unit". 

666 metadata: nested dict 

667 Additional metadata saved into the numpy file. 

668 Flattened dictionary entries stored under keys 

669 starting with "metadata__". 

670 locs: None or 1-D or 2-D array of ints 

671 Marker positions (first column) and spans (optional second column) 

672 for each marker (rows). 

673 labels: None or 2-D array of string objects 

674 Labels (first column) and texts (optional second column) 

675 for each marker (rows). 

676 format: str or None 

677 File format, only None or 'NPZ' are supported. 

678 encoding: str or None 

679 Encoding of the data. 

680 

681 Returns 

682 ------- 

683 filepath: Path 

684 The actual file name used for writing the data. 

685 

686 Raises 

687 ------ 

688 ImportError 

689 The numpy module is not available. 

690 ValueError 

691 File format or encoding not supported. 

692 """ 

693 if not data_modules['numpy']: 

694 raise ImportError 

695 if format is None: 

696 format = 'NPZ' 

697 if format.upper() not in formats_numpy(): 

698 raise ValueError(f'file format {format} not supported by numpy file format') 

699 filepath = Path(filepath) 

700 ext = filepath.suffix 

701 if len(ext) <= 1 or ext[1].upper() != 'N': 

702 filepath = filepath.with_suffix('.npz') 

703 if encoding is None: 

704 encoding = 'DOUBLE' 

705 encoding = encoding.upper() 

706 if not encoding in encodings_numpy(format): 

707 raise ValueError(f'file encoding {encoding} not supported by numpy file format') 

708 buffer = recode_array(data, amax, encoding) 

709 ddict = dict(data=buffer, rate=rate) 

710 ddict['amax'] = amax 

711 if unit: 

712 ddict['unit'] = unit 

713 if metadata: 

714 insert_container_metadata(metadata, ddict, 'metadata') 

715 if locs is not None and len(locs) > 0: 

716 if locs.ndim == 1: 

717 ddict['positions'] = locs 

718 else: 

719 ddict['positions'] = locs[:,0] 

720 if locs.shape[1] > 1: 

721 ddict['spans'] = locs[:,1] 

722 if labels is not None and len(labels) > 0: 

723 if labels.ndim == 1: 

724 maxc = np.max([len(l) for l in labels]) 

725 ddict['labels'] = labels.astype(dtype=f'U{maxc}') 

726 else: 

727 maxc = np.max([len(l) for l in labels[:,0]]) 

728 ddict['labels'] = labels[:,0].astype(dtype=f'U{maxc}') 

729 if labels.shape[1] > 1: 

730 maxc = np.max([len(l) for l in labels[:,1]]) 

731 ddict['descriptions'] = labels[:,1].astype(dtype=f'U{maxc}') 

732 np.savez(filepath, **ddict) 

733 return filepath 

734 

735 

736def formats_mat(): 

737 """Data formats supported by scipy.io.savemat(). 

738 

739 Returns 

740 ------- 

741 formats: list of str 

742 List of supported file formats as strings. 

743 """ 

744 if not data_modules['scipy']: 

745 return [] 

746 else: 

747 return ['MAT'] 

748 

749 

750def encodings_mat(format=None): 

751 """Encodings of the matlab format. 

752 

753 Parameters 

754 ---------- 

755 format: str 

756 The file format. 

757 

758 Returns 

759 ------- 

760 encodings: list of str 

761 List of supported encodings as strings. 

762 """ 

763 if not format: 

764 format = 'MAT' 

765 if format.upper() != 'MAT': 

766 return [] 

767 else: 

768 return ['PCM_16', 'PCM_32', 'FLOAT', 'DOUBLE'] 

769 

770 

771def write_mat(filepath, data, rate, amax=1.0, unit=None, 

772 metadata=None, locs=None, labels=None, format=None, 

773 encoding=None): 

774 """Write data into matlab file. 

775  

776 Documentation 

777 ------------- 

778 https://docs.scipy.org/doc/scipy/reference/generated/scipy.io.savemat.html 

779 

780 Parameters 

781 ---------- 

782 filepath: str or Path 

783 Full path and name of the file to write. 

784 data: 1-D or 2-D array of floats 

785 Array with the data (first index time, optional second index channel). 

786 Stored under the key "data". 

787 rate: float 

788 Sampling rate of the data in Hertz. 

789 Stored under the key "rate". 

790 amax: float 

791 Maximum possible amplitude of the data in `unit`. 

792 Stored under the key "amax". 

793 unit: str 

794 Unit of the data. 

795 Stored under the key "unit". 

796 metadata: nested dict 

797 Additional metadata saved into the mat file. 

798 Stored under the key "metadata". 

799 locs: None or 1-D or 2-D array of ints 

800 Marker positions (first column) and spans (optional second column) 

801 for each marker (rows). 

802 labels: None or 2-D array of string objects 

803 Labels (first column) and texts (optional second column) 

804 for each marker (rows). 

805 format: str or None 

806 File format, only None or 'MAT' are supported. 

807 encoding: str or None 

808 Encoding of the data. 

809 

810 Returns 

811 ------- 

812 filepath: Path 

813 The actual file name used for writing the data. 

814 

815 Raises 

816 ------ 

817 ImportError 

818 The scipy.io module is not available. 

819 ValueError 

820 File format or encoding not supported. 

821 """ 

822 if not data_modules['scipy']: 

823 raise ImportError 

824 if format is None: 

825 format = 'MAT' 

826 if format.upper() not in formats_mat(): 

827 raise ValueError(f'file format {format} not supported by matlab file format') 

828 filepath = Path(filepath) 

829 ext = filepath.suffix 

830 if len(ext) <= 1 or ext[1].upper() != 'M': 

831 filepath = filepath.with_suffix('.mat') 

832 if encoding is None: 

833 encoding = 'DOUBLE' 

834 encoding = encoding.upper() 

835 if not encoding in encodings_mat(format): 

836 raise ValueError(f'file encoding {encoding} not supported by matlab file format') 

837 buffer = recode_array(data, amax, encoding) 

838 ddict = dict(data=buffer, rate=rate) 

839 ddict['amax'] = amax 

840 if unit: 

841 ddict['unit'] = unit 

842 if metadata: 

843 insert_container_metadata(metadata, ddict, 'metadata') 

844 if locs is not None and len(locs) > 0: 

845 if locs.ndim == 1: 

846 ddict['positions'] = locs 

847 else: 

848 ddict['positions'] = locs[:,0] 

849 if locs.shape[1] > 1: 

850 ddict['spans'] = locs[:,1] 

851 if labels is not None and len(labels) > 0: