The Python script used to generate mental model diagrams has been updated to allow for added flexibility in output. Originally, box labels greater than about 48 characters would render outside the margins of the box, requiring close monitoring of the label length and often caused the label to be rewritten awkwardly or with abbreviations.
The new script was updated to allow for the following:
- Variable box height setting (on or off)
- Base box height setting
- Max box height setting
- Page aspect ratio may be altered, allowing the mental model diagram to be rendered in either landscape or portrait
- The boxes with the greatest height are moved to the top of the tower when rendered
- Tower height/width is rendered relative to the cumulative height of the boxes plus margins
Requirements for Running the Script
- Install Python version 2.6.2 for Windows (latest supported by PyWin)
- Install Pywin32 version pywin32-212.win32-py2.6.exe (Match the version number to the version number of Python you install–you will need to look at the list of exe files to find the right one, which may involve clicking on an upper-level folder; don’t just “download now” the whole package. Go for the matching exe file, with a strange file name like the one I show here.)
- Excel is required to run the script. The script does run with Excel 2003, but has not been tried with other versions
- While Omnigraffle or Visio are not required to run the script or create the diagram, they are required to view the diagram
- Note: As of Jan 2011, I have tried running Python27 on my Win7 32-bit OS, with the matching win32 Python extension, and it works. I have not tried Vista, egad.
Setting Variables Within the Script
Variables within the script may be set by the user to adjust the appearance of the mental model diagram. To set variables, open the script in any text editor such as NotePad or UltraEdit. There are numerous text editors available for free if you do not have one. Avoid rich text editors such as MS Word, or WordPad.
Caution: There are several variables that are calculated relative to other variables. Tower width is an example of this, where it uses the BOXWIDTH setting plus the spacing settings to render the Tower width. If you change these settings you are likely to break the script. If you do this, please download a fresh copy of this mental model script.
The first variable you may change is VariableHeight. Setting it to “False” restores the original script behavior, hiding all updates in this release. BOXHEIGHT defaults to 0.375 inches (3/8″). (You can reset this variable if you want.) At this default height, box labels will be restricted to about 48 characters and will overflow the box margins if too long. Setting VariableHeight to “True” allows the boxes to adjust automatically to the length of the content. (default = True)
The second variable you may change is PageLength. This variable allows the height of the diagram to be set in inches. Setting this variable to 11 for example will cause the diagram to render in portrait. Setting it to 8.5 will cause the diagram to render in landscape. (default = 11″ – portrait) One can assume that setting it to other numbers will allow rendering for slightly different page heights, although we have not tested it yet. Between this variable and MaxTowerHeight, one could possibly format the model to fit on plotter paper, admittedly still at the small font size.
Box Variables If VariableHeight=True:
- MAXBOXHEIGHT – Sets the maximum height in inches for the box height (default = 1.5 inches)
- MINBOXHEIGHT – Sets the minimum height in inches for the box height (default = 0.375 inches, 3/8″)
- BOXWIDTH – Sets the width of the Task boxes (default = 0.625 inches, 5/8″)
- Box2BoxSpacing – An empty space between boxes (default = 0.0625 inches, 1/16″)
Tower Height Variables If VariableHeight=True:
- MaxTowerHeight – Sets the maximum height for the tower (default = 4.05 inches)
- VariableTowerHeader – Turn on/off tower header content adjusting. Turned on (True) computes a space occupied by a tower header and adjust the boxes accordingly. Disabled (False) leaves a constant space controlled by a variable TowerHeaderExtra (default = True)
- MaxBoxNumberPerColumn – Sets the maximum number of boxes in a tower (default = 7)
- Box2TowerSpacing – A gap between a tower border and a box side (default = 0.125 inches, 1/8″)
- TowerHeaderExtra – Height of the tower header if VariableTowerHeader = False (default = 0.375 inches, 3/8″)
Troubleshooting
- If you are not using the Excel template, please be aware the the script is looking for column headings with the following labels in the exact order: Mental Space, Task Tower, Task
- Some characters will not render by this version of the script. Curly quotes will break the script, as well as some diacritical marks such as the acute acccent in fiancé.
- This script has been tested on the PC, but it has not been ported to the Mac.
Note: this list will be updated as new issues are found.
