Blog post on UML and the Strategy Design Pattern #52

HarmonicReflux · 2024-08-28T01:45:06Z

My RSE blog post makes a contribution towards explaining UML and the Strategy Design Pattern followed by a practical example from option pricing.

In particular, we:

Introduce UML and its role in software architecture
Detail the Strategy Pattern and its components (Context, Strategy Interface, Concrete Strategy)
Include a practical example of pricing European options using the Black-Scholes-Merton equation
Integrate relevant mathematical expressions and explanations

Closes #13, #22.

…Strategy Design Pattern followed by a practical example from option pricing. In particular, we: - Introduce UML and its role in software architecture - Detail the Strategy Pattern and its components (Context, Strategy Interface, ConcreteStrategy) - Include a practical example of pricing European options using the Black-Scholes-Merton equation - Integrate relevant mathematical expressions and explanations

for more information, see https://pre-commit.ci

- Fix trailing whitespace issues

dalonsoa

I've given a first pass to the post. It looks very good, but it will require several revisions until it is polished enough for publication.

I've left a few comments below but the main points are:

You need to add some links between sections to facilitate the reader to move naturally form one to another. As it is now, you seem to jump from one topic to another with no clear reason.
I'm a bit unsure about including equations. They are not complicated and I think it is nice to make it clear what you are solving, but they can be very obscure to someone not in the financial world. Maybe, to facilitate people going through them, explain what they are about, what they are useful for, etc. European Call and European Put don't say much.
Your premise for using UML diagram is to get to a code that is not overengineer but your code is very overengineer. You are using classes where you only need simple functions, which is one of the main criticisms of OOB: not everything needs to be a class! I've suggested a change that will improve that part, but obviously the UML diagrams will need updating accordingly. Probably things can be simplified further, but let's leave it here and see what others have to say.

docs/posts/design_patterns.md

dalonsoa · 2024-08-28T09:18:45Z

docs/posts/design_patterns.md

+Over-engineering at the prototyping or proof-of-concept stage can be counterproductive. However, as systems mature, this approach can lead to technical debt,
+resulting in code that is difficult, if not impossible, to maintain.
+
+In the following, we first describe UML diagrams and how they are used to plan and visualise software architecture before coding itself.


This paragraph here comes a bit out of the blue after the nice introduction above. I would suggest something along the lines of:

In this blog post we will... (some indication of the overall purpose of the post, linking the above introduction to what is coming next). We first start describing UML diagrams...

Agree. Describing how this blog post will address the issues identified in the good introduction above would make the contents and goal of the post more clear. Even if it's obvious to you, it's a reassurance for the reader that they are not just being clickbaited.

It is the least of my intention to deliver click-bait. I have a few concepts to explain here:

The design patterns and its purpose

How it can be applied to a concrete example (here: option pricing from finance which essentially is pricing an insurance contract given uncertainty of future evolution of an underlying asset (and hence it is called a "derivative"))

Incidentally, this forces me to also explain the concept of said derivatives as otherwise it pops out of nowhere for readers unfamiliar with the topic.

Hence, it is not that easy to cater for all interests in the introduction.

I expanded the introduction providing an overview of what the blog post explains. Hopefully, this provides a better overview and makes things clearer.

docs/posts/design_patterns.md

jamesturner246

Nice to see info on UML and API design 👍

I've added a few points and suggestions. One other thing I note is the title: I feel this content is just as applicable to software developers in other computational fields. Maybe emphasise in the title that the content is more about API design using UML, and (with less emphasis) using a computational finance problem as an example.

docs/posts/design_patterns.md

jamesturner246 · 2024-08-30T12:16:06Z

docs/posts/design_patterns.md

+Over-engineering at the prototyping or proof-of-concept stage can be counterproductive. However, as systems mature, this approach can lead to technical debt,
+resulting in code that is difficult, if not impossible, to maintain.
+
+In the following, we first describe UML diagrams and how they are used to plan and visualise software architecture before coding itself.


