Coverage for ibllib/qc/camera.py: 78%

1"""Video quality control. 

2 

3This module runs a list of quality control metrics on the camera and extracted video data. 

4 

5Examples 

6-------- 

7Run right camera QC, downloading all but video file 

8 

9>>> qc = CameraQC(eid, 'right', download_data=True, stream=True) 

10>>> qc.run() 

11 

12Run left camera QC with session path, update QC field in Alyx 

13 

14>>> qc = CameraQC(session_path, 'left') 

15>>> outcome, extended = qc.run(update=True) # Returns outcome of videoQC only 

16>>> print(f'video QC = {outcome}; overall session QC = {qc.outcome}') # NB difference outcomes 

17 

18Run only video QC (no timestamp/alignment checks) on 20 frames for the body camera 

19 

20>>> qc = CameraQC(eid, 'body', n_samples=20) 

21>>> qc.load_video_data() # Quicker than loading all data 

22>>> qc.run() 

23 

24Run specific video QC check and display the plots 

25 

26>>> qc = CameraQC(eid, 'left') 

27>>> qc.load_data(download_data=True) 

28>>> qc.check_position(display=True) # NB: Not all checks make plots 

29 

30Run the QC for all cameras 

31 

32>>> qcs = run_all_qc(eid) 

33>>> qcs['left'].metrics # Dict of checks and outcomes for left camera 

34""" 

35import logging (empty)

36from inspect import getmembers, isfunction (empty)

37from pathlib import Path (empty)

38from itertools import chain (empty)

39import copy (empty)

40 

41import cv2 (empty)

42import numpy as np (empty)

43import matplotlib.pyplot as plt (empty)

44import pandas as pd (empty)

45from matplotlib.patches import Rectangle (empty)

46 

47import one.alf.io as alfio (empty)

48from one.util import filter_datasets (empty)

49from one.alf import spec (empty)

50from one.alf.exceptions import ALFObjectNotFound (empty)

51from iblutil.util import Bunch (empty)

52from iblutil.numerical import within_ranges (empty)

53 

54from ibllib.io.extractors.camera import extract_camera_sync, extract_all (empty)

55from ibllib.io.extractors import ephys_fpga, training_wheel, mesoscope (empty)

56from ibllib.io.extractors.video_motion import MotionAlignment (empty)

57from ibllib.io.extractors.base import get_session_extractor_type (empty)

58from ibllib.io import raw_data_loaders as raw (empty)

59from ibllib.io.raw_daq_loaders import load_timeline_sync_and_chmap (empty)

60from ibllib.io.session_params import read_params, get_sync, get_sync_namespace (empty)

61import brainbox.behavior.wheel as wh (empty)

62from ibllib.io.video import get_video_meta, get_video_frames_preload, assert_valid_label (empty)

63from . import base (empty)

64 

65_log = logging.getLogger(__name__) (empty)

66 

67try: (empty)

68 from labcams import parse_cam_log (empty)

69except ImportError: 

70 _log.warning('labcams not installed') 

71 

72 

73class CameraQC(base.QC): (empty)

74 """A class for computing camera QC metrics.""" 

75 

76 dstypes = [ (empty)

77 '_ibl_experiment.description', 

78 '_iblrig_Camera.frameData', # Replaces the next 3 datasets 

79 '_iblrig_Camera.frame_counter', 

80 '_iblrig_Camera.GPIO', 

81 '_iblrig_Camera.timestamps', 

82 '_iblrig_taskData.raw', 

83 '_iblrig_taskSettings.raw', 

84 '_iblrig_Camera.raw', 

85 'camera.times', 

86 'wheel.position', 

87 'wheel.timestamps' 

88 ] 

89 dstypes_fpga = [ (empty)

90 '_spikeglx_sync.channels', 

91 '_spikeglx_sync.polarities', 

92 '_spikeglx_sync.times', 

93 'ephysData.raw.meta' 

94 ] 

95 """Recall that for the training rig there is only one side camera at 30 Hz and 1280 x 1024 px. (empty)

96 For the recording rig there are two label cameras (left: 60 Hz, 1280 x 1024 px; 

97 right: 150 Hz, 640 x 512 px) and one body camera (30 Hz, 640 x 512 px). """ 

98 video_meta = { (empty)

99 'training': { 

100 'left': { 

101 'fps': 30, 

102 'width': 1280, 

103 'height': 1024 

104 } 

105 }, 

106 'ephys': { 

107 'left': { 

108 'fps': 60, 

109 'width': 1280, 

110 'height': 1024 

111 }, 

112 'right': { 

113 'fps': 150, 

114 'width': 640, 

115 'height': 512 

116 }, 

117 'body': { 

118 'fps': 30, 

119 'width': 640, 

120 'height': 512 

121 }, 

122 } 

123 } 

