Discuss: Standardization of Title and About sections

[jackiekazil]

When I added a description to the bank reserves model in PR #587, I thought about three things that I wanted to throw out for discussion...

1. WHAT IN ABOUT: What should go into an about on the front-end versus the readme versus the description of the Model in the model.py? Are they mutually exclusive? Do they overlap?

2. WHERE TO STORE: Where should the "About" be stored? (Are their reusable components?) Is the model.py description the best place?

3. HOW TO DISPLAY: Most of the Abouts that have been written are two lines. The one in #587 was much longer. I stopped, because there is the lack of formatting. Maybe we should allow for Markdown? (This would be after we figure out the answer to the first one.)

[Corvince]

Good discussion point!

Here is my first intuition without thinking too much about it.

1. Readme: General description of the model, agents, outcomes, etc. Can be as long as one wants, including rich formatting
2. model.py: "Docstring-style": One-Liner about the general model. Longer text about implementation details, where to find which function, etc.
3. Front-end: Visualization info: What to look for, whats the effect of user-settable parameters, etc.

That would be my first idea/expectation.

[jackiekazil]

@Corvince ... and are some of those parts reusable? And if so, where do they live? Or is this just a copy and paste situation? (When I created the description for bank reserves model, which is the PR I refer, all I did was take from the README since I didn't know much about the model.)

[Corvince]

No, I would have suggested the parts to be mutually exclusive. Especially the model.py description should only interest people who want to inspect the code and/or modify the model. I was thinking of a general workflow like first reading/skimming the Readme. And if that model sounds interesting, run the model. At that moment it should be known how the model works and one would be more interested to know what effect of the user-settable parameters are and what to look out for. And only if one really wants to know the details, look at the model.py implementation. At that point a general description of the model should be superfluous.

But hey, thats just my first idea. And it goes against the current situation, especially on the front end with the about section. What I could imagine is that you could open the readme file from the front-end.

---

Ok I was just having a quick look at some of the examples readme files and I realized how messy the current situation is. And also that sections like "installation" and "how to run" wouldn't make sense at the front end.

That's a more serious issue then I thought!

[majdal]

This is a very important issue, so I'll put my UX designer hat on and throw in a few thoughts:

To me, one of the most useful things about ABMs is that they facilitate communication between users.

One of the main reasons that I chose Mesa over other frameworks is that it works in the browser, which means I can make it network accessible.

If my model is network accessible, it means that it's possible that a user can try it without me being there to explain what's going on.

So, the user should be able to view the model and be able to play with it without having access to the source code.

I suggest that we follow the "information scent" principle, and offer three places for information:

• Title: currently the title of the model is greyed out and occupies the same level of hierarchy as the About and controls section. It should be a lot more prominent.
• Brief description: As soon as they land on the page, the user should be able to read a paragraph that explains what they are looking at.
• Details: This includes implementation details, possible scenarios to run, credits, and any other information that the model creator deems useful. This section not immediately visible to the user but should be viewable side-by-side with the model, so that the user doesn't have to flip back and forth between tabs to try out the suggestions included.

There's a lot of different ways that this could be implemented, but I'll throw this out just to restart the discussion.

[Corvince]

Very good points @majdal!

For me the visualization was always more for the modelers themselves. But in this respect rather pointless, because it is a lot of additional work to do it the Mesa way for little added benefit (compared to running batchrunner and plotting the results with matplotib or similar).

It is probably much better to view the visualization as a communication tool and in this regard we can probably do a lot better. To be honest apart from your points the whole thing looks rather premature.

Maybe you can come up with a mock-up of how you imagine things?

[majdal]

Glad to hear that you agree :)

I'd be glad to create a mockup. I started with a few sketches, and I was trying to stick to the UI vocabulary provided by Bootstrap. However, I started hitting the limitations of the framework very quickly.

