Overview
ResearchMaster is a tool that you can trust to help with organization, multitasking, and research -- both personal and professional. ResearchMaster provides a place to capture your fleeting thoughts and ideas, and it allows you to hit-the-ground-running on projects. ResearchMaster was developed with professional scientific research in mind, but it's great for grocery lists and address books, as well.
Through the application interface the user creates, interacts with, and otherwise manages collections of records. Records hold a section called Notes, a section called Meta Info, one called BibTeX Info, and another section called Flash Cards. Much of the time you will likely have an Associated Media file corresponding to a record (optional). You can configure your own file-type handlers to quickly launch associated media files in your prefered application. Recommended usage is to use the Add Time Stamp To Notes button when adding new notes to a record so that the Chronology Builder feature can recursively re-assemble your various entries, across all records, in chronological order. You can also have the Bibliography Builder assemble a BibTeX-formatted bibliography file using the BibTeX information stored with each record. And each record can have an arbitrary number of LaTeX Flash Cards associated with it, which can be practiced through a flashcard session that includes flashcards from all records below a selected point in your collections hierarchy. Finally, each new record has a Membership list, and a single record can be a member of multiple collections.
Records & Collections
The application window is divided vertically into left and right parts. The tree widget on the left shows collections of records. The record is the fundamental object used throughout the application. A record typically has some associated media file, such as a PDF, in which case you can think of it as a record of your interaction with the file. When you create a new record you are given the opportunity to import an associated file, though the associated file can be added or deleted at any time. An actual record has four sections: Notes, Meta Info, Bibliography Info and Flash Cards, corresponding to the four tabs across the top of the right side of the application window. Selecting a record in the tree causes the four sections of the record to be loaded into the corresponding four editor tabs on the right side of the application. You can copy or move collections and records to new locations using the following keys: shift+ctrl+right-click+dragging to copy, ctrl+right-click+dragging to move.
Notes
The Notes section of each record is intended as a place for logging your time with respect to that record. On the toolbar is a button labeld "Time Stamp". Use this feature to add a timestamp each time you work with this record. Later you can use the Chronology Tool to chronologically sort all of you time-stamped entries, across all of your records (or some subset), and export the resulting list to a file. In this way you can retrace your own footsteps and account for your time. Note that each timestamp includes a separator, the default being "========================". This value is hard-coded in the file ResearchMaster/researchmaster.py (~line 72). It was not included in the Preferences tab simply because it was too wide and affected the appearance of the Preferences tab layout. The separator string is used by the Chronology Tool to identify individual note entries and should therefore remain constant throughout all of your ResearchMaster records. The Chronology Tool is accessed from the "Special Operations" menu of the left toolbar.
There are currently two keyboard actions recognized within the Notes panel (i.e. when the panel has focus): ctrl-f to launch a "find in record" dialog, and ctrl-s to save your record. Saving saves all four sections of a record regardless of which panel is currently showing.
Meta Info
The Meta Info section holds the membership information of each record. Each single record instance can be a member of multiple collections. Initially this will contain the single location at which the record was created. Membership to other collections can be accomplished either by shift+ctrl+right-click+dragging a record to an additional location, or manually adding new membership paths through the text-entry field on the Meta Info panel. If done manually, then you should save the record and refresh the collections tree to reflect changes. Important: Membership paths use "/" for all platforms, i.e. Windows, Linux and Mac.
The Meta Info section is also the place to manage a record's associated file. Using the Meta Operations menu on the right toolbar you can import, export and view the associated file. Importing amounts to copying a particular file into ResearchMaster's own file archive. Exporting copies the associated file to a place outside ResearchMaster's file archive, perhaps so you can email it somebody. Viewing will launch the file in the application of your choice, but you must first configure this behavior by associating a "handler" application with the particular file-type in the Preferences panel.
The "flagged" attribute in the Meta Info panel causes the record to be a member of the "*flagged" collection. It should have a value of either zero or one. The *flagged directory could be thought of as a "Favorites" list. You may be frequently accessing a deeply buried Record, in which case flagging it brings a link to it right at the top level...as you would expect. Likewise, an instance of a Record may show up in *orphans if a Record should ever develop an inconsistency in which it is to be a member of a non-existant collection. This could be caused by incorrect manual editing of the membership attribute. The *orphan feature prevents you from losing the Record altogether, and alerts you to the inconsistency.
The other fields of the Meta Info section (isbn, url, fsize (file size), callno (call number)) should be filled-in manually if desired. These fields are stand-alone and do not affect other parts of the record or collections hierarchy like the membership field, for example.
Bibliography Info
ResearchMaster is designed to be used with LaTeX and BibTeX. See the Leslie Lamport book for details about LaTeX and BibTeX. The following assumes that you are familiar with the LaTeX document formatting system. When you created a record you were prompted to enter a "citation_key". This becomes the name of your new record, and it can be anything you like. However, the term "citation_key" comes from LaTeX/BibTeX and does have special meaning in that context, in addition to merely the name of your record. In a LaTeX document that has a bibliography you reference bibliography items via their citation_key. The LaTeX system finds the citation_key in your .bib file and adjusts your reference numberings and citations accordingly.
BibTeX recognizes several differnt bibliography types (articles, books, proceedings, etc). Each type has a corresponding set of fields which are mandatory, as well as an optional set. You can configure these through the BibTeX Operations menu on the right toolbar. Be sure to completely specify all required fields. Later, when you wish to produce a BibTeX formatted bibliography file you can simply use the Bibliography Tool located under the Special Operations menu on the left toolbar of the application. This will prompt you for an output filename and location. Your file should have a ".bib" extension to be compatible with the LaTeX/BibTeX system. The Bibliography Tool will then generate a bibliography recursively from the selected point within your collections hierarchy.
Flashcards
Each Record has a list of Flashcards. This may not be relevant in many instances, but keeping in mind ResearchMaster's originally intended functionality -- ie. a research tool -- it made sense to include an optional list of Flashcards with each Record. Previously I had developed an application called "LaTeX Flaschcard System", which resulted in a hierarchy of collections that mirrored my ResearchMaster collections, and in many cases there was a direct correspondence between a set of flashcards and a collection of ResearchMaster records. So much that it eventually dawned on me to merge the LaTeX Flashcard System's functionality into ResearchMaster as it currently is. This had the added benefit that the LaTeX Flashcard System would now be implemented in Python (previously it was C++). Another motivation was the existing BibTeX support in ResearchMaster. There is currently no real connection between the LaTeX of the Flashcards and the BibTeX info of the same record, but it amounts to two reasons to have a proper LaTeX implementation on your system -- ie. if you're planning to use ResearchMaster.
To create a flashcard simply load the corresponding record, then go to the record's Flash Card panel and give it a name and content. The Front and Back can contain any valid LaTeX. For math I generally just use $$ between the dollar signs as it is most efficient. Again, if you are already familiar with LaTeX then these things are hopefully intuitive. You can preview without saving, although you can just as easily save and delete a flashcard you don't wish to keep. Either way. Of course you can just type plain English (or other) and not worry about LaTeX special characters; what you enter in the text areas is wrapped with a LaTeX flashcard style-sheet, so knowledge of LaTeX is not essential. A functioning LaTeX system, however, is necessary, as the application makes system calls to the gs program (GhostScript) and the LaTeX compiler, as well. Actually, the order is 1) LaTeX to produce a DVI (Device Independent file), then 2) GhostScript to produce a .png image of both the front and back. Everything is done on the fly.
Offsets: If the front and back images of your flashcard are not aligned properly in the flashcard viewer when you go to view them, then you can adjust the x and y offsets from the Preferences panel on the left side of the application. These variables are FLASHCARD_X_OFFSET and FLASHCARD_Y_OFFSET. If running on Windows, then notice that there are special variables with a "_WIN" for Windows. This was done so that the application could have proper default offsets for both Linux/Mac and Windows without need for configuration. LaTeX implementations differ, however, so these value can be manually adjusted if the defaults don't look right on your system. For example, different versions of Windows appear to give different results. The defaults provided were tested with Windows 7.
On Windows there is an additional variable used by the Flash Card system: GS_EXE. This is the name of the ghostscript executable on your system. If you followed the installation instructions and installed the recommended Ghostscript package then this will have the value: "gswin32", and the default should work fine. But if you need to change it you can.
You can have as many flashcards per record as you like. You can launch a flashcard session using all flashcards from all records below your current-selected point in the collections hierarchy with the "Recursive Flashcard Session" function found under "Special Operations" on the left toolbar.
Base Directory & Configuration File
ResearchMaster stores it's information in a special directory. By default this directory is created under the user's $HOME directory and named ".researchmaster". Note the leading dot! It is referred to internally as the BASE_DIR. You can tell ResearchMaster to use a different BASE_DIR by selecting "Change Base Directory" from the Tree Operations menu on the left toolbar. This assumes that the new directory contains the sub-directories that ResearchMaster expects, namely records, files and collections directories. You can see which paths ResearchMaster is using by looking at the "Paths" tab on the left side of the application.
There are 2 particularly important sub-directories under the BASE_DIR: "records" and "collections". When you create a collection in ResearchMaster it shows up as a directory of the tree widget on the left panel. There is also a corresponding directory created under the "collections" directory (ie. $HOME/.researchmaster/collections/.../SomeProject"). Collections created under "SomeProject" create further directories on your disk, but records created under any given directory are NOT stored under "collections", as you might think, but rather dumped into the one-level-deep "records" directory. This allows a single record to be included in multiple Collections, and explains why ResearchMaster can take a while starting up -- i.e. because it has to look at each record and determine which collection(s) it belongs to, then attach them to the ResearchMaster collections tree widget at the appropriate place. Whether this one-to-many functionality is useful to you will depend.
The other configuration file used by ResearchMaster, which is also located in the user's $HOME directory, is called ".researchmaster_config". This is located outside of the .researchmaster BASE_DIR so that the user can change BASE_DIR and still keep the same configuration. The syntax of the .researchmaster_config file is that of a simple python dictionary structure, i.e. key:value pairs. You can edit this manually, if desired, but syntax errors introduced through manual editing will likely cause problems (i.e. possible crash at startup) until fixed.
Preferences Panel
The Preferences Panel is accessed by clicking the Preferences tab, located at the top-left of the application window. Currently the Preferences Panel is editable by hand. This will change in the next release. For now, please edit carefully. You may need to change the flashcard offset fields depending on your platform. The defaults were tested on several Linux variants and Windows 7 as well as XP.
File handlers can be configured either manually, or with the help of the ".abc associations" tool at the top of the Preferences panel. File handlers are the applications that "handle" the opening of your associated files in your prefered application. ResearchMaster uses the convention that the key (i.e. of key:value config pairs) for handlers has the prefix "HANDLER_". You can have one handler with no file-type suffix, i.e. "HANDLER_", which will serve as your default application for all file-types not otherwise specified. Thus, to launch an associated PDF file in Adobe Acrobat, you should enter ".pdf" in the textarea of the ".abc associations" tool and select the application (i.e. Adobe Acrobat) using the "Select Application" button in the same tool. Your new addition will show-up immediately, but will not be saved until you press the "Save" button at the bottom of the Preferences Panel. Alternatively, you could edit your configuration by hand, using the "Save" button when finished. Pressing the "Save" button in the Preferences panel causes the configuration to be written to $HOME/.researchmaster_config.
Archiving Collections
On the left toolbar is the Archive Operations menu. This allows you to import and export archived collections. This feature has not been extensively tested, so use with some caution (i.e. make back-ups!). The archive feature may be useful if you have a large collection of materials that you no longer wish to see, but wish to save nonetheless.
Exporting an archive causes ResearchMaster to bundle the directory structure and associated records into a .tgz archive (Linux/Mac) or .zip archive (Windows). The archived files are stored in BASE_DIR/archives. Importing an archive simply unzips the selected archive back-into the collections hierarchy.
Installation and Dependencies
ResearchMaster is built from wxPython components, and thus wxPython (www.wxpython.org) needs to be present on your system for anything to work. All major Linux distributions offer wxPython through their various package management systems. Windows users should install wxPython according to the directions on the wxPython website.
A working LaTeX document formatting system is also required if you want to use either the Bibliography Tool or to create LaTeX Flash Cards. Please see the INSTALL file for details of installing these on various platforms. ResearchMaster has not been tested on Mac, but should work according to Linux instructions as Mac is now Linux underneathe. If you have ResearchMaster working on a Mac then please take a moment to send your feedback (ccosse@gmail.com), i.e. whether it works, what problems you had, anything else.
About Asymptopia Software
Asymptopia Software is a one man band (http://en.wikipedia.org/wiki/One_man_band) that was started in 2001 with the introduction of TuxMathScrabble. Other games followed as I attempted to supplement my childrens' education. Throughout the last decade I have studied my own children and experimented with various ways to get them to learn. Many of the insights thus obtained have been fed back into the software for the benefit of future generations. I have one unreleased prototype, in particular, that would revolutionize education, but which awaits a venture capitalist.
This project, ResearchMaster, was written for myself while finishing my Ph.D. in Particle Astrophysics (finished 2004!) and working full-time as a research physicist, on-the-side. Initially it was a JPython (Java + Python) application called "Glossary Tool", then it got rewritten using wxWidgets, rather than Java-Swing widgets, and was renamed to "LibMaster" ... and there was an experimental phase to incorporate voice recognition that was named "RunningLog" ... and then I believe it was "BibMaster" ... and finally a slightly smarter sounding name: ResearchMaster.
The various applications available on www.asymptpoia.org have been a pleasure to build and to use. Feedback is always welcome, as are code contributions of any kind. If you have questions or need support, please don't hesitate to contact me: ccosse@gmail.com.
Until then, all-the-best!
Charles B. Cossé