124 

125 def __init__(self, session_path_or_eid, camera, **kwargs): (empty)

126 """ 

127 Compute and view camera QC metrics. 

128 

129 :param session_path_or_eid: A session id or path 

130 :param camera: The camera to run QC on, if None QC is run for all three cameras 

131 :param n_samples: The number of frames to sample for the position and brightness QC 

132 :param stream: If true and local video files not available, the data are streamed from 

133 the remote source. 

134 :param log: A logging.Logger instance, if None the 'ibllib' logger is used 

135 :param one: An ONE instance for fetching and setting the QC on Alyx 

136 """ 

137 # When an eid is provided, we will download the required data by default (if necessary) 

138 download_data = not spec.is_session_path(Path(session_path_or_eid)) 7 ctx1fcaihbd

139 self.download_data = kwargs.pop('download_data', download_data) 7 ctx1fcaihbd

140 self.stream = kwargs.pop('stream', None) 7 ctx1fcaihbd

141 self.n_samples = kwargs.pop('n_samples', 100) 7 ctx1fcaihbd

142 self.sync_collection = kwargs.pop('sync_collection', None) 7 ctx1fcaihbd

143 self.sync = kwargs.pop('sync_type', None) 7 ctx1fcaihbd

144 super().__init__(session_path_or_eid, **kwargs) 7 ctx1fcaihbd

145 

146 # Data 

147 self.label = assert_valid_label(camera) 7 ctx1fcaihbd

148 filename = f'_iblrig_{self.label}Camera.raw*.mp4' 7 ctx1fcaihbd

149 raw_video_path = self.session_path.joinpath('raw_video_data') 7 ctx1fcaihbd

150 self.video_path = next(raw_video_path.glob(filename), None) 7 ctx1fcaihbd

151 

152 # If local video doesn't exist, change video path to URL 

153 if not self.video_path and self.stream is not False and self.one is not None: 7 ctx1fcaihbd

154 try: 

155 self.stream = True 

156 self.video_path = self.one.path2url(raw_video_path / filename.replace('*', '')) 

157 except (StopIteration, ALFObjectNotFound): 

158 _log.error('No remote or local video file found') 

159 self.video_path = None 

160 

161 logging.disable(logging.NOTSET) 7 ctx1fcaihbd

162 keys = ('count', 'pin_state', 'audio', 'fpga_times', 'wheel', 'video', 7 ctx1fcaihbd

163 'frame_samples', 'timestamps', 'camera_times', 'bonsai_times') 

164 self.data = Bunch.fromkeys(keys) 7 ctx1fcaihbd

165 self.frame_samples_idx = None 7 ctx1fcaihbd

166 

167 # QC outcomes map 

168 self.metrics = None 7 ctx1fcaihbd

169 self.outcome = spec.QC.NOT_SET 7 ctx1fcaihbd

170 

171 # Specify any checks to remove 

172 self.checks_to_remove = [] 7 ctx1fcaihbd

173 self._type = None 7 ctx1fcaihbd

174 

175 @property (empty)

176 def type(self): (empty)

177 """ 

178 Returns the camera type based on the protocol. 

179 

180 :return: Returns either None, 'ephys' or 'training' 

181 """ 

182 if not self._type: 11 ctx1xvqkcaihbgd

183 return 3 ctx1aib

184 else: 

185 return 'ephys' if 'ephys' in self._type else 'training' 11 ctx1xvqkcaihbgd

186 

187 def load_data(self, download_data: bool = None, extract_times: bool = False, load_video: bool = True) -> None: (empty)

188 """Extract the data from raw data files. 

189 

190 Extracts all the required task data from the raw data files. 

191 

192 Data keys: 

193 - count (int array): the sequential frame number (n, n+1, n+2...) 

194 - pin_state (): the camera GPIO pin; records the audio TTLs; should be one per frame 

195 - audio (float array): timestamps of audio TTL fronts 

196 - fpga_times (float array): timestamps of camera TTLs recorded by FPGA 

197 - timestamps (float array): extracted video timestamps (the camera.times ALF) 

198 - bonsai_times (datetime array): system timestamps of video PC; should be one per frame 

199 - camera_times (float array): camera frame timestamps extracted from frame headers 

200 - wheel (Bunch): rotary encoder timestamps, position and period used for wheel motion 

201 - video (Bunch): video meta data, including dimensions and FPS 

202 - frame_samples (h x w x n array): array of evenly sampled frames (1 colour channel) 

203 

204 :param download_data: if True, any missing raw data is downloaded via ONE. 

205 Missing data will raise an AssertionError 

206 :param extract_times: if True, the camera.times are re-extracted from the raw data 

207 :param load_video: if True, calls the load_video_data method 

208 """ 

