Detail for the Grafoscopio English web page.
This readme file introduce Grafoscopio in a quick way, to have a panoramic view of it and having it working easily. It is a edited shorter version of the full user manual, please refer to it for detailed documentation.
Grafoscopio is a moldable tool for literate computing and reproducible research developed on Pharo live coding and computing integrated environment, in the context of a PhD research in a hacker space of the Global South (HackBo in Bogotá, Colombia), that is being actively used, developed and documented. We will expand on the points of the previous definition.
Grafoscopio is intended to be used by learners and researchers in several fields: academia, journalism, activism, hacktivism and for anyone interested in open reproducible research and data storytelling backed by data and agile visualizations [@bergel_agile_2016]. This document assumes that you are such person. We will introduce the general features of Grafoscopio and point to several external and internal resources to complete your panoramic view of the ecosystem that let you deep your knowledge.
We included introductory resources to learn Pharo and data visualization, processing and storage related technologies (see the Help menu), and the Grafoscopio web page (see figure ) shows several examples of how to use them for specific projects: Panama Papers as reproducible research; open community innovation in access to medicine information; Twitter data selfies; specific domain visualizations for medicine information; open, garage and citizen science and research. This whole manual was also created using Grafoscopio and is also an example of the type of documents you can create with this tool. We hope to inspire you to create and publish your own projects.
This document, by not trying to be comprenhensive, is a first invitation to know the Grafoscopio environment and to deep your knowledge with the use of it and other related resources. You will see that, despite of being a manual, it includes pretty practical examples and invitations. That is because I think that learning something new is more like reading a map that reading a manual: you make first a panoramic view of where you are and where you want to be, and take a practical approach to making your tasks and reaching your destination.
No prior knowledge of programming is supposed to follow this manual.
Detail for the Grafoscopio English web page.
Important note > A prototype pointing to future possibilites | Despite of being pretty usable, you will see that Grafoscopio is not totally finished, and this shows in a few spots of the Graphical User Interface (GUI) that "point to the future", towards funtionality still to be implemented. It's an unusual approach, but I think that is important to convey some sense of possibility, and work to be done in the GUI, instead of a fully polished "product" or a GUI that hides what is not ready. This conviction comes from the hackathons and workshops where we worked and evolved Grafoscopio, while the workshop was happening(!), thanks to the dynamic, moldable and continuous nature of the Pharo live coding environment. Blurring the distinction between interactive documents authors and software developers, means to put the whole environment at their dispossal, and to show the community that they can be part of this future possibilities, and that is why we take this unusual approach to GUI.
Where the GUI is more a remainder for the future, I will point that using the TBD remark (for To Be Done).
Grafoscopio is similar to other tools and has been inspired by many of them, while is trying to bring also new possibilities, by combining different ideas, diverging from others, puting "parallel" ideas into dialog and, hopefully, bringing new ones. Here we talk about the similarities and differences with other tools.
Grafoscopio tries to become a simple, understandable, moldable, versatile and flexible tool thanks to the power of Pharo environment and ecosystem and the combination with mature external and internal frameworks and tools. It uses:
Dataviz companion package.Despite of trying to provide a friendly, cohesive and empowering user experience (UX) by integrating default external minimalist and/or self-contained tools into the data exploration and document publishing workflow, other external tools could be integrated (Git, more data bases, including NoSQL, other exporters and light markup languages and so on).
If you want to install Grafoscopio on Pharo 6 or 6.1, there are two ways of doing: via the Pharo catalog or via running a script from the playground. Both suppose that you have already installed and running Pharo for your platform (Windows, Gnu/Linux or Mac) from its download page, and will be explained below, from the easiest one to the far easy ones. Also both of them use the Monticello package manager, so dependencies are managed automatically for you, making the procedures really short, even for the script based one.
Different install procedures suit different tastes and needs and bring alternatives, so, if one doesn't work for you or your need/taste, you can try others, or just leave it like that, if your chosen method worked.
To install Grafoscopio, from Internet in Pharo 6 or 6.1, from the Pharo Catalog, follow this steps:
Tools > Catalog Browser, as shown in the figure .
Install screen 1 | Opening the Cataog Browser from the World Menu.
Enter key. A list of results matching the search criteria will be shown.
Searching for Grafoscopio in the Catalog Browser.
Install stable version from the Catalog Browser.
Install screen 3 | Installation progress bars.
Install screen 4 | Installation ended.
There are two ways of running scripts in the Pharo environment: one by importing them from Internet and the other by writing them manually.
If you want to run a Pharo script from its web address, open the spotter (Shift + Enter) and paste the address and then press Enter to open the interactive playground and finally press the Do it and go green play button or its shorcut (Ctrl + Shift + g). (An empty playground and its play button are showed in figure )
Empty playground and its play button.
Installing via scripts consists in two steps: the first step makes available the configuration of the project or package we want to install, that tells where the package/project and its dependencies are located and in which order they need to be installed; the second step runs (or loads) such configuration, making the new software available in our system. We are going to learn next how to run this two steps, by running separately from different playgrounds or by loading them progressively from the same playground.
For example, if you want to run the first part of the install script, open the spotter and paste this address http://ws.stfx.eu/ADBWX39G4FX0. You will see a screenshot similar to figure , showing the web address you have pasted and the first lines of the script below, marked in grey.
Loading the install configuration package.
Press Enter or select with the mouse the area with the grey background. You will see the interactive playground with the script loaded. We will see more details about the playground later. For the moment press the play button or the shorcut (Ctrl + Shift + g). You will see that the playground has been executed. An executed playground contains a new column with details of the object resulting from that execution, as shown in figure .
Executed playground.
Now repeat the procedure, opening the spotter, pasting this url http://ws.stfx.eu/CZ87ZZ2SXCEM and executing the second part of the installation script (showed in figure ).
Loading Grafoscopio.
You will see the progress bars and the ending of the installation process, as described in the steps 4 to 5 of the previous section.
Is usual to run the previous two steps in a single playground, by executing parts of it. Here we are going to show you how to do it, with the same installation example we have done so far. Open a playground (Ctrl + o + w) and write this (or paste the URL of this playground, in the spotter, as before):
1 2 3 4 5 6 7 8 9 | |
Now select with the mouse the first 5 lines of the script and make click with the mouse secondary button. A contextual menu will be show near to the selection, as shown in the figure . Choose from that menu the Do it and go option (or press the Ctrl + g keyboard combination). Only the selected part of the script will be executed.
Selecting the script part that will be executed and deploying the contextual menu.
Executing the second part of the script.
Now select the second part of the script, the last two lines, as shown in figure and repeat the previous procedure. You will see the progress bars and the ending of the installation process, as described in the steps 4 to 5 of the previous section.
Important: Once we have Grafoscopio installed, by any of the means shown in this section, is important to save the modifications to our computing environment, by making click in any clean part of the GUI (not occupied by any window) to deploy the World Menu. There we choose Save, to save the system with the same name, or Save as to save it with a new one (see figure ).
Saving changes to our Pharo environment via the World Menu.
For detailed usage instruction please read the extended version of this readme file in the Grafoscopio User Manual. This short readme, derived from that manual, follows the JOSS outline for a quick overview of the software.
There is a dedicated complementary package, called Dataviz, with examples, that was build with educative purposes, for a recurrent local workshop called the Data Week, where we invite a diverse community in gender, professions, educational and life backgrounds and is automatically installed when you install Grafoscopio. Also we have a Spanish introductory tutorial, that is directed towards beginners.
To see such examples please execute this code form the playground:
1 2 | |
1 2 | |
Because Grafoscopio inhabits a full live coding environment, it follows the custom of making the API documentation available inside a dynamic environment, instead in some static web page. To open the Grafoscopio package inside the system browser, and see the messages organized by protocols execute:
1 2 3 4 5 | |
The core functionality of Grafoscopio document tree model is tested. If you want to see and run the tests, just open the tests package by executing:
1 | |
From there, you can use the extensive test environment provided by Pharo. For a short introduction to how to run test on this environment, I recommend to watch the Coding a Little Domain Specific Language video, from the Pharo MOOC.
There is a non critical but annoying bug that presents from time to time when you are using the notebook GUI.
Some times, when you click the document tree a window popup with an error message, titled "MessageNotUnderstood: receiver of "selectedMorphList" is nil", as shown in figure .
The know bug message.
If that is the case, you still can continue your writing in the current document, clicking on other notebook nodes and editing them, but if the message presents again (usually when selecting the same node that originated it the first time), you can save the notebook and reopen it again from the Launch > Recent notebooks... docking bar menu.
We are going to hunt and squeeze that bug out of existance. Resistance is futile. To help us with this or other bugs please look at the Community Guidelines to know how to contribute to the project.
Grafoscopio has a small and new born community. You can reach it by following the contact links in the Grafoscopio page in Spanish or in English.
Also you can discuss issues related with Grafoscopio in the Pharo users community mailing list. We are in such list and try to be active participants there and bridge the local Spanish community with the international one.
To report issues or problems with the software and/or its documentation please visit our ticket section Fossil repository. Before creating a new ticket, please be sure to visit the current tickets, to see if your issue/problem has been not reported already.
As we said, Grafoscopio wants to help in blurring the distinction between software developer and interactive document author, so we are pretty open to several ways of contribution: from bug reports, as explained above, to the creation of interactive documentation, domain specific languages (DSLs) and visualizations, or software functionality.
Contributions usually take part on our recurrent Data Week hackathon/workshop and there you will learn how to use and adapt the software, starting by the basics, creating DSLs and crafting visualizations and integrating them into interactive notebooks. You will also learn how to use Fossil and how to commit to our shared repositories for code and for documents and issues. Besides this manual, we are creating also a tutorial (in Spanish) with all these themes covered, as memories for us and others to remember and learn from. The idea, as was said before, is to have multilingual documentation with a local first approach.
If you don't have the chance to assist to one of our face to face learning workshops and hackathons or to use the resulting notebooks, but still want and already know who to contribute, you can also ask for permisions in the respositories using any of the contact methods listed above. We are a small, new born and friendly community with low traffic mail communication and can discuss about contributions on an individual case by case approach, so your words, bugfix and suggestions will be listened and taking into account and integrated when and where they make sense.
Welcome again to our community :-).
Grafoscopio and its tutorial is licensed under MIT license and the readme and the User Manual, and other documentaiton is licensed under a modified P2P license. To see a full copy of such respective licenses, please visit the files under this repository:
IDE: Integrated software Development Environment↩
The idea of the "document is a program" is a paraphrasis of "the book is a program", stated in the Pollen documentation, which is a short phrase to express a powerful idea about burring the disctinction between the document and the program, that is present in several programs, like TeXmacs, Leo, Org Mode, and, of course, Grafoscopio.↩