{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "v4 (Level 1.0), v6 and v7 to 7.2 matfiles are supported." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "You will need an HDF5 Python library to read MATLAB 7.3 format mat files. Because SciPy does not supply one, we do not implement the HDF5 / 7.3 interface here." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "mat_dict", "annotation": "dict", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "dictionary with variable names as keys, and loaded matrices as values." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Load MATLAB file." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "file_name", "annotation": "str", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Name of the mat file (do not need .mat extension if appendmat==True). Can also pass open file-like object." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mdict", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Dictionary in which to insert matfile variables." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "appendmat", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "True to append the .mat extension to the end of the given filename, if not already present. Default is True." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "spmatrix", "annotation": "bool, optional (default: True)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ", return sparse matrix. Otherwise return sparse array. Format is " }, { "__type": "InlineRole", "__tag": 4003, "value": "COO", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for MatFile 4 and " }, { "__type": "InlineRole", "__tag": 4003, "value": "CSC", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for MatFile 5. Only relevant for sparse variables." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "byte_order", "annotation": "str or None, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "None by default, implying byte order guessed from mat file. Otherwise can be one of ('native', '=', 'little', '<', 'BIG', '>')." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mat_dtype", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, return arrays in same dtype as would be loaded into MATLAB (instead of the dtype with which they are saved)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "squeeze_me", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to squeeze unit matrix dimensions or not." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "chars_as_strings", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to convert char arrays to string arrays." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "matlab_compatible", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Returns matrices as would be loaded by MATLAB (implies squeeze_me=False, chars_as_strings=False, mat_dtype=True, struct_as_record=True)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "struct_as_record", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether to load MATLAB structs as NumPy record arrays, or as old-style NumPy arrays with dtype=object. Setting this flag to False replicates the behavior of scipy version 0.7.x (returning NumPy object arrays). The default setting is True, because it allows easier round-trip load and save of MATLAB files." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "verify_compressed_data_integrity", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Whether the length of compressed sequences in the MATLAB file should be checked, to ensure that they are not longer than we expect. It is advisable to enable this (the default) because overlong compressed sequences in MATLAB files generally indicate that the files have experienced some sort of corruption." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "variable_names", "annotation": "None or sequence", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If None (the default) - read all variables in file. Otherwise, " }, { "__type": "CrossRef", "__tag": 4002, "value": "variable_names", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "variable_names" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " should be a sequence of strings, giving names of the MATLAB variables to read from the file. The reader will skip any variable with a name not in this sequence, possibly saving some read processing." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "simplify_cells", "annotation": "False, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, return a simplified dict structure (which is useful if the mat file contains cell arrays). Note that this only affects the structure of the result and not its contents (which is identical for both output structures). If True, this automatically sets " }, { "__type": "CrossRef", "__tag": 4002, "value": "struct_as_record", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "struct_as_record" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " to False and " }, { "__type": "CrossRef", "__tag": 4002, "value": "squeeze_me", "reference": { "__type": "RefInfo", "__tag": 4000, "module": null, "version": null, "kind": "local", "path": "squeeze_me" }, "kind": "local" }, { "__type": "Text", "__tag": 4046, "value": " to True, which is required to simplify cells." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "uint16_codec", "annotation": "str, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The codec to use for decoding characters, which are stored as uint16 values. The default uses the system encoding, but this can be manually set to other values such as 'ascii', 'latin1', and 'utf-8'. This parameter is relevant only for files stored as v6 and above, and not for files stored as v4." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/io/matlab/_mio.py", "item_line": 86, "item_type": "function", "aliases": [ "scipy.io.loadmat" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "from os.path import dirname, join as pjoin\nimport scipy.io as sio\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGet the filename for an example .mat file from the tests/data directory.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "data_dir = pjoin(dirname(sio.__file__), 'matlab', 'tests', 'data')\nmat_fname = pjoin(data_dir, 'testdouble_7.4_GLNX86.mat')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nLoad the .mat file contents.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "mat_contents = sio.loadmat(mat_fname, spmatrix=False)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe result is a dictionary, one key/value pair for each variable:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sorted(mat_contents.keys())\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "mat_contents['testdouble']\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nBy default SciPy reads MATLAB structs as structured NumPy arrays where the\ndtype fields are of type `object` and the names correspond to the MATLAB\nstruct field names. This can be disabled by setting the optional argument\n`struct_as_record=False`.\n\nGet the filename for an example .mat file that contains a MATLAB struct\ncalled `teststruct` and load the contents.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "matstruct_fname = pjoin(data_dir, 'teststruct_7.4_GLNX86.mat')\nmatstruct_contents = sio.loadmat(matstruct_fname)\nteststruct = matstruct_contents['teststruct']\nteststruct.dtype\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe size of the structured array is the size of the MATLAB struct, not the\nnumber of elements in any particular field. The shape defaults to 2-D\nunless the optional argument `squeeze_me=True`, in which case all length 1\ndimensions are removed.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "teststruct.size\nteststruct.shape\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGet the 'stringfield' of the first element in the MATLAB struct.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "teststruct[0, 0]['stringfield']\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nGet the first element of the 'doublefield'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "teststruct['doublefield'][0, 0]\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nLoad the MATLAB struct, squeezing out length 1 dimensions, and get the item\nfrom the 'complexfield'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "matstruct_squeezed = sio.loadmat(matstruct_fname, squeeze_me=True)\nmatstruct_squeezed['teststruct'].shape\nmatstruct_squeezed['teststruct']['complexfield'].shape\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "matstruct_squeezed['teststruct']['complexfield'].item()\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "file_name", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "mdict", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "appendmat", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "spmatrix", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "kwargs", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "loadmat" }, "references": null, "qa": "scipy.io.matlab._mio:loadmat", "arbitrary": [], "local_refs": [ "appendmat", "byte_order", "chars_as_strings", "file_name", "mat_dict", "mat_dtype", "matlab_compatible", "mdict", "simplify_cells", "spmatrix", "squeeze_me", "struct_as_record", "uint16_codec", "variable_names", "verify_compressed_data_integrity" ] }