209 assert self.session_path, 'no session path set' 6 ctx1caihbd

210 if download_data is not None: 6 ctx1caihbd

211 self.download_data = download_data 2 ctx1ab

212 if self.download_data and self.eid and self.one and not self.one.offline: 6 ctx1caihbd

213 self.ensure_required_data() 

214 _log.info('Gathering data for QC') 6 ctx1caihbd

215 

216 # Get frame count and pin state 

217 self.data['count'], self.data['pin_state'] = \ 6 ctx1caihbd

218 raw.load_embedded_frame_data(self.session_path, self.label, raw=True) 

219 

220 # If there is an experiment description and there are video parameters 

221 sess_params = read_params(self.session_path) or {} 6 ctx1caihbd

222 task_collection = get_task_collection(sess_params) 6 ctx1caihbd

223 ns = get_sync_namespace(sess_params) 6 ctx1caihbd

224 self._set_sync(sess_params) 6 ctx1caihbd

225 if not self.sync: 6 ctx1caihbd

226 if not self.type: 3 ctx1aib

227 self._type = get_session_extractor_type(self.session_path, task_collection) 3 ctx1aib

228 self.sync = 'nidq' if 'ephys' in self.type else 'bpod' 3 ctx1aib

229 self._update_meta_from_session_params(sess_params) 6 ctx1caihbd

230 

231 # Load the audio and raw FPGA times 

232 if self.sync != 'bpod' and self.sync is not None: 6 ctx1caihbd

233 self.sync_collection = self.sync_collection or 'raw_ephys_data' 2 ctx1ah

234 ns = ns or 'spikeglx' 2 ctx1ah

235 if ns == 'spikeglx': 2 ctx1ah

236 sync, chmap = ephys_fpga.get_sync_and_chn_map(self.session_path, self.sync_collection) 2 ctx1ah

237 elif ns == 'timeline': 1 ctx1h

238 sync, chmap = load_timeline_sync_and_chmap(self.session_path / self.sync_collection) 

239 else: 

240 raise NotImplementedError(f'Unknown namespace "{ns}"') 1 ctx1h

241 audio_ttls = ephys_fpga.get_sync_fronts(sync, chmap['audio']) 2 ctx1ah

242 self.data['audio'] = audio_ttls['times'] # Get rises 2 ctx1ah

243 # Load raw FPGA times 

244 cam_ts = extract_camera_sync(sync, chmap) 2 ctx1ah

245 self.data['fpga_times'] = cam_ts[self.label] 2 ctx1ah

246 else: 

247 self.sync_collection = self.sync_collection or task_collection 5 ctx1cihbd

248 bpod_data = raw.load_data(self.session_path, task_collection) 5 ctx1cihbd

249 _, audio_ttls = raw.load_bpod_fronts( 5 ctx1cihbd

250 self.session_path, data=bpod_data, task_collection=task_collection) 

251 self.data['audio'] = audio_ttls['times'] 5 ctx1cihbd

252 

253 # Load extracted frame times 

254 alf_path = self.session_path / 'alf' 6 ctx1caihbd

255 try: 6 ctx1caihbd

256 assert not extract_times 6 ctx1caihbd

257 self.data['timestamps'] = alfio.load_object( 4 ctx1cihd

258 alf_path, f'{self.label}Camera', short_keys=True)['times'] 

259 except AssertionError: # Re-extract 3 ctx1aib

260 kwargs = dict(video_path=self.video_path, labels=self.label) 2 ctx1ab

261 if self.sync != 'bpod' and self.sync is not None: 2 ctx1ab

262 kwargs = {**kwargs, 'sync': sync, 'chmap': chmap} # noqa 1 ctx1a

263 outputs, _ = extract_all(self.session_path, self.sync, save=False, 2 ctx1ab

264 sync_collection=self.sync_collection, **kwargs) 

265 self.data['timestamps'] = outputs[f'{self.label}_camera_timestamps'] 2 ctx1ab

266 except ALFObjectNotFound: 1 ctx1i

267 _log.warning('no camera.times ALF found for session') 1 ctx1i

268 

269 # Get audio and wheel data 

270 wheel_keys = ('timestamps', 'position') 6 ctx1caihbd

