Develop `Context` class in context.py

[ubdbra001]

The Context class needs to be added, and functionality needs to be developed.

It should reflect the protocols listed here

This class reflects the context for an individual file in a dataset, and so should be instantiated with path to the file in question and the Dataset object for that file.

Functionality that needs to be added:

• schema: Can be accessed from Dataset object
• dataset: Passed on creation
• subject: From entities? Need to develop Subject class?
• path: Generated in the FileParts object
• size: os.path.getsize()?
• entities: Generated in the FileParts object
• datatype: Generated in the FileParts object
• suffix: Generated in the FileParts object
• extension: Generated in the FileParts object
• modality: From datatype?
• sidecar: Needs to use load_sidecar and `walk_back'?
• associations: Need to develop Associations class
• columns: If the current file has .tsv extesion then parse? What to use to parse?
• json: If current file has .json extension then parse using JSON module?
• gzip: Python has in-built gzip module, not sure how to read the header specifically. Need to develop GZip class?
• nifti_header: Need to develop NiftiHeader class. Can use nibabel for most of this, will likely need guidance.
• ome: Need to develop Ome class. Never heard of OME before, so will need guidance.
• tiff: Need to develop Tiff class

I'll start work on the parts that don't require additional classes, but as suggested I'll create stubs for everything else.

@effigies does this look broadly correct?

[effigies]

LGTM.

Some notes:

1. subject: Probably unused, but you could use bst.types.context.Subject and populate its sessions field with a Sessions class modeled after the existing Subjects class:

   python-validator/src/bids_validator/context.py

   Lines 67 to 108 in e9519f3

   	class Subjects:
   	"""Collections of subjects in the dataset."""
   	def __init__(self, tree: FileTree):
   	self._tree = tree
   	@cached_property
   	def sub_dirs(self) -> list[str]:
   	"""Subjects as determined by sub-* directories."""
   	return [
   	child.name
   	for child in self._tree.children.values()
   	if child.is_dir and child.name.startswith('sub-')
   	]
   	@property
   	def participant_id(self) -> list[str] | None:
   	"""The participant_id column of participants.tsv."""
   	if 'participants.tsv' not in self._tree.children:
   	return None
   	return self._get_participant_id(self._tree.children['participants.tsv'])
   	@cached_property
   	def phenotype(self) -> list[str] | None:
   	"""The union of participant_id columns in phenotype files."""
   	if 'phenotype' not in self._tree.children:
   	return None
   	subjects = set()
   	for phenotype_file in self._tree.children['phenotype'].children:
   	if phenotype_file.name.endswith('.tsv'):
   	subjects.update(self._get_participant_id(phenotype_file))
   	return sorted(subjects)
   	@staticmethod
   	def _get_participant_id(phenotype_file: FileTree) -> list[str] | None:
   	columns = load_tsv(phenotype_file)
   	if 'participant_id' not in columns:
   	return None
   	return list(columns['participant_id'])

2. size: I would use file.direntry.stat().st_size, since the stat should already be cached from checking whether the file was a file or directory.
3. modality: Yes, from datatype.
4. sidecar: Yes. If it's more convenient and we don't have a particular need for a standalone load_sidecar function, this it could just be

   @cached_property
   def sidecar(self):
       metadata = {}
       for sidecar in walk_back(self.file, inherit=True):
           ...

5. associations: For the moment can just be bst.types.context.Associations. Since populating this will require parsing and evaluating expressions, I think it's best to defer this.
6. Columns: .tsv and .tsv.gz should be loaded. Note that with .tsv.gz files, the headers are found in sidecar.Columns rather than the first row. For parsing, the JS validator leaves everything as strings, so a simple Namespace() mapping headers onto lists of values is simplest. Could also use Pandas or Polars, but then you need to make sure that you're handling n/as correctly.
7. json: I would suggest we use https://pypi.org/project/orjson and parse from bytes, so orjson.loads(Path(file).read_bytes()). The result would go into a Namespace(). Same story in sidecar, actually, though you'll want to merge the dict before loading into Namespace(). Just flagging now that we'll want to do some intelligent caching around JSON loading.
8. gzip: Agree that it doesn't look like we can do what we want from the gzip module. Will probably be easier to just read the first N bytes and parse the header, as in https://github.com/bids-standard/bids-validator/blob/cf494fd/src/files/gzip.ts. A function like:

   def read_gzip_header(file: FileTree) -> bst.types.context.Gzip:
       with open(file, 'rb') as fobj:
           buffer = fobj.read(512)
       ...
       return Gzip(timestamp, filename, comment)

9. nifti_header: References: Nifti1Header, https://github.com/bids-standard/bids-validator/blob/cf494fd/src/files/nifti.ts#L50-L69
10. tiff and ome: https://github.com/bids-standard/bids-validator/blob/cf494fd/src/files/tiff.ts. I suspect we can use https://github.com/cgohlke/tifffile/.