Agree. Describing how this blog post will address the issues identified in the good introduction above would make the contents and goal of the post more clear. Even if it's obvious to you, it's a reassurance for the reader that they are not just being clickbaited.

docs/posts/design_patterns.md

jamesturner246 · 2024-08-30T12:37:59Z

docs/posts/design_patterns.md

+*The rendered result should look similar to the above figure.*
+
+We can now use this our blueprint and engineer software that implements the abstract pattern.
+As an example we pick pricing a European call and put option using the `Black-Scholes-Merton` equation, which is


I'd hazard a guess that 80% of the audience doesn't know what, or the significance of, any of these things. You may need to spoon feed people a bit here. Briefly why use/what is a European call, the Black-Scholes-Merton equation. Some people might not even know what a PDE is.

I did address this point in my latest commit.

docs/posts/design_patterns.md

HarmonicReflux · 2024-09-02T01:20:51Z

Hello team,

thanks for the feedback.

I certainly can expand on the background and elaborate more on the the mathematical framework.

I am aware on can borrow the ideas from "Design Patterns" and code them in a functional approach rather than an OOP one. I am not sure whether there is a silver bullet here. The main issue of the OOP approach is, that all variables feeding into the equation can be functions of multiple parameters, particularly, the can be time-dependent. I thought an OOP approach might make it easier to inherit from base classes for such an expansion, but of course, this would necessitate multiple inheritance making things nested.

I am on RSECon this week, so will not be able to contribute this week.

dalonsoa · 2024-09-16T14:46:13Z

I am aware on can borrow the ideas from "Design Patterns" and code them in a functional approach rather than an OOP one. I am not sure whether there is a silver bullet here. The main issue of the OOP approach is, that all variables feeding into the equation can be functions of multiple parameters, particularly, the can be time-dependent. I thought an OOP approach might make it easier to inherit from base classes for such an expansion, but of course, this would necessitate multiple inheritance making things nested.

I totally understand why you are using OOP, but in the example you use, it just results in the opposite idea you are trying to communicate, how to not over engineer your code. There might be other cases where that is the right approach, but I don't think that is the answer in this one. There's no benefit on using classes in this case.

I'd suggest you either come up with an example where using classes is indeed the best approach (eg. if there's a state that needs to be pre-calculated or setup, and then used when needed) or modify your code the way I suggested and re-write the text to match the example.

On the background, I think that's a must. Otherwise, only people with some background in finance will understand what's going on.

Maybe have a crack at Jame's and my comments and then ask the rest of the reviewers to have a look to the revised version, so we can iteratively improve the blog post.

that is priced in this tutorial.

HarmonicReflux · 2024-10-21T01:16:11Z

I did work on improving the description of the background as to not loose readers unfamiliar with the terms straight away.

Regarding OOP vs. functional. I do not have to keep track of the state of the object, but rather to compute a parameter based on inputs (the inputs are mapped to an output via an algebraic manipulation). So indeed the functional approach is the more direct approach here.

restructured introduction that aims at being more explanatory and clearer on what the blog post deals with. This sets and simultaneously limits expectations and provides the reader with a clear overview.

for more information, see https://pre-commit.ci

dalonsoa

The finance related background and the link between the introduction and the UML diagrams is now much better - and indeed pretty interesting!

However, all the UML diagrams still use the class-based approach which, I think we agreed, is not the right call. Maybe you're already on it, but just a reminder.

docs/posts/design_patterns.md

AdrianDAlessandro

I tried running this locally and got:

ERROR   -  Config value 'plugins': The "plantuml_markdown" plugin is not installed

You will need to add this package to the dependencies (with poetry add) and make sure it works

HarmonicReflux · 2024-10-25T04:05:08Z

The finance related background and the link between the introduction and the UML diagrams is now much better - and indeed pretty interesting!

However, all the UML diagrams still use the class-based approach which, I think we agreed, is not the right call. Maybe you're already on it, but just a reminder.