271 try: 6 ctx1caihbd

272 # glob in case wheel data are in sub-collections 

273 alf_path = next(alf_path.rglob('*wheel.timestamps*')).parent 6 ctx1caihbd

274 self.data['wheel'] = alfio.load_object(alf_path, 'wheel', short_keys=True) 5 ctx1cahbd

275 except (StopIteration, ALFObjectNotFound): 1 ctx1i

276 # Extract from raw data 

277 if self.sync != 'bpod' and self.sync is not None: 1 ctx1i

278 if ns == 'spikeglx': 

279 wheel_data = ephys_fpga.extract_wheel_sync(sync, chmap) 

280 elif ns == 'timeline': 

281 extractor = mesoscope.TimelineTrials(self.session_path, sync_collection=self.sync_collection) 

282 wheel_data = extractor.extract_wheel_sync() 

283 else: 

284 raise NotImplementedError(f'Unknown namespace "{ns}"') 

285 else: 

286 wheel_data = training_wheel.get_wheel_position( 1 ctx1i

287 self.session_path, task_collection=task_collection) 

288 self.data['wheel'] = Bunch(zip(wheel_keys, wheel_data)) 1 ctx1i

289 

290 # Find short period of wheel motion for motion correlation. 

291 if data_for_keys(wheel_keys, self.data['wheel']) and self.data['timestamps'] is not None: 6 ctx1caihbd

292 self.data['wheel'].period = self.get_active_wheel_period(self.data['wheel']) 5 ctx1cahbd

293 

294 # Load Bonsai frame timestamps 

295 try: 6 ctx1caihbd

296 ssv_times = raw.load_camera_ssv_times(self.session_path, self.label) 6 ctx1caihbd

297 self.data['bonsai_times'], self.data['camera_times'] = ssv_times 6 ctx1caihbd

298 except AssertionError: 

299 _log.warning('No Bonsai video timestamps file found') 

300 

301 # Gather information from video file 

302 if load_video: 6 ctx1caihbd

303 _log.info('Inspecting video file...') 5 ctx1caibd

304 self.load_video_data() 5 ctx1caibd

305 

306 def load_video_data(self): (empty)

307 """Get basic properties of video. 

308 

309 Updates the `data` property with video metadata such as length and frame count, as well as 

310 loading some frames to perform QC on. 

311 """ 

312 try: 6 ctx1fcaibd

313 self.data['video'] = get_video_meta(self.video_path, one=self.one) 6 ctx1fcaibd

314 # Sample some frames from the video file 

315 indices = np.linspace(100, self.data['video'].length - 100, self.n_samples).astype(int) 6 ctx1fcaibd

316 self.frame_samples_idx = indices 6 ctx1fcaibd

317 self.data['frame_samples'] = get_video_frames_preload(self.video_path, indices, 6 ctx1fcaibd

318 mask=np.s_[:, :, 0]) 

319 except AssertionError: 

320 _log.error('Failed to read video file; setting outcome to CRITICAL') 

321 self._outcome = spec.QC.CRITICAL 

322 

323 @staticmethod (empty)

324 def get_active_wheel_period(wheel, duration_range=(3., 20.), display=False): (empty)

325 """ 

326 Find period of active wheel movement. 

327 

328 Attempts to find a period of movement where the wheel accelerates and decelerates for the 

329 wheel motion alignment QC. 

330 

331 :param wheel: A Bunch of wheel timestamps and position data 

332 :param duration_range: The candidates must be within min/max duration range 

333 :param display: If true, plot the selected wheel movement 

334 :return: 2-element array comprising the start and end times of the active period 

335 """ 

336 pos, ts = wh.interpolate_position(wheel.timestamps, wheel.position) 6 ctx1ocahbd

337 v, acc = wh.velocity_filtered(pos, 1000) 6 ctx1ocahbd

338 on, off, *_ = wh.movements(ts, acc, pos_thresh=.1, make_plots=False) 6 ctx1ocahbd

339 edges = np.c_[on, off] 6 ctx1ocahbd

340 indices, _ = np.where(np.logical_and( 6 ctx1ocahbd

341 np.diff(edges) > duration_range[0], np.diff(edges) < duration_range[1])) 

342 if len(indices) == 0: 6 ctx1ocahbd

343 _log.warning('No period of wheel movement found for motion alignment.') 1 ctx1o

344 return None 1 ctx1o

345 # Pick movement somewhere in the middle 

346 i = indices[int(indices.size / 2)] 5 ctx1cahbd

347 if display: 5 ctx1cahbd

