Skip to main content

The glass box design philosophy

There is an interesting paradox in context of developing data analysis software. On one side, there are clear benefits of designing tools that are easy to use, robust and require as little manual intervention or user expertise as possible. Such design philosophy allows more users to take advantage of the tools and apply them automatically to large heterogeneous datasets. On the other side, blindly applying tools that are not fully understood or do not provide useful information on whether the input data meets their assumptions can raise serious concerns. Developers take not only great pride in the quality of their software but also feel responsible for how the software is being used. Unexperienced users can misuse a “black box” tool and obtain misleading results. Whether we like it or not, such situations can lead to bad reputation misattributed to the tool itself.



Ease of use seems to be at odds with avoiding misuse. Extending your user base to less experienced users can lead to mistakes. Is there a way of designing “black box” tools that can minimize misuses? I believe there is - I call it the glass box philosophy.

The glass box principles

Write educational documentation

The documentation for a data analysis tool should aspire not only to describe how to run the tool but also to explain the theory and assumptions behind the analysis. In this, it should resemble more of an academic handbook than instruction manual.

It does not mean that developers must come up with their original content if such exists already. The purpose of educational documentation is that if the user wants to understand how a tool works they can learn about it from documentation in a programming language agnostic way.

Verify or visualize assumptions

Most data analysis tools will consist of several steps each with their distinctive assumptions. If a step fails to produce expected results (in a silent way) it could have catastrophic consequences down the road. Unfortunately, in many cases, it is very hard or even impossible to programmatically verify if the results of a particular step meet quality requirements of the subsequent step. Thus, it is important that data analysis software provides an option to verify or visualize those assumptions. Such reporting capabilities might not be necessarily taken advantage by the user directly but can provide an extra layer of transparency. For example, more experienced users or reviewers of a paper describing the results could audit the reports generated by data analysis.

Guide dissemination of the results

Obviously, the purpose of running a data analysis tool is to learn something about the data from the results. In clear majority of the cases, users will share the findings with people who were not involved in the analysis and might not know the details of the tool. Whether it is an internal report or an academic paper the user that runs the tool and obtained the result bears the responsibility of explaining to others what the analysis entailed. Here the tool developers can also help by providing boilerplate language summarizing the inner workings of the tool (referencing relevant external materials when possible). Peers of the user who performed the analysis will appreciate such feature because it allows them to understand better what exactly happened to the data. In case of robust tools that use heuristics to adapt to the input data, the boilerplate language should also automatically adapt to accurately describe the analysis path that was taken.

FMRIPREP – an example of a glass box application

To better understand how a glass box application should look like let’s have a look at an example. FMRIPREP is an MR data preprocessing tool that takes whatever comes out of a magnetic resonance scanner and prepares it for higher level analysis. It was designed to adapt to a range of different scan types and use heuristics to provide quality results on a data produces by different scanners. The robustness and ease of use make it appealing to use, but also susceptible to misuse. So how does FMRIPREP implements the glass box principles?

Educational documentation

_images/workflows-3.png
Documentation provided by the developers of FMRIPREP goes beyond the instruction how to use it. It includes a detailed explanation of the data processing workflow – together with figures and references to relevant literature. This rich documentation allows interested users to understand what happens to their data. The documentation does not rely on any knowledge of Python (which is the language FMRIPREP is written in).

Reports


Preprocessing performed by FMRIPREP consist of many interdependent steps. Some of them cannot be validated in an automatic way which leads to a need for visual reports. For every processed piece of data, FMRIPREP produces an HTML report that includes figures and animations designed to highlight different data processing steps. Those reports enable users to quickly verify the validity of individual steps without the need to write any custom code or open intermediate results using specialized software.

Citation boilerplate


FMRIPREP is targeted for research use, and thus its uses will most likely lead to scientific publications. One cannot assume that readers of those publications will be familiar with FMRIPREP, so there is a need to provide an abbreviated description of processing performed by FMRIPREP. The documentation website provides such boilerplate text ready to be reused in publications that used FMRIPREP. Because FMRIPREP runs the slightly different type of processing depending on the inputs, the boilerplate text can be easily adapted via JavaScript controls listing different input options.

Cost