Indeed, I am working on the UML diagrams.

HarmonicReflux · 2024-10-25T04:09:26Z

I tried running this locally and got:
ERROR   -  Config value 'plugins': The "plantuml_markdown" plugin is not installed
You will need to add this package to the dependencies (with poetry add) and make sure it works

This is a tricky bit: I had a discussion a while back ago with @alexdewar
and we could not find a way to integrate plantuml with poetry.

I create the diagrams in a Jupyter notebook like so:

This, unfortunately, is not supported using our RSEBlog repository.

dalonsoa · 2024-10-25T07:21:17Z

I suggest you switch to using Mermaid, which has full support for class diagrams (maybe not full featured UML ones, although I'm not sure of the difference) and do work with MkDocs. As it is not an extra dependency, but some sort of markdown extension, there should be no issues with poetry. It is even rendered in GitHub directly.

We have use it in QwikApp:

Here the config in mkdocs.yml
Here an example of usage within the same docs

HarmonicReflux · 2024-10-25T07:52:13Z

Morning @dalonsoa,

I struggle making my .md file pass markdownlint.
for example the first error indicated in the screenshot below is related to an invalid link.

[Design Patterns: Elements of Reusable Object-Oriented Software](https://www.amazon.com/Design-Patterns-Elements-Reusable-Object-Oriented/dp/0201633612)

throws the indicated error, while a test link, say,
[SocRSE Youtube channel](https://www.youtube.com/channel/UCL7rYOIAP1Rx_VajLPDF-hA)

works just fine. Not sure what the issue is caused by. I tried to run
pre-commit run all-files but the falg all-files appears not to be defined as per the error message No hook with id all-filesin stagepre-commit``. Do you have an idea why my link is flagged invalid?

HarmonicReflux · 2024-10-25T07:55:36Z

I suggest you switch to using Mermaid, which has full support for class diagrams (maybe not full featured UML ones, although I'm not sure of the difference) and do work with MkDocs. As it is not an extra dependency, but some sort of markdown extension, there should be no issues with poetry. It is even rendered in GitHub directly.

We have use it in QwikApp:

Here the config in mkdocs.yml

Here an example of usage within the same docs

I have heard of Mermaid. Let me please first make my .md file pass the pre-commit hooks, so people can provide feedback on the text itself before taking a look at yet another tool.

dalonsoa · 2024-10-25T07:59:10Z

Some webpages just don't let CI systems to check them easily. The simplest solution is jut to skip checking that link. Check this:

RSEBlog/docs/posts/20240722_pydata_london_2024.md

Lines 31 to 33 in 43789a7

    
           <!-- markdown-link-check-disable --> 
        
           Cheuk Ting Ho led an interesting unconference style discussion on “How to define open source AI”. The participants of the unconference were asked to walk through the open source initiative’s conversation [explaining the concept of data information](https://discuss.opensource.org/t/explaining-the-concept-of-data-information/401) and they were asked to put their opinions and questions on it. It was a healthy discussion on Data Information as defined in the draft [Open Source AI](https://opensource.org/blog/open-source-ai-definition-weekly-update-june-17) definition: “Sufficiently detailed information about the data used to train the system, so that a skilled person can recreate a substantially equivalent system using the same or similar data.” 
        
           <!-- markdown-link-check-enable -->

dalonsoa · 2024-10-25T08:02:28Z

About the other error, you have the label and the link split in different lines. They render the same, but they are not the same thing and markdownlint will pick it:

Do not split lines 17 and 18, even if it results in a long line.

…ged UML diagrams and Oython code accordingly. - Expanded the overall text. - Included a section on the put-call parity to test the fair pricing - Increased the number of references

`.spellcheck.yml`

docs/posts/design_patterns.md

.wordlist.txt

alexdewar · 2024-10-25T11:52:59Z

.wordlist.txt

+plantuml
+startuml
+enduml
+labeled


This is "labelled" in UK English. So I'd fix the text rather than ignoring the word.

.wordlist.txt

alexdewar · 2024-10-25T11:55:45Z

.wordlist.txt

+Modeling
+Rumbaugh
+nd
+se


Can we set the spellchecker to ignore two-letter words or something? Does anyone know? Having all these tiny non-words in the dictionary seems really ugly 😬

I am are of this. .wordlist.txt has not been a beauty before my post and it will be ever lesser so after.
I am happy for suggestions of other team members to modify spellchecker to resolve this.

I cannot trigger spellchecker locally to verify it runs error-free, and it got somewhat of a pain to make local changes to the .spellcheck.yml file and pushing them to the repo to trigger the CI pipeline only to experience it fails after 8 to 12 seconds and repeating the loop.

In princliple one should be able to run spellchecker locally like so

pip install pyspelling pyspelling -c .spellcheck.yml

Also, in an experiment, I appended the following

ignore_patterns: - '```[a-zA-Z]+\n[\s\S]*?\n```' # Ignore code blocks - '## References\n(?:- .*\n)*' # Ignore References section

to
.spellcheck.yml`
in order to test whether fenced code-blocks are protected from spellchecker doing its work on them, but to no avail. If someone wants to take a look at that, I think, it should be a separate issue.

Also, I managed to protect the References section from spellchecker using

References go here

which works well.

alexdewar · 2024-10-25T11:56:33Z

docs/posts/design_patterns.md

+
+## References
+
+<!-- spell-check-ignore -->


If this works, then we can remove "Modeling" from .wordlist.txt, right?

Yes, that should work. As with C++, I now have code that "compiles", and I now can work on make it more beautiful. But honestly, spellchecker has been a pain and to make it "behave" has been tricky.

As for the Latin phrase "per se", there is not much I can do about it. I do not use them that regularly, although they come across in economic language quite regularly, e.g. "ex-post [comparison]", "cum-ex [date]" , "ceteris paribus", and frankly e.g. and etc. are Latin words as well.

I will remove "Modeling" from the wordlist. I cite the book as a reference. As it is by an American author, the title is with a single l rather a double l.

I know it's correct -- we don't want to be changing the spelling of a title. I just meant that the  bit should mean that it isn't flagged.

Re the Latin words (hah -- re is another), I wasn't asking you to change your text! I was just wondering if we could fix the spellchecker configuration for some of the things that don't look like words (e.g. "nd" which I guess is part of "2nd" or something).

I also changed Unified Modeling Language to Unified Modelling Language to comply
with the orthography of British English.

alexdewar · 2024-10-25T12:01:09Z

docs/posts/design_patterns.md

+![Definition of the Strategy Pattern](images/design_patterns/def_strategy_pattern.png)
+<!-- markdownlint-disable-next-line MD036 -->
+*The rendered result should look similar to the above figure.*


For figure captions, you can do this:

![My figure caption.](path/to/image.png)

I follow your suggestion for the syntax, but am not able to break the caption like this

![This is the first line of the caption.<br>This should be the second line of the caption](path/to/image.png)

Also, see here
for an explanation of the same issue.

Moreover, our markdown application does not support re-shaping images to fit them to the page, see here

Am thankful for suggestions.

docs/posts/design_patterns.md

Moreover, I reformatted the references sections as well as in-text references. Also, I slightly refined the text for fluency and improved some explanations.

HarmonicReflux · 2024-10-26T08:39:54Z

Disappointingly, my clickable references are not accepted by markdown.
I thought it was a useful feature for the references directly linking to the bibliography. It works on my local copy and markdown serve renders everything beautifully:

[Gemma et al. (1994)]
[Booch et al. (2005)]
[Shreve (2004)]

## References

<!-- spell-check-ignore -->
- <a id="gamma1994"></a> Gamma, E., Helm, R., Johnson, R., & Vlissides, J. *Design patterns: Elements of reusable object-oriented software.* Addison-Wesley, 1994.
- <a id="shreve2004"></a> Shreve, S. *Stochastic Calculus for Finance II: Continuous-Time Models.* Springer Finance, 2004.
- <a id="booch2005"></a> Booch, G., Rumbaugh, J., and Jacobson, I. *The Unified Modeling Language User Guide.* 2nd ed. Addison-Wesley, 2005.
<!-- end-spell-check-ignore -->

When pushing to the repo, I am thrown the following error:
``
markdownlint-fix.........................................................Failed

hook id: markdownlint-fix
exit code: 1
``

…original implementation renders beautifully and without errors on my local machine, but the pre-commit hooks complain.

…y blog post is in the References section and I thought to disable spellcheck like so  ...  will make it pass, but as it stands it does not.

HarmonicReflux · 2024-10-26T08:55:45Z

Forgive me @alexdewar for hacking wordlist.txt but having worked on this blog post intensely, I really do not know why spellcheck is such a pain to work with. I leave modifications to it to a future issue.

Also, I am not quite happy the References section is not interactive anymore, but I need to make
markdownlint-fix happy so I can finally publish my work. Again, agreeing on a good-looking references section that keeps the links between the citation in the blog and the References section at the end, is, in my oppinion, an issue for the future.

HarmonicReflux and others added 4 commits August 28, 2024 02:36

[pre-commit.ci] auto fixes from pre-commit.com hooks

ebc3f78

for more information, see https://pre-commit.ci

- Making markdownlint happy (hopefully) by removing blank lines.

a0d4ded

- Fix trailing whitespace issues

Merge branch 'main' into DesignPatterns2

5a0d471

HarmonicReflux self-assigned this Aug 28, 2024

This was referenced Aug 28, 2024

Blog post "Design Patterns in Financial Data Science" #22

Closed

Post on design patterns for financial data analysis in Python #13

Open

HarmonicReflux requested review from dalonsoa and dc2917 August 28, 2024 02:25

dalonsoa changed the title ~~My RSE blog post makes a contribution towards explaining UML and the …~~ Blog post on UML and the Strategy Design Pattern Aug 28, 2024

dalonsoa requested changes Aug 28, 2024

View reviewed changes

jamesturner246 self-requested a review August 30, 2024 10:50

jamesturner246 requested changes Aug 30, 2024

View reviewed changes

dalonsoa and others added 2 commits September 16, 2024 15:46

Merge branch 'main' into DesignPatterns2

b3e25d4

Improved explanation of the financial contract

83252f9

that is priced in this tutorial.

HarmonicReflux and others added 2 commits October 21, 2024 09:02

Incremental commit of the

f8c448f

restructured introduction that aims at being more explanatory and clearer on what the blog post deals with. This sets and simultaneously limits expectations and provides the reader with a clear overview.

[pre-commit.ci] auto fixes from pre-commit.com hooks

e84c981

for more information, see https://pre-commit.ci

AdrianDAlessandro self-requested a review October 21, 2024 14:23

dalonsoa requested changes Oct 22, 2024

View reviewed changes

docs/posts/design_patterns.md Outdated Show resolved Hide resolved

AdrianDAlessandro requested changes Oct 24, 2024

View reviewed changes

alexdewar and others added 11 commits October 25, 2024 11:00

pyproject.toml: Fix email

c0d5a46

Regenerate poetry.lock

f7f9b10

- Improved tutorial: Adapted functional programming paradigm and chan…

7686d4e

…ged UML diagrams and Oython code accordingly. - Expanded the overall text. - Included a section on the put-call parity to test the fair pricing - Increased the number of references

Merge branch 'main' into DesignPatterns2

636467b

attempt to avoid spell-checking code blocks as well as references.

8ec91e9

another attempt to save spell checker from itself by modifying

3fbeaaa

`.spellcheck.yml`

.

7275e94

.

44b7c77

.

fa57df3

.

4970f47

.

4079653