348 _, (ax0, ax1) = plt.subplots(2, 1, sharex='all') 

349 mask = np.logical_and(ts > edges[i][0], ts < edges[i][1]) 

350 ax0.plot(ts[mask], pos[mask]) 

351 ax1.plot(ts[mask], acc[mask]) 

352 return edges[i] 5 ctx1cahbd

353 

354 def ensure_required_data(self): (empty)

355 """Ensure the datasets required for QC are local. 

356 

357 If the download_data attribute is True, any missing data are downloaded. If all the data 

358 are not present locally at the end of it an exception is raised. If the stream attribute 

359 is True, the video file is not required to be local, however it must be remotely accessible. 

360 NB: Requires a valid instance of ONE and a valid session eid. 

361 

362 Raises 

363 ------ 

364 AssertionError 

365 The data requires for complete QC are not present. 

366 """ 

367 assert self.one is not None, 'ONE required to download data' 1 ctx1k

368 

369 sess_params = {} 1 ctx1k

370 if self.download_data: 1 ctx1k

371 dset = self.one.list_datasets(self.session_path, '*experiment.description*', details=True) 

372 if self.one._check_filesystem(dset): 

373 sess_params = read_params(self.session_path) or {} 

374 else: 

375 sess_params = read_params(self.session_path) or {} 1 ctx1k

376 self._set_sync(sess_params) 1 ctx1k

377 

378 # Get extractor type 

379 is_ephys = 'ephys' in (self.type or self.one.get_details(self.eid)['task_protocol']) 1 ctx1k

380 self.sync = self.sync or ('nidq' if is_ephys else 'bpod') 1 ctx1k

381 

382 is_fpga = 'bpod' not in self.sync 1 ctx1k

383 

384 # dataset collections outside this list are ignored (e.g. probe00, raw_passive_data) 

385 collections = ( 1 ctx1k

386 'alf', '', get_task_collection(sess_params), get_video_collection(sess_params, self.label) 

387 ) 

388 dtypes = self.dstypes + self.dstypes_fpga if is_fpga else self.dstypes 1 ctx1k

389 assert_unique = True 1 ctx1k

390 # Check we have raw ephys data for session 

391 if is_ephys: 1 ctx1k

392 if len(self.one.list_datasets(self.eid, collection='raw_ephys_data')) == 0: 1 ctx1k

393 # Assert 3A probe model; if so download all probe data 

394 det = self.one.get_details(self.eid, full=True) 

395 probe_model = next(x['model'] for x in det['probe_insertion']) 

396 assert probe_model == '3A', 'raw ephys data missing' 

397 collections += (self.sync_collection or 'raw_ephys_data',) 

398 if sess_params: 

399 probes = sess_params.get('devices', {}).get('neuropixel', {}) 

400 probes = set(x.get('collection') for x in chain(*map(dict.values, probes))) 

401 collections += tuple(probes) 

402 else: 

403 collections += ('raw_ephys_data/probe00', 'raw_ephys_data/probe01') 

404 assert_unique = False 

405 else: 

406 # 3B probes have data in root collection 

407 collections += ('raw_ephys_data',) 1 ctx1k

408 for dstype in dtypes: 1 ctx1k

409 datasets = self.one.type2datasets(self.eid, dstype, details=True) 1 ctx1k

410 if 'camera' in dstype.lower(): # Download individual camera file 1 ctx1k

411 datasets = filter_datasets(datasets, filename=f'.*{self.label}.*') 1 ctx1k

412 else: # Ignore probe datasets, etc. 

413 _datasets = filter_datasets(datasets, collection=collections, assert_unique=assert_unique) 1 ctx1k

414 if '' in collections: # Must be handled as a separate query 1 ctx1k

415 datasets = filter_datasets(datasets, collection='', assert_unique=assert_unique) 1 ctx1k

416 datasets = pd.concat([datasets, _datasets]).sort_index() 1 ctx1k

417 else: 

418 datasets = _datasets 

419 

420 if any(x.endswith('.mp4') for x in datasets.rel_path) and self.stream: 1 ctx1k

421 names = [x.split('/')[-1] for x in self.one.list_datasets(self.eid, details=False)] 

422 assert f'_iblrig_{self.label}Camera.raw.mp4' in names, 'No remote video file found' 

423 continue 

424 optional = ('camera.times', '_iblrig_Camera.raw', 'wheel.position', 'wheel.timestamps', 1 ctx1k

425 '_iblrig_Camera.timestamps', '_iblrig_Camera.frame_counter', '_iblrig_Camera.GPIO', 

426 '_iblrig_Camera.frameData', '_ibl_experiment.description') 

