RF: Use XmlSerializable, XmlParser for Gifti load/save

[bcipolli]

CiftiImage (#249) and GiftiImage share a lot of logic. Both have functions for parsing, both will use similar logic for loading and saving. XmlBasedImage and XmlImageParser encapsulates the shared code, and defines a (hopefully) clean object model for any future images that are defined in XML.

• XmlImageParser - a new abstract class that does most of the work here. Defines a structure for parsing XML files; every xml-based image will have to define one, specific to that image format. This essentially generalizes the object model used in parse_gifti_fast.py.
• XmlBasedImage - a light wrapper around FileBasedImage that calls into the XmlImageParser for the image class on read, and takes care of small details on write (call into to_xml()). New required class property: parser (similar usage to header)

Things done:

• Define XmlImageParser and XmlBasedImage
• Migrate GiftiImage to use XmlBasedImage, and parse_gifti_fast to use XmlImageParser
• Deprecate parse_gifti_file and related objects.

Things to do:

• Determine the file structure; there is an unresolvable dependency between gifti.py and parse_gifti_fast.py; each refers to objects in the other. Perhaps we can simply combine them?
• Write tests
• Migrate parse_gifti_fast tests to new object model.
• Add deprecation tests for parse_gifti_file
• Add documentation
• Scrub GIFTI parser code
• Add test to test buffer_size passing via nibabel.load()

I'm pushing this PR out there now as (1) it seems to pass tests and (2) to get feedback on the object model / design as early in the development process as possible.

I'm not in a big rush on this; just wanted to get it out there while it was on my mind.

[bcipolli]

Here, I moved the docstring from GiftiImage.to_file_map to GiftiImage, so that to_file_map could be moved to XmlBasedImage.

[bcipolli]

Checked off all items but one: not sure the best way to avoid the recursive imports here. Should be ready for a looksie anytime--I even tried scrubbing some of the old code :)

[bcipolli]

@effigies I put CiftiImage on top of this code this morning. Turns out that CiftiImage is a Nifti2Image with an xml-based extension; it is not an Xml-based image. This changed two things:

• CiftiImage will not subclass XmlBasedImage; only GiftiImage will.
• The CiftiImage extension will need an xml parser. Using the object model here was great, but XmlImageParser is too specific a name now. I am thinking to change to XmlParser.

I think the object model and abstractions here are good; I'd like to keep them. But, since GiftiImage is the only one using XmlBasedImage, it could be considered overkill. Alternately, I could remove XmlBasedImage, move logic back to GiftiImage, keepxmlutils.py`, and simply add the parser there.

[effigies]

I suppose I'm inclined to not bother with XMLBasedImage if GiftiImage is its only subclass, but I should make it clear that I have not even started to look at this PR. (Busy week. I don't expect to be useful on here until Monday at the earliest.)

[effigies]

Outputter had an initialize method that should be preserved.

[effigies]

Sorry for the delay. This looks reasonable to me.

The main design issue I see is still whether or not we want an XMLBasedImage with only one subclass. In favor of XMLBasedImage, the decoupling work has already been done, and the alternative is to stick generic code into GiftiImage. In opposition, now you have to read another class to understand GiftiImage.

I think I can go either way. If anybody else has strong opinions, I can probably be pushed to one side or the other.

[bcipolli]

I would prefer to move the code back into GiftiImage, rename XmlImageParser to XmlParser (as it's the CIFTI header that's XML-based), and move xmlimages.py back to xmlutils.py.

[effigies]

That sounds good to me.

[bcipolli]

@effigies I did as outlined above, and deprecated Outputter.initialize. Tests pass as well.

[effigies]

Outputter.__init__ doesn't quite do the same thing as Outputter.initialize, since it also calls super(GiftiImageParser, self).__init__, which could change the buffer size and all that. I would just do the original contents, but short, like:

def initialize(self):
    """ Initialize outputter
    """
    self.fsm_state = []
    self.nvpair = self.da = self.coordsys = self.lata = self.label = None
    self.meta_global = self.meta_da = self.write_to = None
    self._char_blocks = None
    self.count_da = True

[bcipolli]

Setting encoding and buffer_size is new. I figured since initialize is deprecated, nobody will call it with those args, nor would those args be non-defaults. I'd prefer to keep the # of lines for deprecated functions minimal.

As a side note, I could remove the arguments from initialize and __init__ to match the original definitions.

LMK what you think.

[effigies]

I would keep the original prototypes and docstring on initialize. But point taken on only defaults being used in any case, so revert the prototypes and I'm okay here.

[bcipolli]

Done.

[effigies]

Should this deprecation be on the class instead of __init__?

[bcipolli]

I probably don't understand what deprecating the class would do; could you help make that clear to me?

In previous cases I remember deprecating __init__ so that the deprecation is lazy--it only triggers if someone instantiates the class, and not when the file is simply imported. That's the only goal here.

[effigies]

I thought the @np.deprecate functions modify documentation. Do they also raise warnings? If so, this makes sense.

[bcipolli]

yep, they raise warnings--I add a deprecation warning test case each time we add this decorator, to make sure.

[effigies]

Okay, LGTM then.

Anybody else have comments?

[bcipolli]

Any chance we can merge this one?

[effigies]

I think people have had a chance to voice objections. In it goes.

[matthew-brett]

Yes, sorry I haven't had a chance to review. Next week is better for me, by Tuesday afternoon I will have more time.

[matthew-brett]

Rewrite comment now you've decided in this implementation?

[effigies]

@matthew-brett Should I revert this merge?

[matthew-brett]

Oh - no - sorry - you did good to merge, thanks for doing it. I was only adding post-merge suggestions. Happy to do that as a PR if it's easier.