Breaking `BidsDataset` API Changes
- Dominant language
- Python
- Stars
- 23
- Forks
- 16
- PR merge metrics
- No merged PRs in 30d
Description
This issue picks up from #209. There's going to be a few steps involved in establishing the breaking `BidsDataset` API, so we can use this issue for tracking.
- [x] #237
- [x] #238
- [ ] #239
The relevant portion of the API proposal is copied here:
## API
* `BidsDataset.path`
The root path of the datset.
* `BidsDataset.wildcards[]`
Return `{"wildcard": "{snakemake_wildcard}"}` pairings. Any selected entities not found in any component would be silently ignored, allowing a generic version of the current `BidsDataset.subj_wildcards`.
* `BidsDataset.entities[]`
An extension of `BidsComponent.entities`. In the simple case, with one entity in the selector, the entity values across all components which have the entity will be returned in a list. With multiple entities in the selector, a `dict[entity, list[values]` will be returned. If an entity is not found in any component, it could raise an error, or the entity could be ignored.
If used as an iterator, or if `.items`, `.values`, or `.keys` is called, any entity appearing in at least one component will be considered. `dict(BidsDataset.entities)` will be equivalent to selecting every single available entity.
* `BidsDataset.zip_lists[]`
Returns the entity group consensus across all components.
`itertools.product(*BidsDataset.entities[*selected_entities].values())` will be used as the baseline. In other words, all possible combinations of all values of the selected entities found across all components. Each such combination will be called a row. From this baseline, rows with values missing in one or more components will be filtered out. Components with just one of the selected entities will filter out all rows with entity values not found in the component. Components with multiple of the selected entities will filter all rows with entity combinations not found in the component. Components not containing any of the selected entities will not be considered.
Lists are automatically de-duplicated prior to return. This is necessary because different components may have different numbers of entities, making meaningful comparison without de-duplication impossible:
```python
inputs.zip_lists['subject', 'session'] == [
['001', '001', '002', '002'],
['01', '02', '01', '02']
] != [
['001', '001', '002', '002', '001', '001', '002', '002'],
['01', '02', '01', '02', '01', '02', '01', '02']
]
```
Because of this, note that:
```python
entity = "my_entity"
assert inputs.zip_lists[entity] == inputs.entities[entity]
```
`dict(BidsDataset.zip_lists)` will be equivalent to `BidsDataset.zip_list[]`.
If used as an iterator, or if any of `.keys`, `.values`, or `.items` is called, and no selection made, it shall be treated as the `dict` case above.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reviewing the remaining checklist item, #239, alongside the API proposal in this issue; #237 and #238 are already complete. Establish the remaining BidsDataset API behavior and consider the issue done when the checklist and breaking API proposal have been fully addressed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100