Matlab file doc and convenience function

README.md

@@ -6,35 +6,6 @@ analysis pipeline.
 ### Installation
 See [INSTALL.md](./INSTALL.md) for installation instructions.
 
-## Development guidelines
-In order to separate the python2, python3, and "currently working" versions 
-(\#socialdistancing) of the pipeline, please use the branches:
-* python2.7: for any development on the 2 version
-* python3.6-dev: for any added features for the python3 version
-* master: very sparingly and only for changes that need to be made in both
- versions as I will be merging changes from master into the development
- branches frequently
-    * Ideally for adding features into any branch, espeically master, create
-     a new branch first, then create a pull request (from within Gitlab) before 
-     merging it back so we can check each others' code. This is just to make
-     sure that we can always use the code that is in the master branch without
-     any issues.
- 
-Branching cheat-sheet:
-```git
-git branch my_branch # Create a new branch called branch_name from master
-git branch my_branch another_branch #Branch from another_branch, not master
-git checkout -b my_branch # Create my_branch and switch to it
-
-# Merge changes from master into your branch
-git pull #get any remote changes in master
-git checkout my_branch
-git merge master
-
-# Merge changes from your branch into another branch
-git checkout another_branch
-git merge my_branch #check the doc for --no-ff option, you might want to use it
-```
 
 ## Quickstart Documentation
 ### Setting up a server
@@ -168,5 +139,70 @@ seg_expt.get_traps_timepoints(timepoint, tile_size=96, channels=None,
                                 z=[0,1,2,3,4])
 ```
 
+## Reading MATLAB files
+*Disclaimer: this is very much still in development so it may not always
+ work for you case. If you run into any problems please let me know, or even
+ better start an Issue on the project describing your problem.*
+
+At the moment the best/only way to read matlab files is through a `matObject`:
+
+```python
+from core.io.matlab import matObject
+cTimelapse = matObject('/path/to/cTimelapse.mat')
+```
+
+You can see an overview of what's in the object:
+```python
+cTimelapse.describe()
+```
+
+The `matObject` has some dictionary-like features although it is *not* a
+dictionary (yet). You can access different parts of the object using keys
+, though, and can use the `keys()` function to do so. This will usually
+work at the first few levels, but if it doesn't you may have run into an
+object that's actually a list or a numpy array.
+
+```python
+cTimelapse.keys()
+```
+
+This should return an iterable of the upper level keys. For example, a
+timelapse object will usually have a `timelapseTrapsOmero` key which you
+can look deeper into in the same manner. Once you've found what you want
+you can usually access it as you would a nested dictionary, for instance:  
+
+```python
+cTimelapse['timelapseTrapsOmero']['cTimepoint']['trapLocations']
+```
+
+## Development guidelines
+In order to separate the python2, python3, and "currently working" versions 
+(\#socialdistancing) of the pipeline, please use the branches:
+* python2.7: for any development on the 2 version
+* python3.6-dev: for any added features for the python3 version
+* master: very sparingly and only for changes that need to be made in both
+ versions as I will be merging changes from master into the development
+ branches frequently
+    * Ideally for adding features into any branch, espeically master, create
+     a new branch first, then create a pull request (from within Gitlab) before 
+     merging it back so we can check each others' code. This is just to make
+     sure that we can always use the code that is in the master branch without
+     any issues.
+ 
+Branching cheat-sheet:
+```git
+git branch my_branch # Create a new branch called branch_name from master
+git branch my_branch another_branch #Branch from another_branch, not master
+git checkout -b my_branch # Create my_branch and switch to it
+
+# Merge changes from master into your branch
+git pull #get any remote changes in master
+git checkout my_branch
+git merge master
+
+# Merge changes from your branch into another branch
+git checkout another_branch
+git merge my_branch #check the doc for --no-ff option, you might want to use it
+```
 
 

core/io/matlab.py

@@ -85,6 +85,10 @@ class matObject:
     def __getitem__(self, item):
         return self.attrs[item]
 
+    def keys(self):
+        """Returns the names of the available properties"""
+        return self.attrs.keys()
+
     def _init_buffer(self):
         fp = open(self.filepath, 'rb')
         rdr = MatFile5Reader(fp, struct_as_record=True, squeeze_me=True)
@@ -273,6 +277,8 @@ def flatten_obj(arr):
     return arr
 
 
+## NOT YET FULLY IMPLEMENTED!
+
 class _Info:
     def __init__(self, info):
         self.info = info