Writing mzIdentML Documents

class psims.mzid.writer.MzIdentMLWriter(outfile, close=None, vocabularies=None, missing_reference_is_error=False, vocabulary_resolver=None, version='1.2.0', **kwargs)

A high level API for generating MzIdentML XML files from simple Python objects.

This class depends heavily on lxml’s incremental file writing API which in turn depends heavily on context managers. Almost all logic is handled inside a context manager and in the context of a particular document. Since all operations assume that they have access to a universal identity map for each element in the document, that map is centralized in this instance.

MzIdentMLWriter inherits from ComponentDispatcher, giving it a context attribute and access to all Component objects pre-bound to that context with attribute-access notation.

outfile

The open, writable file descriptor which XML will be written to.

Type

file

xmlfile

The incremental XML file wrapper which organizes file writes onto outfile. Kept to control context.

Type

lxml.etree.xmlfile

writer

The incremental XML writer produced by xmlfile. Kept to control context.

Type

lxml.etree._IncrementalFileWriter

toplevel

The top level incremental xml writer element which will be closed at the end of file generation. Kept to control context

Type

lxml.etree._FileWriterElement

context

Type

DocumentContext

__enter__()

Begins writing, opening the top-level tag

__exit__(exc_type, exc_value, traceback)

Closes the top-level tag, the XML formatter, and the file itself.

__getattr__(name)

Provide access to an automatically parameterized version of all ComponentBase types which use this instance’s context.

Parameters

name (str) – Component Name

Returns

A partially parameterized instance constructor for the ComponentBase type requested.

Return type

ReprBorrowingPartial

begin()

Writes the doctype and starts the low-level writing machinery

controlled_vocabularies()

Write out the <cvList> element and all its children, including both this format’s default controlled vocabularies and those passed as arguments to this method.this

This method requires writing to have begun.

element(element_name, **kwargs)

Construct and immediately open a subclass instance of TagBase with the given tag name. All other arguments are forwarded to the TagBase constructor.

Parameters

• element_name (str) – The name of the tag type to create

• *args – Arbitrary arguments for the tag

• **kwargs – Key word arguments for the tag

See also

element()

end(exc_type=None, exc_value=None, traceback=None)

Ends the XML document, and flushes and closes the file if appropriate.

format(outfile=None)

This method is deprecated. Previously, the serialization process did not indent the XML in-place and the lxml pretty printer had to be invoked separately. With the addition of XMLFormattingStreamWriter, the XML stream is formatted in-place as it is being streamed to file.

provenance(software=(), owner=(), organization=(), provider=None)

Write the analysis provenance section, a top-level segment of the MzIdentML document

This section should be written early on to register the list of software used in this analysis

Parameters

• software (dict or list of dict, optional) – A single dictionary or list of dictionaries specifying an AnalysisSoftware instance

• owner (dict, optional) – A dictionary specifying a Person instance. If missing, a default person will be created

• organization (dict, optional) – A dictionary specifying a Organization instance. If missing, a default organization will be created

register(entity_type, id)

Pre-declare an entity in the document context. Ensures that a reference look up will be satisfied.

Parameters

• entity_type (str) – An entity type, either a tag name or a component name

• id (int) – The unique id number for the thing registered

Returns

The constructed reference id

Return type

str

validate()

Attempt to perform XSD validation on the XML document this writer wrote

Returns

• bool – Whether or not the document was valid

• lxml.etree.XMLSchema – The schema object where errors are logged

Raises

TypeError – When the file cannot be recovered from the writer object, a TypeError is thrown

write(*args, **kwargs)

Either write a complete XML sub-tree or add free text to the file stream

Parameters

arg (str or lxml.etree.Element) – The entity to be written out.