I hope I made a convincing argument for building robust, easy to use software that also excels in transparency. It is worth noting that the extra steps that need to be taken to turn a black box analysis tool into a glass box analysis tool require extra effort. After all guides for interpreting results and the educational documentation will not write itself and code for reporting tools will not appear out of anywhere. Nonetheless, I do feel that the glass box philosophy is worth pursuing and may reduce the amount of user support necessary for the analysis tool. Furthermore, some of the addition necessary to turn your app into a glass box (for example documentation) could be contributed by users themselves. This is a great opportunity to grow your open source contributor network.


PS I by no means invented the term “glass box” – it has been used previously (for example in the context of software testing). However, because this term fits so well with these design principles I decided to highjack it.

Comments

  1. I wish to show thanks to you just for bailing me out of this particular trouble. As a result of checking through the net and meeting techniques that were not productive, I thought my life was done.chartered accountant firms in dubai

    ReplyDelete
  2. I feel this is among the such a lot vital info for meCashflowbest

    ReplyDelete
  3. Thanks for sharing this, I actually appreciate you taking the time to share with everybody.
    Best Institute For Data Science In Hyderabad

    ReplyDelete
  4. It is nice thing! Looks cool. Buy facebook likes for it from this page https://soclikes.com/

    ReplyDelete
  5. I've read this post and if I could I desire to suggest you some interesting things or suggestions. Perhaps you could write next articles referring to this article. I want to read more things about it!
    data science training

    ReplyDelete
  6. This is most informative and also this post most user friendly and super navigation to all posts... Thank you so much for giving this information to me..
    data science course in delhi

    ReplyDelete
  7. As always your articles do inspire me. Every single detail you have posted was great.
    certification of data science

    ReplyDelete
  8. Hello there to everyone, here everybody is sharing such information, so it's fussy to see this webpage, and I used to visit this blog day by day
    data science course in delhi

    ReplyDelete
  9. Enjoyed reading your blog. Please check my latest post on the professional accountant in Dubai and let me know what you think.

    ReplyDelete
  10. Very awesome!!! When I searched for this I found this website at the top of all blogs in search engines.
    Data Science Training in Hyderabad

    ReplyDelete
  11. I want to leave a little comment to support and wish you the best of luck.we wish you the best of luck in all your blogging enedevors.
    data science course fees in bangalore

    ReplyDelete
  12. great article!! sharing these type of articles is the nice one and i hope you will share an article on data science.By giving a institute like 360DigiTMG.it is one the best institute for doing certified courses
    data science certification

    ReplyDelete
  13. nice blog!! i hope you will share a blog on Data Science.
    data science training in pune

    ReplyDelete
  14. Interesting article. AMCA is a leading audit firm in Dubai, UAE. We offer a variety of auditing & accounting services in Dubai. We are FTA approved tax agency.

    ReplyDelete
  15. This article is amazing. It helped me a lot. keep up the good work. data science institute in delhi/ncr

    ReplyDelete
  16. What a really awesome post this is. Truly, one of the best posts I've ever witnessed to see in my whole life. Wow, just keep it up.
    digital marketing courses in hyderabad with placement

    ReplyDelete
  17. I have read Your Article and Learn a lot from it. I can Imagine the time it took to get all this expertise exposed . You can also look here to see where to easily get a HIGH QUALITY BANK STATEMENTS FOR MORTGAGE I've bookmark your site and furthermore include RSS. keep us refreshed all the time.

    ReplyDelete
  18. Really impressed! Everything is very open and very clear clarification of issues. It contains truly facts. Your website is very valuable. Thanks for sharing.
    data science training

    ReplyDelete
  19. Extremely overall quite fascinating post. I was searching for this sort of data and delighted in perusing this one. Continue posting. A debt of gratitude is in order for sharing. python course in delhi

    ReplyDelete
  20. I am impressed by the information that you have on this blog. It shows how well you understand this subject.
    data science course


    ReplyDelete
  21. I was basically inspecting through the web filtering for certain data and ran over your blog. I am flabbergasted by the data that you have on this blog. It shows how well you welcome this subject. Bookmarked this page, will return for extra. data science course in jaipur

    ReplyDelete
  22. Really Nice Information It's Very Helpful All courses Checkout Here.
    ai courses aurangabad

    ReplyDelete
  23. I have been searching to find a comfort or effective procedure to complete this process and I think this is the most suitable way to do it effectively.
    data scientist training in malaysia

    ReplyDelete
  24. Great tips and very easy to understand. This will definitely be very useful for me when I get a chance to start my blog.
    data science course in malaysia

    ReplyDelete
  25. Amazing Article! I would like to thank you for the efforts you had made for writing this awesome article. This article inspired me to read more. keep it up.
    Data science course in pune

    ReplyDelete
  26. Very interesting , good job and thanks for sharing such a good blog. we also provide glass software solutions. for more info visit our website.

    ReplyDelete
  27. Impressive. Your story always bring hope and new energy. Keep up the good work.
    data science training

    ReplyDelete
  28. Looking for all the latest styles of jackets 8 ball leather jacket and coats for men? Shop the best collection of men's jackets and coats. Free shipping available.

    ReplyDelete
  29. I want to say thanks to you. I have bookmark your site for future updates.
    data scientist course in chennai

    ReplyDelete
  30. Thanks for these blog post . It is really amazing and having good knowledge about these post. I appreciate by seeing your work. glass software solutions.

    ReplyDelete
  31. Extraordinary post I should state and a debt of gratitude is in order for the data. Instruction is unquestionably a clingy subject. Be that as it may, is still among the main subjects within recent memory. I value your post and anticipate more.data science training in lucknow

    ReplyDelete
  32. First You got a great blog .I will be interested in more similar topics.I commend you for your excellent report on the knowledge that you have shared in this blog.

    digital marketing training in hyderabad
    free digital marketing course in hyderabad

    ReplyDelete
  33. Very good points you wrote here..Great stuff...I think you've made some truly interesting points.Keep up the good work.
    data science course

    ReplyDelete
  34. Impressive. Your story always bring hope and new energy. Keep up the good work. Data Science Course in Vadodara

    ReplyDelete
  35. Ready to Book your Business Centers in Dubai? Spider Business Center offers Fully furnished and fully equipped office spaces for rent in Dubai’s Sheikh Zayed Road.

    ReplyDelete
  36. Great Article Image Processing Projects Deep Learning Projects for Final Year JavaScript Training in Chennai JavaScript Training in Chennai The Angular Training covers a wide range of topics including Components, Angular Directives, Angular Services, Pipes, security fundamentals, Routing, and Angular programmability. The new Angular TRaining will lay the foundation you need to specialise in Single Page Application developer. Angular Training Project Centers in Chennai

    ReplyDelete
  37. I really appreciate this post. I have been looking all over for this! Thank goodness I found it on Bing. You have made my day! Thanks again! 바카라사이트

    ReplyDelete
  38. Great Information sharing .. I am very happy to read this article .. thanks for giving us go through info.Fantastic nice. I appreciate this post. 토토사이트

    ReplyDelete
  39. It has truly been an absolute pleasure visiting your site. It is a pleasure to have you on board and thanks for sharing your blog site with us - it is greatly appreciated.
    룰렛사이트탑

    ReplyDelete
  40. I was just examining through the web looking for certain information and ran over your blog.It shows how well you understand this subject. Bookmarked this page, will return for extra.

    ReplyDelete
  41. Thanks for making the sincere attempt to explain this. I think very robust about it and want to learn more. If it’s OK, as you attain more extensive knowledge 온라인바카라

    ReplyDelete
  42. This comment has been removed by the author.

    ReplyDelete
  43. This Is Very Nice and Wonderful Keep Writing Such type Of Wonderful blogs
    안전놀이터

    ReplyDelete
  44. Yes, I am entirely agreed with this article, and I just want say that this article is very helpful and enlightening. I also have some precious piece of concerned info !!!!!!Thanks. bitmain antminer s19

    ReplyDelete
  45. I really impressed after read this because of some quality work and informative thoughts . I just wanna say thanks for the writer and wish you all the best for coming Courtier immobilier Hull

    ReplyDelete
  46. I am hoping the same best effort from you in the future as well. In fact your creative writing skills has inspired me
    Restaurant chair

    ReplyDelete
  47. Wow, this is really interesting reading. I am glad I found this and got to read it. Great job on this content. I like it
    used motorcycles for sale

    ReplyDelete
  48. Thank you for another great article. Where else could anyone get that kind of information in such a perfect way of writing? I have a presentation next week, and I am on the look for such information polaris dealer

    ReplyDelete
  49. I am sure this post has touched all the internet viewers, its really really good paragraph on building up new webpage
    polaris dealer

    ReplyDelete
  50. There are many dissertation internet sites on-line after you uncover unsurprisingly identified in your website page. ✅
    antique display cabinet

    ReplyDelete
  51. I read a article under the same title some time ago, but this articles quality is much, much better. How you do this..
    Skip Hire Ulverston

    ReplyDelete
  52. So lot to occur over your amazing blog. Your blog procures me a fantastic transaction of enjoyable.. Salubrious lot beside the scene
    shipping from china

    ReplyDelete
  53. So lot to occur over your amazing blog. Your blog procures me a fantastic transaction of enjoyable.. Salubrious lot beside the scene
    Shipping To FBA Warehouse From China

    ReplyDelete
  54. I found so many interesting stuff in your blog especially its discussion. From the tons of comments on your articles, I guess I am not the only one having all the enjoyment here! keep up the good work. Compliance Services Malta

    ReplyDelete
  55. This is such a great resource that you are providing and you give it away for free. I love seeing blog that understand the value. Im glad to have found this post as its such an interesting one! I am always on the lookout for quality posts and articles so i suppose im lucky to have found this! I hope you will be adding more in the future... Wordpress Malta

    ReplyDelete
  56. I want to leave a little comment to support and wish you the best of luck.we wish you the best of luck in all your blogging enedevors
    data science course in trivandrum

    ReplyDelete
  57. I am jovial you take pride in what you write. It makes you stand way out from many other writers that can not push high-quality content like you 토토사이트

    ReplyDelete
  58. This is important, though it's necessary to help you head over to it weblink:
    출장홈타이

    ReplyDelete
  59. Very nice article, I enjoyed reading your post, very nice share, I want to twit this to my followers. Thanks!
    토토커뮤니티

    ReplyDelete
  60. This is important, though it's necessary to help you head over to it weblink: 바카라사이트

    ReplyDelete
  61. I had been tiny bit acquainted of this your broadcast provided bright clear idea
    파워사다리

    ReplyDelete
  62. I had been tiny bit acquainted of this your broadcast provided bright clear idea 스마일도메인

    ReplyDelete
  63. I had been tiny bit acquainted of this your broadcast provided bright clear idea
    메이저사이트

    ReplyDelete
  64. Very nice article, I enjoyed reading your post, very nice share, I want to twit this to my followers. Thanks!
    토토사이트

    ReplyDelete
  65. "Excellent article. I’m going through many of these issues as well..

    " 토토사이트

    ReplyDelete
  66. I recently came across your blog and have been reading along. I thought I would leave my first comment. I don't know what to say except that I have enjoyed reading. Nice blog. I will keep visiting this blog very often. 토토솔루션

    ReplyDelete
  67. 360DigiTMG, the top-rated organisation among the most prestigious industries around the world, is an educational destination for those looking to pursue their dreams around the globe. The company is changing careers of many people through constant improvement, 360DigiTMG provides an outstanding learning experience and distinguishes itself from the pack. 360DigiTMG is a prominent global presence by offering world-class training. Its main office is in India and subsidiaries across Malaysia, USA, East Asia, Australia, Uk, Netherlands, and the Middle East.

    ReplyDelete
  68. Thanks for sharing this. This would be a big help but I think writing an essay for college application
    needs only determination. If you are determined enough to enter college.
    leather jacket

    ReplyDelete
  69. Wishing you the best of luck for all your blogging efforts.This is my first opportunity to chat this website
    I found some interesting things and I will apply to the development of my blog.
    wedding photography packages

    ReplyDelete
  70. Thanks you for sharing this unique useful information content with us. Really awesome work. keep on blogging

    Glass companies in Nigeria

    ReplyDelete
  71. Battisti showed Tucci how he makes risotto alla Milanese at his restaurant Ratanà, but if
    부산모텔출장

    ReplyDelete
  72. "My introduction to risotto was my mother's risotto Milanese," Tucci wrote, "but I have
    부산출장

    ReplyDelete
  73. Thanks a lot. Your blog made my day. Keep sharing this type of information if any one is thinking about applying for a Turkish visa please, don't waste yours time. Now you can easily apply for Turkey visa. The application process is totally online based . and if you face any problem at the time of filling the application form you can also contact us.

    ReplyDelete
  74. This is an excellent post I seen thanks to share it. It is really what I wanted to see hope in future you will continue for sharing such a excellent post. Data Science Course in Vadodara

    ReplyDelete
  75. Thanks for sharing this valuable information, we also provide instagram video download and,
    really appreciate your hard work and good research that help us in for of your good valuable article. Keep updating us with your awesome content.

    ReplyDelete
  76. Really nice and interesting post. I was looking for this kind of information and enjoyed reading this one. Keep posting. Thanks for sharing.data scientist course in bhubaneswar

    ReplyDelete
  77. I am happy to find your distinguished way of writing the post. Now you make it easy for me to understand and implement the concept. Thank you for the post. result totomacau

    ReplyDelete
  78. Thanks for your efforts in sharing this post with us. This was really awesome. kindly keep continuing the great work. Architectural glass companies in Nigeria

    ReplyDelete
  79. its really approaching and appealing content for reading and implementation purpose.
    accounting software uae

    ReplyDelete

  80. I learn from a good blog, your blog is a great inspiration, thank you. India visas for US citizens are available online. US citizens can apply for an Indian visa within 5 to 10 minutes. Firstly you can read all the document requirements for Indian visa for US citizens via our website then you can apply for your Indian visa.


    ReplyDelete
  81. This comment has been removed by the author.

    ReplyDelete
  82. https://www.igotbiz.com/directory/listingdisplay.aspx?lid=192087

    https://www.jigsawplanet.com/ConnectFreelance?viewas=0255d69d5b78

    https://bbpress.org/forums/profile/freelancevisadubai/

    https://buddypress.org/members/freelancevisadubai/profile/

    https://www.pixnet.net/pcard/91053621f564324939/article/e26ba240-e65f-11ec-a0e8-49c1d4c9968e?utm_source=PIXNET&utm_medium=pcard_article&utm_content=91053621f564324939

    https://elearning.wmich.edu/d2l/lms/blog/view_userentry.d2l?ou=6606&ownerId=86384&entryId=407&ec=0&expCmd=1&sp=&gb=usr

    https://www.blogger.com/profile/02911435215444306999

    https://ameblo.jp/eddy900/entry-12747221132.html

    https://linktr.ee/connectfreelance

    ReplyDelete
  83. Truly mind blowing blog went amazed with the subject they have developed the content. These kinds of posts are really helpful to gain the knowledge of unknown things which surely triggers to motivate and learn more. Travelers can obtain a Turkey visa from anywhere in the world. It is an electronic visa that can be obtained through the internet.

    ReplyDelete
  84. https://www.vingle.net/posts/4588482
    https://c4c.tribe.so/post/the-advantages-of-hiring-a-payroll-service-in-the-uae-62cd69388f564cbc5bc412a6
    https://roggle-delivery.tribe.so/post/the-trending-stuff-about-freelance-visa-62cd6fdd5e80e003b3242f1e
    https://business-services-dubai.mystrikingly.com/
    https://professionalservicesdubai.mystrikingly.com/

    https://proexpert2112.tribe.so/post/steps-to-do-business-setup-in-dubai---explained-by-connect-me-62d15cf2ec1678b8482fde62
    https://articlization.tribe.so/post/how-dubai-will-be-the-best-destination-for-business-setup-62d163fd799c7731564f7d15
    https://legendarymedia.tribe.so/post/how-to-start-ecommerce-business-in-uae-emirates-62d1669dcad81e582f6a58a7

    ReplyDelete
  85. I have read your article which is so amazing and easy to read & understand. I hope your audience enjoys it. Passengers who are willing to wish Turkey and want a Turkey evisa they can visit the website for applying online.

    ReplyDelete
  86. I truly adored visiting your post and this content was very unique. Thanks a lot for sharing this...
    Virginia Spousal Support Calculator
    Virginia Spousal Support

    ReplyDelete
  87. I appreciate your blog, from this session i got good knowledge. I admire your effort in writing valuable blogs. Thanks
    Online Solicitation Of A Minor
    military divorce in virginia
    Ley de conducción imprudente de Virginia

    ReplyDelete

Post a Comment