427 present = ( 1 ctx1k

428 self.one._check_filesystem(datasets) 

429 if self.download_data 

430 else (next(self.session_path.rglob(d), None) for d in datasets['rel_path']) 

431 ) 

432 

433 required = (dstype not in optional) 1 ctx1k

434 all_present = not datasets.empty and all(present) 1 ctx1k

435 assert all_present or not required, f'Dataset {dstype} not found' 1 ctx1k

436 

437 if not self.type and self.sync != 'nidq': 

438 self._type = get_session_extractor_type(self.session_path) 

439 

440 def _set_sync(self, session_params=False): (empty)

441 """Set the sync and sync_collection attributes if not already set. 

442 

443 Also set the type attribute based on the sync. NB The type attribute is for legacy sessions. 

444 

445 Parameters 

446 ---------- 

447 session_params : dict, bool 

448 The loaded experiment description file. If False, attempts to load it from the session_path. 

449 """ 

450 if session_params is False: 7 ctx1kcaihbd

451 if not self.session_path: 

452 raise ValueError('No session path set') 

453 session_params = read_params(self.session_path) 

454 sync, sync_dict = get_sync(session_params) 7 ctx1kcaihbd

455 self.sync = self.sync or sync 7 ctx1kcaihbd

456 self.sync_collection = self.sync_collection or sync_dict.get('collection') 7 ctx1kcaihbd

457 if self.sync: 7 ctx1kcaihbd

458 self._type = 'ephys' if self.sync == 'nidq' else 'training' 3 ctx1chd

459 

460 def _update_meta_from_session_params(self, sess_params): (empty)

461 """ 

462 Update the default expected video properties. 

463 

464 Use properties defined in the experiment description file, if present. This updates the 

465 `video_meta` property with the fps, width and height for the type and camera label. 

466 

467 Parameters 

468 ---------- 

469 sess_params : dict 

470 The loaded experiment description file. 

471 """ 

472 try: 6 ctx1caihbd

473 assert sess_params 6 ctx1caihbd

474 video_pars = sess_params.get('devices', {}).get('cameras', {}).get(self.label) 3 ctx1chd

475 except (AssertionError, KeyError): 3 ctx1aib

476 return 3 ctx1aib

477 PROPERTIES = ('width', 'height', 'fps') 3 ctx1chd

478 video_meta = copy.deepcopy(self.video_meta) # must re-assign as it's a class attribute 3 ctx1chd

479 if self.type not in video_meta: 3 ctx1chd

480 video_meta[self.type] = {} 

481 if self.label not in video_meta[self.type]: 3 ctx1chd

482 video_meta[self.type][self.label] = {} 

483 video_meta[self.type][self.label].update( 3 ctx1chd

484 **{k: v for k, v in video_pars.items() if k in PROPERTIES} 

485 ) 

486 self.video_meta = video_meta 3 ctx1chd

487 

488 def run(self, update: bool = False, **kwargs) -> (str, dict): (empty)

489 """ 

490 Run video QC checks and return outcome. 

491 

492 :param update: if True, updates the session QC fields on Alyx 

493 :param download_data: if True, downloads any missing data if required 

494 :param extract_times: if True, re-extracts the camera timestamps from the raw data 

495 :returns: overall outcome as a str, a dict of checks and their outcomes 

496 """ 

497 _log.info(f'Computing QC outcome for {self.label} camera, session {self.eid}') 5 ctx1caibd

498 namespace = f'video{self.label.capitalize()}' 5 ctx1caibd

499 if all(x is None for x in self.data.values()): 5 ctx1caibd

500 self.load_data(**kwargs) 4 ctx1caid

501 if self.data['frame_samples'] is None or self.data['timestamps'] is None: 5 ctx1caibd

502 return spec.QC.NOT_SET, {} 1 ctx1i

503 if self.data['timestamps'].shape[0] == 0: 4 ctx1cabd

504 _log.error(f'No timestamps for {self.label} camera; setting outcome to CRITICAL') 

505 return spec.QC.CRITICAL, {} 

506 

507 def is_metric(x): 4 ctx1cabd

508 return isfunction(x) and x.__name__.startswith('check_') 4 ctx1cabd

509 # import importlib 

510 # classe = getattr(importlib.import_module(self.__module__), self.__name__) 

511 # print(classe) 

512 

513 checks = getmembers(self.__class__, is_metric) 4 ctx1cabd

514 checks = self._remove_check(checks) 4 ctx1cabd

515 self.metrics = {f'_{namespace}_' + k[6:]: fn(self) for k, fn in checks} 4 ctx1cabd

