ENH: -c ls-studysections to show tables with unique fields in dicom series

[yarikoptic]

• see if should be added (interest?)
• extract into a function
• replace Nones with empty strings?
• move pyout imports/make optional or make mandatory but then add requirement on it
• rudimentary testing
• decide on what functionality could be asked from heuristics -- probably extra fields
• would be nice to have different formatters but dummy CLI interface for commands does not make it possible to provide options

A 'grown up' cousin of ls: With such command can "quickly" see what heudiconv would find for series and specific protocols

$> heudiconv --dbg --command ls-studysessions -f reproin --files David{,2}/DICOM/*
INFO: Running heudiconv version 0.11.3.post7+g64569f1.d20220606 latest 0.11.3
INFO: Analyzing 3748 dicoms
INFO: Filtering out 0 dicoms based on their filename
INFO: Generated sequence info for 2 studies with 23 entries total
INFO: Processing sequence infos to deduce study/session
INFO: Study session for StudySessionInfo(locator='Etypically/emptyhhhhhhhhhhhhhhhhhhhh', session=None, subject='registration (usually the same as patient)')
INFO: Processing sequence infos to deduce study/session
INFO: Study session for StudySessionInfo(locator='Etypically/emptyhhhhhhhhhhhhhhhhhhhh', session=None, subject='registration (usually the same as patient) 2')
StudySessionInfo(locator='Etypically/emptyhhhhhhhhhhhhhhhhhhhh', session=None, subject='registration (usually the same as patient)'):
example_dcm_file series_files series_id                                                            protocol_name                                                    series_description                                             TR   dim1 dim2 dim3
IM_0001          101          101-WIP SmartBrain                                                   WIP SmartBrain                                                   SmartBrain                                                     -1.0 256  256  101 
IM_0461          3            102-WIP MPR - SmartBrain                                             WIP MPR - SmartBrain                                             WIP MPR - SmartBrain                                           -1.0 256  256  3   
IM_0464          55           103-Patient Aligned MPR AWPLAN_SMARTPLAN_TYPE_BRAIN                  Patient Aligned MPR AWPLAN_SMARTPLAN_TYPE_BRAIN                  Patient Aligned MPR AWPLAN_SMARTPLAN_TYPE_BRAIN                -1.0 256  256  55  
IM_0519          205          201-WIP MPragesag7                                                   WIP MPragesag7                                                   MPragesag7                                                     -1.0 256  256  205 
XX_0103          3            302-WIP PRESS_PAR                                                    WIP PRESS_PAR                                                    PRESS_PAR                                                      2.0  1    1    3   
IM_0106          271          401-WIP rsfMRI 1                                                     WIP rsfMRI 1                                                     rsfMRI 1                                                       -1.0 96   96   271 
IM_0378          82           501-WIP DTI Fieldmap P                                               WIP DTI Fieldmap P                                               DTI Fieldmap P                                                 -1.0 144  144  82  
IM_0726          82           601-WIP DTI Fieldmap A                                               WIP DTI Fieldmap A                                               DTI Fieldmap A                                                 -1.0 144  144  82  
IM_1270          460          701-WIP DTI 1                                                        WIP DTI 1                                                        DTI 1                                                          -1.0 144  144  460 
IM_0809          460          801-WIP dwi_run-1_acq-1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx WIP dwi_run-1_acq-1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx dwi_run-1_acq-1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -1.0 144  144  460 
StudySessionInfo(locator='Etypically/emptyhhhhhhhhhhhhhhhhhhhh', session=None, subject='registration (usually the same as patient) 2'):
example_dcm_file series_files series_id                                  protocol_name                              series_description                         TE    TR                 date     dim1 dim2 dim3 image_type                                time     
IM_0005          101          101-WIP SmartBrain                         WIP SmartBrain                             SmartBrain                                 -1.0  -1.0               None     256  256  101                                            None     
IM_0125          3            102-WIP MPR - SmartBrain                   WIP MPR - SmartBrain                       WIP MPR - SmartBrain                       -1.0  -1.0               None     256  256  3                                              None     
IM_0334          55           103-Patient Aligned MPR AWPLAN_SMARTPLA... Patient Aligned MPR AWPLAN_SMARTPLAN_TY... Patient Aligned MPR AWPLAN_SMARTPLAN_TY... -1.0  -1.0               None     256  256  55                                             None     
IM_0128          205          201-WIP anat-T1_acq-mprage                 WIP anat-T1_acq-mprage                     anat-T1_acq-mprage                         -1.0  -1.0               None     256  256  205                                            None     
IM_0107          9            202-VWIP anat-T1_acq-mprage                VWIP anat-T1_acq-mprage                    VWIP anat-T1_acq-mprage                    3.159 0.0069801001548767 20190912 512  512  9    ORIGINAL, PRIMARY, PROJECTION IMAGE, M... 153218.56
IM_0116          9            203-VWIP anat-T1_acq-mprage                VWIP anat-T1_acq-mprage                    VWIP anat-T1_acq-mprage                    3.159 0.0069801001548767 20190912 512  512  9    ORIGINAL, PRIMARY, PROJECTION IMAGE, M... 153218.56
XX_0002          3            302-WIP spect-PRESS_acq-PAR                WIP spect-PRESS_acq-PAR                    spect-PRESS_acq-PAR                        -1.0  2.0                None     1    1    3                                              None     
IM_1664          271          401-WIP func_task-rest_run-01              WIP func_task-rest_run-01                  func_task-rest_run-01                      -1.0  -1.0               None     96   96   271                                            None     
IM_0472          271          501-WIP func_task-rest_run-01_proc-pmc     WIP func_task-rest_run-01_proc-pmc         func_task-rest_run-01_proc-pmc             -1.0  -1.0               None     96   96   271                                            None     
IM_1936          82           601-WIP fmap_dir-PA                        WIP fmap_dir-PA                            fmap_dir-PA                                -1.0  -1.0               None     144  144  82                                             None     
IM_0389          82           701-WIP fmap_dir-AP                        WIP fmap_dir-AP                            fmap_dir-AP                                -1.0  -1.0               None     144  144  82                                             None     
IM_1203          460          801-WIP dwi_run-1_acq-1xxxxxxxxxxxxxxxx... WIP dwi_run-1_acq-1xxxxxxxxxxxxxxxxxxxx... dwi_run-1_acq-1xxxxxxxxxxxxxxxxxxxxxxxx... -1.0  -1.0               None     144  144  460                                            None     
IM_0744          459          802-Reg - WIP dwi_run-1_acq-1xxxxxxxxxx... Reg - WIP dwi_run-1_acq-1xxxxxxxxxxxxxx... Reg - WIP dwi_run-1_acq-1xxxxxxxxxxxxxx... 95.0  0.525404113769531  20190912 144  144  459  ORIGINAL, PRIMARY, M_SE, M, SE            154005.76
heudiconv --dbg --command ls-studysessions -f reproin --files   17.39s user 1.44s system 104% cpu 18.005 total

@tsalo -- WDYT?

[codecov]

Codecov Report

Base: 81.29% // Head: 80.90% // Decreases project coverage by -0.40% ⚠️

Coverage data is based on head (d51eddd) compared to base (aea555b).
Patch coverage: 40.54% of modified lines in pull request are covered.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #572      +/-   ##
==========================================
- Coverage   81.29%   80.90%   -0.40%     
==========================================
  Files          41       41              
  Lines        3817     3854      +37     
==========================================
+ Hits         3103     3118      +15     
- Misses        714      736      +22     

Impacted Files	Coverage Δ
heudiconv/cli/run.py	91.48% <ø> (ø)
heudiconv/main.py	68.78% <4.34%> (-9.89%)	⬇️
heudiconv/tests/test_utils.py	100.00% <100.00%> (ø)
heudiconv/utils.py	91.63% <100.00%> (+0.27%)	⬆️

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.