Improvements to the documentation of the Lobsterenv module

[JaGeo]

I improved the documentation of the LobsterEnv module which was triggered by our updates to LobsterPy (JaGeo/LobsterPy#81) and suggestions by @ajjackson

@janosh : happy to hear additional thoughts from you.

[JaGeo]

@janosh, I tried to add more type hinting but mypy was raising very weird errors.

[ajjackson]

The return value of the function also has an "atoms" entry but I don't see that here?

[JaGeo]

Yes, you are correct. I somehow merged labels and atoms in the description.

[ajjackson]

Where functions are returning a large tuple containing various types and lengths of data, it might be helpful to wrap them up as a NamedTuple. This would be backward-compatible as you still can access the elements by index, but also allows:

• clearer type-hinting than a dict would have, taking advantage of the immutability
• named attribute access for more intelligible code and lower chance of accessing the wrong element by mistake
• easier interactive exploration e.g. in a Jupyter notebook or IPython terminal; we get something a bit more self-describing than a bare list of tuple, but not a complicated new class that might have surprising behaviours

Be aware that while a lot of the old docs and tutorials recommend to use the namedtuple function to produce them, we can now build them with class for clearer type-hinting. See examples at https://docs.python.org/3/library/typing.html#typing.NamedTuple

So we could do something like

class ICOHPNeighboursInfo(NamedTuple):
    total: float
    interaction_sums: List[float]
    n_bonds: int
    labels: List[str]
    atoms: List[SomeAtomTypeOrOther]
    central_isites: List[int]

class LobsterNeighbors(NearNeighbors):
...
    def get_info_icohps_to_neighbors(
        self,
        isites: Optional[List[int]] = None,
        onlycation_isites: bool = True
            ) -> ICOHPNeighboursInfo:
    ...
    return ICOHPNeigboursInfo(summed_icohps, list_icohps, number_bonds, labels, atoms, final_isites)

[JaGeo]

Thanks, @ajjackson , this is a great suggestion. I will implement it as it is much cleaner.

[JaGeo]

@ajjackson , I implemented the named tuple

[janosh]

@janosh, I tried to add more type hinting but mypy was raising very weird errors.

Is the structure arg really optional here? What happens if you don't supply a structure?

[JaGeo]

You are correct. Same is true for "filename_ICOHP".

[janosh]

Thanks @JaGeo! 👍