516 

517 values = [x if isinstance(x, spec.QC) else x[0] for x in self.metrics.values()] 4 ctx1cabd

518 outcome = max(map(spec.QC.validate, values)) 4 ctx1cabd

519 

520 if update: 4 ctx1cabd

521 extended = { 2 ctx1cd

522 k: spec.QC.NOT_SET if v is None else v 

523 for k, v in self.metrics.items() 

524 } 

525 self.update_extended_qc(extended) 2 ctx1cd

526 self.update(outcome, namespace) 2 ctx1cd

527 return outcome, self.metrics 4 ctx1cabd

528 

529 def _remove_check(self, checks): (empty)

530 """ 

531 Remove one or more check functions from QC checklist. 

532 

533 Parameters 

534 ---------- 

535 checks : list of tuple 

536 The complete list of check function name and handle. 

537 

538 Returns 

539 ------- 

540 list of tuple 

541 The list of check function name and handle, sans names in `checks_to_remove` property. 

542 """ 

543 if len(self.checks_to_remove) == 0: 4 ctx1cabd

544 return checks 4 ctx1cabd

545 else: 

546 for check in self.checks_to_remove: 

547 check_names = [ch[0] for ch in checks] 

548 idx = check_names.index(check) 

549 checks.pop(idx) 

550 return checks 

551 

552 def check_brightness(self, bounds=(40, 200), max_std=20, roi=True, display=False): (empty)

553 """Check that the video brightness is within a given range. 

554 

555 The mean brightness of each frame must be with the bounds provided, and the standard 

556 deviation across samples frames should be less than the given value. Assumes that the 

557 frame samples are 2D (no colour channels). 

558 

559 :param bounds: For each frame, check that: bounds[0] < M < bounds[1], 

560 where M = mean(frame). If less than 75% of sample frames outside of these bounds, the 

561 outcome is WARNING. If <75% of frames within twice the bounds, the outcome is FAIL. 

562 :param max_std: The standard deviation of the frame luminance means must be less than this 

563 :param roi: If True, check brightness on ROI of frame 

564 :param display: When True the mean frame luminance is plotted against sample frames. 

565 The sample frames with the lowest and highest mean luminance are shown. 

566 """ 

567 if self.data['frame_samples'] is None: 6 ctx1lcabgd

568 return spec.QC.NOT_SET 1 ctx1l

569 if roi is True: 6 ctx1lcabgd

570 _, h, w = self.data['frame_samples'].shape 6 ctx1lcabgd

571 if self.label == 'body': # Latter half 6 ctx1lcabgd

572 roi = (slice(None), slice(None), slice(int(w / 2), None, None)) 1 ctx1g

573 elif self.label == 'left': # Top left quadrant (~2/3, 1/2 height) 6 ctx1lcabgd

574 roi = (slice(None), slice(None, int(h / 2), None), slice(None, int(w * .66), None)) 6 ctx1lcabgd

575 else: # Top right quadrant (~2/3 width, 1/2 height) 

576 roi = (slice(None), slice(None, int(h / 2), None), slice(int(w * .66), None, None)) 1 ctx1g

577 else: 

578 roi = (slice(None), slice(None), slice(None)) 

579 brightness = self.data['frame_samples'][roi].mean(axis=(1, 2)) 6 ctx1lcabgd

580 # dims = self.data['frame_samples'].shape 

581 # brightness /= np.array((*dims[1:], 255)).prod() # Normalize 

582 

583 if display: 6 ctx1lcabgd

584 f = plt.figure() 1 ctx1l

585 gs = f.add_gridspec(2, 3) 1 ctx1l

586 indices = self.frame_samples_idx 1 ctx1l

587 # Plot mean frame luminance 

588 ax = f.add_subplot(gs[:2, :2]) 1 ctx1l

589 plt.plot(indices, brightness, label='brightness') 1 ctx1l

590 ax.set( 1 ctx1l

591 xlabel='frame #', 

592 ylabel='brightness (mean pixel)', 

593 title='Brightness') 

594 ax.hlines(bounds, 0, indices[-1], 1 ctx1l

595 colors='tab:orange', linestyles=':', label='warning bounds') 

596 ax.hlines((bounds[0] / 2, bounds[1] * 2), 0, indices[-1], 1 ctx1l

597 colors='r', linestyles=':', label='failure bounds') 

598 ax.legend() 1 ctx1l

599 # Plot min-max frames 

600 for i, idx in enumerate((np.argmax(brightness), np.argmin(brightness))): 1 ctx1l

