MRG: Improve docstring of mne.io.Info and improve error messages in Info._attributes

[mscheltienne]

Next small PR to improve Info.

1. Most of the long list of attributes in the docstring is sorted in alphabetical order; except attributes that were added later on and where .. versionadded:: x.xx is specified. It complicates navigation on the API Page, and it makes it difficult to find the docstring of the attribute we are looking for.

2. Some error messages in _attributes could be improved. I added the methods to use for nchan and projs, but I don't know which methods/functions should be proposed to the user for the remaining attributes.

3. Some attributes are not present in the docstring. Missing attributes are:

   • command_line
   • filename
   • kit_system_id
   • maxshield
   • meas_file
   • mri_file
   • mri_head_t
   • mri_id
   • working_dir
   • xplotter_layout

Are they all deprecated and present for backward compatibility only?
If this is the case, I will add it to the error message.

4. What are the public attributes that the user can directly set?

For now, in the docstring, it says bads, description, experimenter, and line_freq.
But, in practice it also includes dev_head_t, subject_info, device_info and helium_info. Do you agree with this extended list or would you prefer to have some of those become locked?

[larsoner]

command_line
filename
meas_file
mri_file
mri_id
working_dir
xplotter_layout

For these I'm not sure, we'll have to look at the fiff-constants repo + mne/io/constants.py to figure it out. I'm guessing they are really only used for / by MEGIN / Elekta nowadays.

kit_system_id

We use this one in the KIT reader, it identifies the MEG system in use

maxshield

We use this to say whether active shielding (IAS) was active for the raw data

mri_head_t

We set this when saving a forward solution (maybe inverse, too?) but in general people shouldn't set or use this themselves, and it shouldn't be a part of raw/epochs/evoked data.

[mscheltienne]

meas_file and mri_file refer to FIFF.FIFF_MNE_FILE_NAME = 3508 and mne_file_name 3508 string.
They are both used only in forward/inverse/source estimation.

[mscheltienne]

For mri_id, file MNE-sample-data/MEG/sample/sample_audvis-eeg-oct-6-fwd.fif contains:

forward['info']['mri_id']
Out[12]: 
{'version': 65539,
 'machid': array([-1035262720,        6388], dtype=int32),
 'secs': 1316194493,
 'usecs': 320003}

Very similar to file_id, which is not defined in this loaded forward model.
Is mri_id the equivalent to file_id for forward/inverse instances?

[mscheltienne]

All good for me; the 4 last attributes that are missing from the docstring command_line, filename, working_dir and xplotter_layout, well I have no idea what they are supposed to be and how they should be described in the docstring.

I also feel like the docstring is not very clear as it is, as it mixes attributes for Raw, Epochs, Evoked, Forward, ... + it mixes attributes that can be changed and read-only attributes.

Anyway, this is already a small improvement compared to the previous docstring; feel free to change any description to suit you best.

[larsoner]

One way to find what these means is figure out the correspondence between mne/io/constants.py:FIFF and https://github.com/mne-tools/fiff-constants. For example, command_line doing:

$ git grep command_line
...
mne/source_space.py:                    src.info['command_line'] = tag.data

you can see where it's actually read from file. (You can also in our code how we set it using other entries in the git grep, --it's the command-line entry that gave rise to the object -- but let's follow the constants anyway because this won't always be the case.) Looking in that area in source_space.py, the constant is FIFF_MNE_ENV_COMMAND_LINE, which is 3551 in constants.py (by another git grep), and then cloning the fiff-constants repo another git grep 3551 points to:

DictionaryTags_MNE.txt:mne_env_command_line        3551  string   "The command used to create the file"

Can you try with the others, too?

[mscheltienne]

@larsoner That was already clear from your previous message, and I did look into:

• Where is ['attribute'] used in MNE code.
• What is the ID corresponding and info in io/constants.py
• What does this ID correspond to in fiff-constants

For these 4 last ones, it was not very clear to me, and I could not make out a description I was confident enough with.

• command_line seems to contain the command that was used to generate the instance (used in source estimation). I am not familiar with the command-line API of MNE, and I don't know what this command could be.
• working_dir seems to contain the (path?) to the directory from which the command was executed. Same, I don't see in which API it might be used.
• xplotter_layout, if I recall correctly the description was Xplotter.. Again, that one is a mystery fo me.
• filename, I don't remember what I saw.