• The UI is very "bulky", with components that distract from the functionality of the model
• Bootstrap is mostly focused on layout, not on UI creation. So, most of the most useful UI components (sliders, counters, etc...) are 3rd party, and are dependant on a Javascript build system. This creates a lot of cluttering, both in the code and in the UI.

I'm very hesitant to suggest this, but I think it might be a good idea to think of changing the UI framework (as opposed to a layout framework) to one that is more comprehensive. This will create a lot of refactoring tasks on the short term, but I think will be beneficial long term. But since a UI refresh is a thing that we agree on, it might as well be a comprehensive one.

A few options:

• Foundation: Nice UI, lots of components, well documented and widely used
• UIKit: Much lighter both in code footprint and visually, more comprehensive component list

Both can be integrated progressively, and have themeing options.

BOUNS (and this is dear to my heart as an Arabic speaker): they have native right-to-left layout support.

There are other options, e.g. Bulma, but they're less well-established.

There are two tasks here:

1. Estimate how much work would refactoring the frontend for a different UI be
2. Draw a mockup based on the current Bootstrap UI and based on an alternative UI

---

PS a more radical option would be to make full use of web components by using a front end framework like Vue.js, but I won't open that Pandora's Box 🙈📦 (CC: @kamicut)

[tpike3]

@majdal This is great! I am all for a long term enduring solution. I have very little UI experience and as @Corvince stated I also have been more interested in BatchRunning and doing a quick viz for debugging and hadn't really thought of it as a communication tool. Although I can immediately see the benefit.

I will start looking into Foundation, UIKit and Vue.js just to get smart on them, but out of curiosity what would be your dream approach if you had a carte blanche and lots of time?

[Corvince]

@majdal have you seen my PR in #718? It's a rewrite if the viz module, Backend and frontend. There is a preview available on glitch: [https://four-e.glitch.me/]().

The frontend is structurally very similar, but after that I feel pretty comfortable with how the mesa front end works. And I have been going forward and backward with rewriting everything as a proper SPA. I actually wanted to start with a react rewrite a few days ago, but couldn't bare with the thousand of files created by create-react-app. If you look at the current implementation it really is just a bunch of functions, so going full SPA is a bit of an overkill. But on the other hand I really want to do it as a learning project. So I would be happy to rewrite the front end once again e.g. with Vue.js, if you or someone else helps with sketching out the UI.

[majdal]

I've been thinking about this for a few days, and there's a TON of possibilities. I'd say that we would shouldn't fall into the typical trap that us techies fall into, and create an engineering solution to a UX problem :)

So, whether we choose to build an SPA with React or Vue.js, or a lighter UX polish with UIkit, etc.. we should prioritize the user experience, conceptualizing it as a communication tool to non-experts.

A few user stories of what I'd use to frame the discussion. Some are more relevant than others, but they're a good starting point.

• As a thesis supervisor, I'd like to play with my student's ABM remotely, so that I can view and verify their progress
• As a policy maker, I'd like to test out a few scenarios of a model, in order to understand the dynamics of a complex system
• As an engaged citizen, I'd like to verify some scenarios proposed to me by policy makers, in order to verify their claims
• As a model developer, I'd like to play with my model parameters on the fly, in order to verify their effects
• As a model user, I'd like to visualize the output of two different model scenarios, in order to compare them
• As a model user, I'd like to visualize the output of my data as a (bar chart/column chart/line graph/map), in order to understand the dynamics of the model
• As a model developer, I'd like to compose the the user interface using modular components, in order to allow for flexible user interaction
• As a model user, I'd like to be guided by the model creator on how to understand and use the model, in order to make maximum use of it
• As a model user, I'd like to save the output of my model run as a database file (csv, sqlite, etc...), in order to share it in a publication, and make my own visualizations
• As a model user, I'd like to be able to understand the model components at a glance, in order to start experimenting with it quickly

These are a few, in no particular order. I'll try to come up with a quick sketch soon.

Meanwhile, Happy Eid to those celebrating! ⭐🌙🏮🌙⭐