601 a = f.add_subplot(gs[i, 2]) 1 ctx1l

602 ax.annotate('*', (indices[idx], brightness[idx]), # this is the point to label 1 ctx1l

603 textcoords='offset points', xytext=(0, 1), ha='center') 

604 frame = self.data['frame_samples'][idx][roi[1:]] 1 ctx1l

605 title = ('min' if i else 'max') + ' mean luminance = %.2f' % brightness[idx] 1 ctx1l

606 self.imshow(frame, ax=a, title=title) 1 ctx1l

607 

608 PCT_PASS = .75 # Proportion of sample frames that must pass 6 ctx1lcabgd

609 # Warning if brightness not within range (3/4 of frames must be between bounds) 

610 warn_range = np.logical_and(brightness > bounds[0], brightness < bounds[1]) 6 ctx1lcabgd

611 warn_range = 'PASS' if sum(warn_range) / self.n_samples > PCT_PASS else 'WARNING' 6 ctx1lcabgd

612 # Fail if brightness not within twice the range or std less than threshold 

613 fail_range = np.logical_and(brightness > bounds[0] / 2, brightness < bounds[1] * 2) 6 ctx1lcabgd

614 within_range = sum(fail_range) / self.n_samples > PCT_PASS 6 ctx1lcabgd

615 fail_range = 'PASS' if within_range and np.std(brightness) < max_std else 'FAIL' 6 ctx1lcabgd

616 return self.overall_outcome([warn_range, fail_range]) 6 ctx1lcabgd

617 

618 def check_file_headers(self): (empty)

619 """Check reported frame rate matches FPGA frame rate.""" 

620 if None in (self.data['video'], self.video_meta): 6 ctx1xcabgd

621 return spec.QC.NOT_SET 1 ctx1x

622 expected = self.video_meta[self.type][self.label] 6 ctx1xcabgd

623 return spec.QC.PASS if self.data['video']['fps'] == expected['fps'] else spec.QC.FAIL 6 ctx1xcabgd

624 

625 def check_framerate(self, threshold=1.): (empty)

626 """Check camera times match specified frame rate for camera. 

627 

628 :param threshold: The maximum absolute difference between timestamp sample rate and video 

629 frame rate. NB: Does not take into account dropped frames. 

630 """ 

631 if any(x is None for x in (self.data['timestamps'], self.video_meta)): 5 ctx1vcabd

632 return spec.QC.NOT_SET 1 ctx1v

633 fps = self.video_meta[self.type][self.label]['fps'] 5 ctx1vcabd

634 Fs = 1 / np.median(np.diff(self.data['timestamps'])) # Approx. frequency of camera 5 ctx1vcabd

635 return spec.QC.PASS if abs(Fs - fps) < threshold else spec.QC.FAIL, float(round(Fs, 3)) 5 ctx1vcabd

636 

637 def check_pin_state(self, display=False): (empty)

638 """Check the pin state reflects Bpod TTLs.""" 

639 if not data_for_keys(('video', 'pin_state', 'audio'), self.data): 5 ctx1mcabd

640 return spec.QC.NOT_SET 3 ctx1mcd

641 size_diff = int(self.data['pin_state'].shape[0] - self.data['video']['length']) 3 ctx1mab

642 # NB: The pin state can be high for 2 consecutive frames 

643 low2high = np.insert(np.diff(self.data['pin_state'][:, -1].astype(int)) == 1, 0, False) 3 ctx1mab

644 # NB: Time between two consecutive TTLs can be sub-frame, so this will fail 

645 ndiff_low2high = int(self.data['audio'][::2].size - sum(low2high)) 3 ctx1mab

646 # state_ttl_matches = ndiff_low2high == 0 

647 # Check within ms of audio times 

648 if display: 3 ctx1mab

649 plt.Figure() 1 ctx1m

650 plt.plot(self.data['timestamps'][low2high], np.zeros(sum(low2high)), 'o', 1 ctx1m

651 label='GPIO Low -> High') 

652 plt.plot(self.data['audio'], np.zeros(self.data['audio'].size), 'rx', 1 ctx1m

653 label='Audio TTL High') 

654 plt.xlabel('FPGA frame times / s') 1 ctx1m

655 plt.gca().set(yticklabels=[]) 1 ctx1m

656 plt.gca().tick_params(left=False) 1 ctx1m

657 plt.legend() 1 ctx1m

658 

659 outcome = self.overall_outcome( 3 ctx1mab

660 ('PASS' if size_diff == 0 else 'WARNING' if np.abs(size_diff) < 5 else 'FAIL',