From 412a340e51a50a130af865033722eb86eabb73d6 Mon Sep 17 00:00:00 2001 From: "Ankur Sinha (Ankur Sinha Gmail)" Date: Tue, 5 Dec 2023 10:38:21 +0000 Subject: [PATCH] docs(writers): document classes and methods And other cosmetic cleanups. --- neuroml/writers.py | 91 ++++++++++++++++++++++++++++++++++------------ 1 file changed, 68 insertions(+), 23 deletions(-) diff --git a/neuroml/writers.py b/neuroml/writers.py index 8a76bcf..35169cf 100644 --- a/neuroml/writers.py +++ b/neuroml/writers.py @@ -2,13 +2,25 @@ from six import string_types +"""Classes to write NeuroML to various formats.""" + + class NeuroMLWriter(object): + """Writes from NeuroMLDocument to nml file. + + In future can implement from other types via chain of responsibility pattern. + """ @classmethod def write(cls, nmldoc, file, close=True): - """ - Writes from NeuroMLDocument to nml file - in future can implement from other types - via chain of responsibility pattern. + """Write a NeuroMLDocument to file. + + :param nmldoc: NeuroML document object to write + :type nmldoc: neuroml.NeuroMLDocument + :param file: file name to write to + :type file: str + :param close: toggle whether file should be closed + :type close: bool + :raises AttributeError: if export fails """ if isinstance(file, string_types): @@ -36,8 +48,21 @@ def write(cls, nmldoc, file, close=True): class NeuroMLHdf5Writer(object): + """Exports NeuroML documents to HDF5 format.""" @classmethod def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True): + """Write a NeuroMLDocument to HDF5 file + + :param nmldoc: NeuroML document object to write + :type nmldoc: neuroml.NeuroMLDocument + :param h5_file_name: file name to write to + :type h5_file_name: str + :param embed_xml: toggle whether XML serialization should be embedded + :type embed_xml: bool + :param compress: toggle compression + :type compress: bool + """ + import tables FILTERS = ( @@ -67,17 +92,13 @@ def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True): try: import StringIO - sf = StringIO.StringIO() - except: + except ImportError: import io - sf = io.StringIO() NeuroMLWriter.write(nml_doc, sf, close=False) - nml2 = sf.getvalue() - rootGroup._f_setattr("neuroml_top_level", nml2) # Put back into previous form... @@ -89,20 +110,20 @@ def write(cls, nml_doc, h5_file_name, embed_xml=True, compress=True): """ @classmethod def write_xml_and_hdf5(cls,nml_doc0,xml_file_name,h5_file_name): - + nml_doc_hdf5 = neuroml.NeuroMLDocument(nml_doc0.id) - + for n in nml_doc0.networks: nml_doc_hdf5.networks.append(n) - + nml_doc0.networks = [] - - nml_doc0.includes.append(neuroml.IncludeType(h5_file_name)) - + + nml_doc0.includes.append(neuroml.IncludeType(h5_file_name)) + NeuroMLWriter.write(nml_doc0,xml_file_name) - + NeuroMLHdf5Writer.write(nml_doc_hdf5,h5_file_name,embed_xml=False) - + # Put back into previous form... for n in nml_doc_hdf5.networks: nml_doc0.networks.append(n) @@ -113,11 +134,22 @@ def write_xml_and_hdf5(cls,nml_doc0,xml_file_name,h5_file_name): class ArrayMorphWriter(object): """ + Write morphology to ArrayMorph format. + For now just testing a simple method which can write a morphology, not a NeuroMLDocument. """ @classmethod def __write_single_cell(cls, array_morph, fileh, cell_id=None): + """Write a array morphology to a file handler. + + :param array_morph: a array morph object containing a morphology + :type array_morph: neuroml.arraymorph.ArrayMorphology + :param fileh: file handler of file to write to + :type fileh: file object + :param cell_id: id of cell + :type cell_id: str + """ vertices = array_morph.vertices connectivity = array_morph.connectivity physical_mask = array_morph.physical_mask @@ -128,12 +160,12 @@ def __write_single_cell(cls, array_morph, fileh, cell_id=None): # Create the groups: # can use morphology name in future? - if array_morph.id == None: + if array_morph.id is None: morphology_name = "Morphology" else: morphology_name = array_morph.id - if cell_id == None: + if cell_id is None: morphology_group = fileh.create_group(root, morphology_name) hierarchy_prefix = "/" + morphology_name else: @@ -151,26 +183,39 @@ def __write_single_cell(cls, array_morph, fileh, cell_id=None): @classmethod def __write_neuroml_document(cls, document, fileh): - document_id = document.id + """Write a NeuroMLDocument containing morphology to a file handler + :param document: a NeuroML document object containing a morphology + :type document: neuroml.NeuroMLDocument + :param fileh: file handler of file to write to + :type fileh: file object + """ for default_id, cell in enumerate(document.cells): morphology = cell.morphology - if morphology.id == None: + if morphology.id is None: morphology.id = "Morphology" + str(default_id) - if cell.id == None: + if cell.id is None: cell.id = "Cell" + str(default_id) cls.__write_single_cell(morphology, fileh, cell_id=cell.id) for default_id, morphology in enumerate(document.morphology): - if morphology.id == None: + if morphology.id is None: morphology.id = "Morphology" + str(default_id) cls.__write_single_cell(morphology, fileh, cell_id=cell.id) @classmethod def write(cls, data, filepath): + """Write morphology to file in ArrayMorph format. + + :param data: data to write + :type data: neuroml.arraymorph.ArrayMorphology or neuroml.NeuroMLDocument + :param filepath: path of file to write to + :type filepath: str + + """ import tables fileh = tables.open_file(filepath, mode="w")