If you want I can post in a comment later today or tomorrow the relation/what I find in the fiff-constants and use cases in MNE for each of them. Maybe it will make sense to you and you can then propose type/description for each of them.

[larsoner]

@larsoner That was already clear from your previous message, and I did look into:

Ahh sorry didn't realize I already told you how to do this :)

command_line seems to contain the command ...
working_dir seems to contain the (path?) to the directory from which the command was executed...

This behavior is hidden in the code somewhere, but just to give an example:

$ cd  # goes to /home/larsoner
$ python
>>> import mne
>>> src = mne.setup_source_space('sample', subjects_dir=mne.datasets.sample.data_path() + '/subjects', add_dist='patch')
>>> src.info['command_line']
'setup_source_space(sample, spacing=oct6, surface=white, subjects_dir=/home/larsoner/mne_data/MNE-sample-data/subjects, add_dist=patch, verbose=None)'
>>> src.info['working_dir']
'/home/larsoner'

Since we don't have a command_line exactly, we give the Python command. And the working_dir is the current directory that was used (which isn't really very useful, but we add it anyway).

xplotter_layout, if I recall correctly the description was Xplotter.. Again, that one is a mystery fo me.

Xplotter is a Neuromag plotting utility. We never change/set this ourselves, we just preserve it if it already exists in the object.

filename, I don't remember what I saw.

For this I see:

doc/changes/0.14.inc:- The measurement info :class:`Info` no longer contains a potentially misleading ``info['filename']`` entry.

So I don't think it should exist anymore. If it does, it's probably a bug.

[mscheltienne]

@larsoner Ok, it does start to make some sense. So command_line and working_dir are storing the arguments that were used to create a source space (meshing, spacing, ...).

Docstring proposition:

command_line : str
    Contains the command and arguments used to create the source space (used in source estimation).
working_dir : str
    Path to the working directory used when the source space was created (used in source estimation).

For the Xplotter, what is the python type associated with it? Description could be: Xplotter utility (Neuromag only)..

For filename, I did think it was deprecated, but it does appear in:

• KIT reader: mne.io.kit.kit.py:442
• Test for Info: mne.io.tests.test_meas_info:479
• Label: mne.label.py:252 self.filename = state['filename'] (I am not sure this is related to Info)
• BEM: mne.bem.py:1196 vol_info['filename'] = mgz

Let's remove it for good in this PR.

[larsoner]

KIT reader: mne.io.kit.kit.py:442

Does this end up in raw.info or is it in some private info object? I think it's the latter...

Test for Info: mne.io.tests.test_meas_info:479

If you follow this to meas_info.py you see around line 961 (from 5 years ago):

        if 'filename' in self:
            warn('the "filename" key is misleading '
                 'and info should not have it')

So it's fine to make this an error nowadays, just like any other invalid key.

Label: mne.label.py:252 self.filename = state['filename'] (I am not sure this is related to Info)

No this is pickling or something I think, label has no info

BEM: mne.bem.py:1196 vol_info['filename'] = mgz

This is also not the same as our Info / meas_info

[mscheltienne]

@larsoner All 4 correct ;) I removed the unnecessary warning in _check_consistency() and the associated test. I renamed the variable filename to input_fname for the KIT reader (name of the argument passed that was renamed to filename).

Any idea on the type of the variable in Info['xplotter_layout']?

[larsoner]

str

https://github.com/mne-tools/fiff-constants/blob/aae5960007ee8a67dfc07535ea37d421d37dfe1b/DictionaryTags.txt#L649

[mscheltienne]

Ok, well that settles it. Now all attributes from Info are present in the attribute section of the docstring. It might not always be the best description, but it can be improved when encountered later. Thanks a lot @larsoner !

[larsoner]

Can you add an entry in latest.inc in the enhancements section? I think the proper complete documentation of all of these params is long overdue and well worth an entry!

[mscheltienne]

Done, let's see if I added the entry correctly or if the doc build is unhappy 😅

[larsoner]

Just a few minor comments, otherwise LGTM

[larsoner]

Thanks @mscheltienne !