diff --git a/advanced_topics/object_oriented_programming.ipynb b/advanced_topics/object_oriented_programming.ipynb
index eee37dd639e9ddacb2d38b7519a1563fa80d7163..38938351a0038bbfe30020abbe041435093e5294 100644
--- a/advanced_topics/object_oriented_programming.ipynb
+++ b/advanced_topics/object_oriented_programming.ipynb
@@ -4,7 +4,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "# Object-oriented programming\n",
+ "# Object-oriented programming in Python\n",
"\n",
"\n",
"By now you might have realised that __everything__ in Python is an\n",
@@ -63,7 +63,7 @@
"> ```\n",
"\n",
"\n",
- "The fundamental difference between a `struct` in C, and a `class` in Python\n",
+ "One of the major differences between a `struct` in C, and a `class` in Python\n",
"and other object oriented languages, is that you can't (easily) add functions\n",
"to a `struct` - it is just a chunk of memory. Whereas in Python, you can add\n",
"functions to your class definition, which will then be added as methods when\n",
@@ -71,10 +71,11 @@
"\n",
"\n",
"Of course there are many more differences between C structs and classes (most\n",
- "notably [inheritance](todo), and [protection](todo)). But if you can\n",
- "understand the difference between a _definition_ of a C struct, and an\n",
- "_instantiation_ of that struct, then you are most of the way towards\n",
- "understanding the difference between a Python _class_, and a Python _object_.\n",
+ "notably [inheritance](todo), [polymorphism](todo), and [access\n",
+ "protection](todo)). But if you can understand the difference between a\n",
+ "_definition_ of a C struct, and an _instantiation_ of that struct, then you\n",
+ "are most of the way towards understanding the difference between a _class_,\n",
+ "and an _object_.\n",
"\n",
"\n",
"> But just to confuse you, remember that in Python, __everything__ is an\n",
@@ -154,9 +155,10 @@
"metadata": {},
"source": [
"Here we have added a _method_ called `__init__` to our class (remember that a\n",
- "_method_ is just a function which is associated with a specific object). This\n",
- "method expects two arguments - `self`, and `inimg`. So now, when we create an\n",
- "instance of the `FSLMaths` class, we will need to provide an input image:"
+ "_method_ is just a function which is defined in a cliass, and which can be\n",
+ "called on instances of that class). This method expects two arguments -\n",
+ "`self`, and `inimg`. So now, when we create an instance of the `FSLMaths`\n",
+ "class, we will need to provide an input image:"
]
},
{
@@ -399,19 +401,13 @@
"\n",
" for oper, value in self.operations:\n",
"\n",
- " # If value is a string, we assume\n",
- " # that it is a path to an image.\n",
- " if isinstance(value, str):\n",
- " image = nib.load(value)\n",
- " value = image.get_data()\n",
- "\n",
- " # Or it could be an image that\n",
+ " # Values could be an image that\n",
" # has already been loaded.\n",
" elif isinstance(value, nib.nifti1.Nifti1Image):\n",
- " value = image.get_data()\n",
+ " value = value.get_data()\n",
"\n",
" # Otherwise we assume that\n",
- " # it is a scalar value.\n",
+ " # values are scalars.\n",
"\n",
" if oper == 'add':\n",
" data = data + value\n",
@@ -445,10 +441,12 @@
"outputs": [],
"source": [
"input = op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm.nii.gz')\n",
- "inimg = nib.load(input)\n",
- "fm = FSLMaths(inimg)\n",
+ "mask = op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm_brain_mask.nii.gz')\n",
+ "input = nib.load(input)\n",
+ "mask = nib.load(mask)\n",
+ "fm = FSLMaths(input)\n",
"\n",
- "fm.mul(op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm_brain_mask.nii.gz'))\n",
+ "fm.mul(mask)\n",
"fm.add(-10)\n",
"\n",
"outimg = fm.run()\n",
@@ -495,7 +493,7 @@
"source": [
"Well, the scary answer is ... there is __nothing__ stopping you from doing\n",
"whatever you want to a Python object. You can add, remove, and modify\n",
- "attribute at will. You can even replace the methods of an existing object if\n",
+ "attributes at will. You can even replace the methods of an existing object if\n",
"you like:"
]
},
@@ -529,7 +527,7 @@
"Python tends to assume that programmers are \"responsible adults\", and hence\n",
"doesn't do much in the way of restricting access to the attributes or methods\n",
"of an object. This is in contrast to languages like C++ and Java, where the\n",
- "notion of a private attribute or method is enforced by the language.\n",
+ "notion of a private attribute or method is strictly enforced by the language.\n",
"\n",
"\n",
"However, there are a couple of conventions in Python that are [universally\n",
@@ -685,9 +683,9 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Property setters are a nice way to restrict the values that a property may\n",
- "take - note that we perform a sanity check in the `input` setter, to make\n",
- "sure that the new input is a NIFTI image:"
+ "Property setters are a nice way to add validation logic when an attribute is\n",
+ "assigned a value. We are doing this in the above example, by making sure that\n",
+ "the new input is a NIFTI image:"
]
},
{
@@ -722,6 +720,370 @@
"> validate the initial `inimg` that was passed in during creation.\n",
"\n",
"\n",
+ "## Inheritance\n",
+ "\n",
+ "\n",
+ "One of the major advantages of an object-oriented programming approach is\n",
+ "_inheritance_ - the ability to define hierarchical relationships between\n",
+ "classes and instances.\n",
+ "\n",
+ "\n",
+ "### The basics\n",
+ "\n",
+ "\n",
+ "For example, a veterinary surgery might be running some Python code which\n",
+ "looks like the following. Perhaps it is used to assist the nurses in\n",
+ "identifying an animal when it arrives at the surgery:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Animal(object):\n",
+ " def noiseMade(self):\n",
+ " raise NotImplementedError('This method is implemented by sub-classes')\n",
+ "\n",
+ "class Dog(Animal):\n",
+ " def noiseMade(self):\n",
+ " return 'Woof'\n",
+ "\n",
+ "class Cat(Animal):\n",
+ " def noiseMade(self):\n",
+ " return 'Meow'\n",
+ "\n",
+ "class Labrador(Dog):\n",
+ " pass\n",
+ "\n",
+ "class Chihuahua(Dog):\n",
+ " def noiseMade(self):\n",
+ " return 'Yap yap yap'"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Hopefully this example doesn't need much in the way of explanation - this\n",
+ "collection of classes captures a hierarchical relationship which exists in the\n",
+ "real world (and also captures the inherently annoying nature of\n",
+ "chihuahuas). For example, in the real world, all dogs are animals, but not all\n",
+ "animals are dogs. Therefore in our model, the `Dog` class has specified\n",
+ "`Animal` as its base class. We say that the `Dog` class _extends_, _derives\n",
+ "from_, or _inherits from_, the `Animal` class, and that all `Dog` instances\n",
+ "are also `Animal` instances (but not vice-versa).\n",
+ "\n",
+ "\n",
+ "What does that `noiseMade` method do? There is a `noiseMade` method defined\n",
+ "on the `Animal` class, but it has been re-implemented, or _overridden_ in the\n",
+ "`Dog`, `Cat`, and `Chihuahua` classes (but not on the `Labrador` class). We\n",
+ "can call the `noiseMade` method on any `Animal` instance, but the specific\n",
+ "behaviour that we get is dependent on the specific type of animal."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "d = Dog()\n",
+ "l = Labrador()\n",
+ "c = Cat()\n",
+ "ch = Chihuahua()\n",
+ "\n",
+ "print('Noise made by dogs: {}'.format(d .noiseMade()))\n",
+ "print('Noise made by labradors: {}'.format(l .noiseMade()))\n",
+ "print('Noise made by cats: {}'.format(c .noiseMade()))\n",
+ "print('Noise made by chihuahuas: {}'.format(ch.noiseMade()))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Code re-use and problem decomposition\n",
+ "\n",
+ "\n",
+ "Inheritance allows us to split a problem into smaller problems, and to re-use\n",
+ "code. Let's demonstrate this with a more involved example. Imagine that a\n",
+ "former colleague had written a class called `Operator`:\n",
+ "\n",
+ "\n",
+ "> I know this is a little abstract (and quite contrived), but bear with me\n",
+ "> here."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Operator(object):\n",
+ "\n",
+ " def __init__(self):\n",
+ " self.__operations = []\n",
+ " self.__opFuncs = {}\n",
+ "\n",
+ " @property\n",
+ " def operations(self):\n",
+ " return list(self.__operations)\n",
+ "\n",
+ " @property\n",
+ " def functions(self):\n",
+ " return dict(self.__opFuncs)\n",
+ "\n",
+ " def addFunction(self, name, func):\n",
+ " self.__opFuncs[name] = func\n",
+ "\n",
+ " def do(self, name, *values):\n",
+ " self.__operations.append((name, values))\n",
+ "\n",
+ " def preprocess(self, value):\n",
+ " return value\n",
+ "\n",
+ " def run(self, input):\n",
+ " data = self.preprocess(input)\n",
+ " for oper, vals in self.__operations:\n",
+ " func = self.__opFuncs[oper]\n",
+ " vals = [self.preprocess(v) for v in vals]\n",
+ " data = func(data, *vals)\n",
+ " return data"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "This `Operator` class provides an interface and logic to execute a chain of\n",
+ "operations - an operation is some function which accepts one or more inputs,\n",
+ "and produce one output.\n",
+ "\n",
+ "\n",
+ "But it stops short of defining any operations. Instead, we can create another\n",
+ "class - a sub-class - which derives from the `Operator` class. This sub-class\n",
+ "will define the operations that will ultimately be executed by the `Operator`\n",
+ "class. All that the `Operator` class does is:\n",
+ "\n",
+ "- Allow functions to be registered with the `addFunction` method - all\n",
+ " registered functions can be used via the `do` method.\n",
+ "\n",
+ "- Stage an operation (using a registered function) via the `do` method. Note\n",
+ " that `do` allows any number of values to be passed to it, as we used the `*`\n",
+ " operator when specifying the `values` argument.\n",
+ "\n",
+ "- Run all staged operations via the `run` method - it passes an input through\n",
+ " all of the operations that have been staged, and then returns the final\n",
+ " result.\n",
+ "\n",
+ "\n",
+ "Let's define a sub-class:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class NumberOperator(Operator):\n",
+ "\n",
+ " def __init__(self):\n",
+ " super().__init__()\n",
+ " self.addFunction('add', self.add)\n",
+ " self.addFunction('mul', self.mul)\n",
+ " self.addFunction('negate', self.negate)\n",
+ "\n",
+ " def preprocess(self, value):\n",
+ " return float(value)\n",
+ "\n",
+ " def add(self, a, b):\n",
+ " return a + b\n",
+ "\n",
+ " def mul(self, a, b):\n",
+ " return a * b\n",
+ "\n",
+ " def negate(self, a):\n",
+ " return -a"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The `NumberOperator` is a sub-class of `Operator`, which we can use for basic\n",
+ "numerical calculations. It provides a handful of simple numerical methods, but\n",
+ "the most interesting stuff is inside `__init__`:\n",
+ "\n",
+ "\n",
+ "> ```\n",
+ "> super().__init__()\n",
+ "> ```\n",
+ "\n",
+ "\n",
+ "This line invokes `Operator.__init__` - the initialisation method for the\n",
+ "`Operator` base-class. In Python, we can use the [built-in `super`\n",
+ "method](https://docs.python.org/3.5/library/functions.html#super) to take care\n",
+ "of correctly calling methods that are defined in an object's base-class (or\n",
+ "classes, in the case of [multiple inheritance](todo)).\n",
+ "\n",
+ "\n",
+ "> ```\n",
+ "> self.addFunction('add', self.add)\n",
+ "> self.addFunction('mul', self.mul)\n",
+ "> self.addFunction('negate', self.negate)\n",
+ "> ```\n",
+ "\n",
+ "\n",
+ "Here we are registering all of the functionality that is provided by the\n",
+ "`NumberOperator` class, via the `Opoerator.addFunction` method.\n",
+ "\n",
+ "\n",
+ "The `NumberOperator` class has also overridden the `preprocess` method, to\n",
+ "ensure that all values handled by the `Operator` are numbers. This method gets\n",
+ "called within the `run` method - for a `NumberOperator` instance, the\n",
+ "`NumberOperator.preprocess` method will get called<sup>1</sup>.\n",
+ "\n",
+ "> <sup>1</sup> We can still [access overridden base-class methods](todo link)\n",
+ "> via the `super()` function, or by explicitly calling the base-class\n",
+ "> implementation.\n",
+ "\n",
+ "\n",
+ "\n",
+ "Now let's see what our `NumberOperator` class does:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "no = NumberOperator()\n",
+ "no.do('add', 10)\n",
+ "no.do('mul', 2)\n",
+ "no.do('negate')\n",
+ "\n",
+ "print('Operations on {}: {}'.format(10, no.run(10)))\n",
+ "print('Operations on {}: {}'.format(2.5, no.run(5)))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "It works! While this is a contrived example, hopefully you can see how\n",
+ "inheritance can be used to break a problem down into sub-problems:\n",
+ "\n",
+ "- The `Operator` class provides all of the logic needed to manage and execute\n",
+ " operations, without caring about what those operations are actually doing.\n",
+ "\n",
+ "- This leaves the `NumberOperator` class free to concentrate on implementing\n",
+ " the functions that are specific to its task, and not having to worry about\n",
+ " how they are executed.\n",
+ "\n",
+ "\n",
+ "We could also easily implement other `Operator` sub-classes to work on\n",
+ "different data types, such as arrays, images, or even non-numeric data such as\n",
+ "strings:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class StringOperator(Operator):\n",
+ " def __init__(self):\n",
+ " super().__init__()\n",
+ " self.addFunction('capitalise', self.capitalise)\n",
+ " self.addFunction('concat', self.concat)\n",
+ "\n",
+ " def preprocess(self, value):\n",
+ " return str(value)\n",
+ "\n",
+ " def capitalise(self, s):\n",
+ " return ' '.join([w[0].upper() + w[1:] for w in s.split()])\n",
+ "\n",
+ " def concat(self, s1, s2):\n",
+ " return s1 + s2\n",
+ "\n",
+ "so = StringOperator()\n",
+ "so.do('capitalise')\n",
+ "so.do('concat', '!')\n",
+ "\n",
+ "print(so.run('python is an ok language'))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Polymorphism\n",
+ "\n",
+ "\n",
+ "Inheritance also allows us to take advantage of _polymorphism_, which refers\n",
+ "to idea that, in an object-oriented language, we should be able to use an\n",
+ "object without having complete knowledge about the class, or type, of that\n",
+ "object. For example, we should be able to write a function which expects an\n",
+ "`Operator` instance, but which should work on an instance of any `Operator`\n",
+ "sub-classs. For example, we can write a function which prints a summary\n",
+ "of an `Operator` instance:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "def operatorSummary(o):\n",
+ " print(type(o).__name__)\n",
+ " print(' All functions: ')\n",
+ " for fname in o.functions.keys():\n",
+ " print(' {}'.format(fname))\n",
+ " print(' Staged operations: ')\n",
+ " for i, (fname, vals) in enumerate(o.operations):\n",
+ " vals = ', '.join([str(v) for v in vals])\n",
+ " print(' {}: {}({})'.format(i + 1, fname, vals))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Because the `operatorSummary` function only uses methods that are defined\n",
+ "in the `Operator` base-class, we can use it on _any_ `Operator` instance,\n",
+ "regardless of its type:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "operatorSummary(no)\n",
+ "operatorSummary(so)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### Multiple inheritance\n",
+ "\n",
+ "\n",
+ "Mention the MRO\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
+ "\n",
"## Class attributes and methods\n",
"\n",
"\n",
@@ -892,7 +1254,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "Calling a class method is the same as accessing a class attribute:"
+ "alling a class method is the same as accessing a class attribute:"
]
},
{
@@ -942,9 +1304,6 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "## Inheritance\n",
- "\n",
- "\n",
"## Appendix: The `object` base-class\n",
"\n",
"\n",
@@ -1022,7 +1381,71 @@
"party library which has bugs in it. No problem - while you are waiting for the\n",
"library author to release a new version of the library, you can write your own\n",
"working implementation and [monkey-patch it\n",
- "in](https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes/blob/0.21.0/fsleyes/views/viewpanel.py#L726)!"
+ "in](https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes/blob/0.21.0/fsleyes/views/viewpanel.py#L726)!\n",
+ "\n",
+ "\n",
+ "## Appendix: Method overloading\n",
+ "\n",
+ "\n",
+ "Method overloading (defining multiple methods on a class, each accepting\n",
+ "different arguments) is one of the only object-oriented features that is not\n",
+ "present in Python. Becuase Python does not perform any runtime checks on the\n",
+ "types of arguments that are passed to a method, or the compatibility of the\n",
+ "method to accept the arguments, it would not be possible to determine which\n",
+ "implementation of a method is to be called.\n",
+ "\n",
+ "\n",
+ "However, because a Python method can be written to accept any number or type\n",
+ "of arguments, it is very easy to to build your own overloading logic by\n",
+ "writing a \"dispatch\" method. Here is YACE (Yet Another Contrived Example):"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class Adder(object):\n",
+ "\n",
+ " def add(self, *args):\n",
+ " if len(args) == 2: return self.__add2(*args)\n",
+ " elif len(args) == 3: return self.__add3(*args)\n",
+ " elif len(args) == 4: return self.__add4(*args)\n",
+ "\n",
+ " def __add2(self, a, b):\n",
+ " return a + b\n",
+ "\n",
+ " def __add3(self, a, b, c):\n",
+ " return a + b + c\n",
+ "\n",
+ " def __add4(self, a, b, c, d):\n",
+ " return a + b + c + d\n",
+ "\n",
+ "a = Adder()\n",
+ "\n",
+ "print('Add two: {}'.format(a.add(1, 2)))\n",
+ "print('Add three: {}'.format(a.add(1, 2, 3)))\n",
+ "print('Add four: {}'.format(a.add(1, 2, 3, 4)))"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## Useful references\n",
+ "\n",
+ "\n",
+ "https://docs.python.org/3.5/library/unittest.mock.html\n",
+ "https://docs.python.org/3.5/tutorial/classes.html\n",
+ "https://docs.python.org/3.5/library/functions.html\n",
+ "https://docs.python.org/2/reference/datamodel.html\n",
+ "https://www.reddit.com/r/learnpython/comments/2s3pms/what_is_the_difference_between_init_and_new/cnm186z/\n",
+ "https://docs.python.org/3.5/reference/datamodel.html\n",
+ "http://www.jesshamrick.com/2011/05/18/an-introduction-to-classes-and-inheritance-in-python/\n",
+ "https://www.digitalocean.com/community/tutorials/understanding-class-inheritance-in-python-3\n",
+ "\n",
+ "https://docs.python.org/3.5/library/functions.html#super"
]
}
],
diff --git a/advanced_topics/object_oriented_programming.md b/advanced_topics/object_oriented_programming.md
index 3ca3e43ee270d55f1a1ca3d2cf514195a041209f..adf8e16850e85f5d051b68d70f1e526a658d62ab 100644
--- a/advanced_topics/object_oriented_programming.md
+++ b/advanced_topics/object_oriented_programming.md
@@ -1,4 +1,4 @@
-# Object-oriented programming
+# Object-oriented programming in Python
By now you might have realised that __everything__ in Python is an
@@ -57,7 +57,7 @@ instantiation of a struct:
> ```
-The fundamental difference between a `struct` in C, and a `class` in Python
+One of the major differences between a `struct` in C, and a `class` in Python
and other object oriented languages, is that you can't (easily) add functions
to a `struct` - it is just a chunk of memory. Whereas in Python, you can add
functions to your class definition, which will then be added as methods when
@@ -65,10 +65,11 @@ you create an object from that class.
Of course there are many more differences between C structs and classes (most
-notably [inheritance](todo), and [protection](todo)). But if you can
-understand the difference between a _definition_ of a C struct, and an
-_instantiation_ of that struct, then you are most of the way towards
-understanding the difference between a Python _class_, and a Python _object_.
+notably [inheritance](todo), [polymorphism](todo), and [access
+protection](todo)). But if you can understand the difference between a
+_definition_ of a C struct, and an _instantiation_ of that struct, then you
+are most of the way towards understanding the difference between a _class_,
+and an _object_.
> But just to confuse you, remember that in Python, __everything__ is an
@@ -124,9 +125,10 @@ class FSLMaths(object):
Here we have added a _method_ called `__init__` to our class (remember that a
-_method_ is just a function which is associated with a specific object). This
-method expects two arguments - `self`, and `inimg`. So now, when we create an
-instance of the `FSLMaths` class, we will need to provide an input image:
+_method_ is just a function which is defined in a cliass, and which can be
+called on instances of that class). This method expects two arguments -
+`self`, and `inimg`. So now, when we create an instance of the `FSLMaths`
+class, we will need to provide an input image:
```
@@ -316,19 +318,13 @@ class FSLMaths(object):
for oper, value in self.operations:
- # If value is a string, we assume
- # that it is a path to an image.
- if isinstance(value, str):
- image = nib.load(value)
- value = image.get_data()
-
- # Or it could be an image that
+ # Values could be an image that
# has already been loaded.
elif isinstance(value, nib.nifti1.Nifti1Image):
- value = image.get_data()
+ value = value.get_data()
# Otherwise we assume that
- # it is a scalar value.
+ # values are scalars.
if oper == 'add':
data = data + value
@@ -354,10 +350,12 @@ We now have a useable (but not very useful) `FSLMaths` class!
```
input = op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm.nii.gz')
-inimg = nib.load(input)
-fm = FSLMaths(inimg)
+mask = op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm_brain_mask.nii.gz')
+input = nib.load(input)
+mask = nib.load(mask)
+fm = FSLMaths(input)
-fm.mul(op.expandvars('$FSLDIR/data/standard/MNI152_T1_2mm_brain_mask.nii.gz'))
+fm.mul(mask)
fm.add(-10)
outimg = fm.run()
@@ -393,7 +391,7 @@ fm.run()
Well, the scary answer is ... there is __nothing__ stopping you from doing
whatever you want to a Python object. You can add, remove, and modify
-attribute at will. You can even replace the methods of an existing object if
+attributes at will. You can even replace the methods of an existing object if
you like:
@@ -419,7 +417,7 @@ this - take a look at the appendix for a [brief discussion on this topic](todo).
Python tends to assume that programmers are "responsible adults", and hence
doesn't do much in the way of restricting access to the attributes or methods
of an object. This is in contrast to languages like C++ and Java, where the
-notion of a private attribute or method is enforced by the language.
+notion of a private attribute or method is strictly enforced by the language.
However, there are a couple of conventions in Python that are [universally
@@ -534,9 +532,9 @@ class FSLMaths(object):
```
-Property setters are a nice way to restrict the values that a property may
-take - note that we perform a sanity check in the `input` setter, to make
-sure that the new input is a NIFTI image:
+Property setters are a nice way to add validation logic when an attribute is
+assigned a value. We are doing this in the above example, by making sure that
+the new input is a NIFTI image:
```
@@ -562,6 +560,306 @@ fm.input = 'abcde'
> validate the initial `inimg` that was passed in during creation.
+## Inheritance
+
+
+One of the major advantages of an object-oriented programming approach is
+_inheritance_ - the ability to define hierarchical relationships between
+classes and instances.
+
+
+### The basics
+
+
+For example, a veterinary surgery might be running some Python code which
+looks like the following. Perhaps it is used to assist the nurses in
+identifying an animal when it arrives at the surgery:
+
+
+```
+class Animal(object):
+ def noiseMade(self):
+ raise NotImplementedError('This method is implemented by sub-classes')
+
+class Dog(Animal):
+ def noiseMade(self):
+ return 'Woof'
+
+class Cat(Animal):
+ def noiseMade(self):
+ return 'Meow'
+
+class Labrador(Dog):
+ pass
+
+class Chihuahua(Dog):
+ def noiseMade(self):
+ return 'Yap yap yap'
+```
+
+
+Hopefully this example doesn't need much in the way of explanation - this
+collection of classes captures a hierarchical relationship which exists in the
+real world (and also captures the inherently annoying nature of
+chihuahuas). For example, in the real world, all dogs are animals, but not all
+animals are dogs. Therefore in our model, the `Dog` class has specified
+`Animal` as its base class. We say that the `Dog` class _extends_, _derives
+from_, or _inherits from_, the `Animal` class, and that all `Dog` instances
+are also `Animal` instances (but not vice-versa).
+
+
+What does that `noiseMade` method do? There is a `noiseMade` method defined
+on the `Animal` class, but it has been re-implemented, or _overridden_ in the
+`Dog`, `Cat`, and `Chihuahua` classes (but not on the `Labrador` class). We
+can call the `noiseMade` method on any `Animal` instance, but the specific
+behaviour that we get is dependent on the specific type of animal.
+
+
+```
+d = Dog()
+l = Labrador()
+c = Cat()
+ch = Chihuahua()
+
+print('Noise made by dogs: {}'.format(d .noiseMade()))
+print('Noise made by labradors: {}'.format(l .noiseMade()))
+print('Noise made by cats: {}'.format(c .noiseMade()))
+print('Noise made by chihuahuas: {}'.format(ch.noiseMade()))
+```
+
+
+### Code re-use and problem decomposition
+
+
+Inheritance allows us to split a problem into smaller problems, and to re-use
+code. Let's demonstrate this with a more involved example. Imagine that a
+former colleague had written a class called `Operator`:
+
+
+> I know this is a little abstract (and quite contrived), but bear with me
+> here.
+
+
+```
+class Operator(object):
+
+ def __init__(self):
+ self.__operations = []
+ self.__opFuncs = {}
+
+ @property
+ def operations(self):
+ return list(self.__operations)
+
+ @property
+ def functions(self):
+ return dict(self.__opFuncs)
+
+ def addFunction(self, name, func):
+ self.__opFuncs[name] = func
+
+ def do(self, name, *values):
+ self.__operations.append((name, values))
+
+ def preprocess(self, value):
+ return value
+
+ def run(self, input):
+ data = self.preprocess(input)
+ for oper, vals in self.__operations:
+ func = self.__opFuncs[oper]
+ vals = [self.preprocess(v) for v in vals]
+ data = func(data, *vals)
+ return data
+```
+
+
+This `Operator` class provides an interface and logic to execute a chain of
+operations - an operation is some function which accepts one or more inputs,
+and produce one output.
+
+
+But it stops short of defining any operations. Instead, we can create another
+class - a sub-class - which derives from the `Operator` class. This sub-class
+will define the operations that will ultimately be executed by the `Operator`
+class. All that the `Operator` class does is:
+
+- Allow functions to be registered with the `addFunction` method - all
+ registered functions can be used via the `do` method.
+
+- Stage an operation (using a registered function) via the `do` method. Note
+ that `do` allows any number of values to be passed to it, as we used the `*`
+ operator when specifying the `values` argument.
+
+- Run all staged operations via the `run` method - it passes an input through
+ all of the operations that have been staged, and then returns the final
+ result.
+
+
+Let's define a sub-class:
+
+
+```
+class NumberOperator(Operator):
+
+ def __init__(self):
+ super().__init__()
+ self.addFunction('add', self.add)
+ self.addFunction('mul', self.mul)
+ self.addFunction('negate', self.negate)
+
+ def preprocess(self, value):
+ return float(value)
+
+ def add(self, a, b):
+ return a + b
+
+ def mul(self, a, b):
+ return a * b
+
+ def negate(self, a):
+ return -a
+```
+
+
+The `NumberOperator` is a sub-class of `Operator`, which we can use for basic
+numerical calculations. It provides a handful of simple numerical methods, but
+the most interesting stuff is inside `__init__`:
+
+
+> ```
+> super().__init__()
+> ```
+
+
+This line invokes `Operator.__init__` - the initialisation method for the
+`Operator` base-class. In Python, we can use the [built-in `super`
+method](https://docs.python.org/3.5/library/functions.html#super) to take care
+of correctly calling methods that are defined in an object's base-class (or
+classes, in the case of [multiple inheritance](todo)).
+
+
+> ```
+> self.addFunction('add', self.add)
+> self.addFunction('mul', self.mul)
+> self.addFunction('negate', self.negate)
+> ```
+
+
+Here we are registering all of the functionality that is provided by the
+`NumberOperator` class, via the `Opoerator.addFunction` method.
+
+
+The `NumberOperator` class has also overridden the `preprocess` method, to
+ensure that all values handled by the `Operator` are numbers. This method gets
+called within the `run` method - for a `NumberOperator` instance, the
+`NumberOperator.preprocess` method will get called<sup>1</sup>.
+
+> <sup>1</sup> We can still [access overridden base-class methods](todo link)
+> via the `super()` function, or by explicitly calling the base-class
+> implementation.
+
+
+
+Now let's see what our `NumberOperator` class does:
+
+
+```
+no = NumberOperator()
+no.do('add', 10)
+no.do('mul', 2)
+no.do('negate')
+
+print('Operations on {}: {}'.format(10, no.run(10)))
+print('Operations on {}: {}'.format(2.5, no.run(5)))
+```
+
+
+It works! While this is a contrived example, hopefully you can see how
+inheritance can be used to break a problem down into sub-problems:
+
+- The `Operator` class provides all of the logic needed to manage and execute
+ operations, without caring about what those operations are actually doing.
+
+- This leaves the `NumberOperator` class free to concentrate on implementing
+ the functions that are specific to its task, and not having to worry about
+ how they are executed.
+
+
+We could also easily implement other `Operator` sub-classes to work on
+different data types, such as arrays, images, or even non-numeric data such as
+strings:
+
+
+```
+class StringOperator(Operator):
+ def __init__(self):
+ super().__init__()
+ self.addFunction('capitalise', self.capitalise)
+ self.addFunction('concat', self.concat)
+
+ def preprocess(self, value):
+ return str(value)
+
+ def capitalise(self, s):
+ return ' '.join([w[0].upper() + w[1:] for w in s.split()])
+
+ def concat(self, s1, s2):
+ return s1 + s2
+
+so = StringOperator()
+so.do('capitalise')
+so.do('concat', '!')
+
+print(so.run('python is an ok language'))
+```
+
+
+### Polymorphism
+
+
+Inheritance also allows us to take advantage of _polymorphism_, which refers
+to idea that, in an object-oriented language, we should be able to use an
+object without having complete knowledge about the class, or type, of that
+object. For example, we should be able to write a function which expects an
+`Operator` instance, but which should work on an instance of any `Operator`
+sub-classs. For example, we can write a function which prints a summary
+of an `Operator` instance:
+
+
+```
+def operatorSummary(o):
+ print(type(o).__name__)
+ print(' All functions: ')
+ for fname in o.functions.keys():
+ print(' {}'.format(fname))
+ print(' Staged operations: ')
+ for i, (fname, vals) in enumerate(o.operations):
+ vals = ', '.join([str(v) for v in vals])
+ print(' {}: {}({})'.format(i + 1, fname, vals))
+```
+
+
+Because the `operatorSummary` function only uses methods that are defined
+in the `Operator` base-class, we can use it on _any_ `Operator` instance,
+regardless of its type:
+
+
+```
+operatorSummary(no)
+operatorSummary(so)
+```
+
+
+### Multiple inheritance
+
+
+Mention the MRO
+
+
+
+
+
## Class attributes and methods
@@ -708,7 +1006,7 @@ class FSLMaths(object):
```
-Calling a class method is the same as accessing a class attribute:
+alling a class method is the same as accessing a class attribute:
```
@@ -741,9 +1039,6 @@ print(fm1.usage())
```
-## Inheritance
-
-
## Appendix: The `object` base-class
@@ -822,3 +1117,58 @@ party library which has bugs in it. No problem - while you are waiting for the
library author to release a new version of the library, you can write your own
working implementation and [monkey-patch it
in](https://git.fmrib.ox.ac.uk/fsl/fsleyes/fsleyes/blob/0.21.0/fsleyes/views/viewpanel.py#L726)!
+
+
+## Appendix: Method overloading
+
+
+Method overloading (defining multiple methods on a class, each accepting
+different arguments) is one of the only object-oriented features that is not
+present in Python. Becuase Python does not perform any runtime checks on the
+types of arguments that are passed to a method, or the compatibility of the
+method to accept the arguments, it would not be possible to determine which
+implementation of a method is to be called.
+
+
+However, because a Python method can be written to accept any number or type
+of arguments, it is very easy to to build your own overloading logic by
+writing a "dispatch" method. Here is YACE (Yet Another Contrived Example):
+
+
+```
+class Adder(object):
+
+ def add(self, *args):
+ if len(args) == 2: return self.__add2(*args)
+ elif len(args) == 3: return self.__add3(*args)
+ elif len(args) == 4: return self.__add4(*args)
+
+ def __add2(self, a, b):
+ return a + b
+
+ def __add3(self, a, b, c):
+ return a + b + c
+
+ def __add4(self, a, b, c, d):
+ return a + b + c + d
+
+a = Adder()
+
+print('Add two: {}'.format(a.add(1, 2)))
+print('Add three: {}'.format(a.add(1, 2, 3)))
+print('Add four: {}'.format(a.add(1, 2, 3, 4)))
+```
+
+## Useful references
+
+
+https://docs.python.org/3.5/library/unittest.mock.html
+https://docs.python.org/3.5/tutorial/classes.html
+https://docs.python.org/3.5/library/functions.html
+https://docs.python.org/2/reference/datamodel.html
+https://www.reddit.com/r/learnpython/comments/2s3pms/what_is_the_difference_between_init_and_new/cnm186z/
+https://docs.python.org/3.5/reference/datamodel.html
+http://www.jesshamrick.com/2011/05/18/an-introduction-to-classes-and-inheritance-in-python/
+https://www.digitalocean.com/community/tutorials/understanding-class-inheritance-in-python-3
+
+https://docs.python.org/3.5/library/functions.html#super
\ No newline at end of file