[ENH] add MultipleLabels IntendedFor method

[octomike]

This is a suggestion for yet another IntendedFor method. We had some success using PlainAcquisitionLabel merged a while back, but there are a number of cases where our site-wide heuristic requires more than that.

We often get duplicated files using the prescan normalization method of our scanner. Currently we name it rec-norm (I'm aware of this beast, we decided to use rec to be bids valid for now). The issue with this however is that we cannot base our IntendedFor matching decision solely on acq, because we have two groups now:

fmap/sub-foo_acq-se_dir-AP_rec-norm_epi.json
fmap/sub-foo_acq-se_dir-PA_rec-norm_epi.json
fmap/sub-foo_acq-se_dir-AP_epi.json
fmap/sub-foo_acq-se_dir-PA_epi.json

and

func/sub-foo_task-t_acq-se_rec-norm_run-01_bold.json
func/sub-foo_task-t_acq-se_rec-norm_run-02_bold.json
func/sub-foo_task-t_acq-se_run-01_bold.json
func/sub-foo_task-t_acq-se_run-02_bold.json

And as I understand, fmaps with rec-norm are intended only for the corresponding functionals with rec-norm .

We could introduce a second label acq-senorm and use that, however, the entity modification with rec- happens way after our protocol modifications (we heavly rely on reproin.fix_dbic_protocol() and a set of regexes.

---

Using a combination of acq and rec as they key would help us out here. I decided to create a slightly more generic approach with this PR, instead of just introducing PlainAcquisitionRecLabel or something similar.

Using MultipleLabels, a heuristic user can now base the decision on one ore more entities, configurable with a new paramter parameter_opts in POPULATE_INTENDED_FOR_OPTS. (I added an example to the docs)

It's mildly invasive, because we have to carry these options along in bids.py - however, I tried to make sure that nothing breaks with reproin or any other heuristic that is unaware of this new option.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.24%. Comparing base (9fc2318) to head (0bc2916).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #851   +/-   ##
=======================================
  Coverage   83.24%   83.24%           
=======================================
  Files          42       42           
  Lines        4404     4429   +25     
=======================================
+ Hits         3666     3687   +21     
- Misses        738      742    +4     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[octomike]

Many tests are currently failing because of requests and chardet - I guess a release is imminent.