The practice of experimental academic research has recently gotten much more complicated because of the advent of computers and automation. Physical handwritten laboratory notebooks are no longer adequate to hold our gigantic data files. Both data and analysis are rife with errors. Datacollect2 is a tool to help us work more consistenly, reduce errors, and automatically record the structure of our experiments along with our results and our data. A companion tool, processtrak helps define consistent and repeatable analysis processes, and a separate companion package databrowse provides a web-based interface to data repositories.
The idea of Datacollect2 is to take those procedures that we follow on a routine basis -- the typical steps in whatever we do -- and formalize them into computerized checklists. Controls to command and query electronic instrumentation are integrated into the checklist steps, making performing the checklists very efficient. The checklists then become the basis for creating (automatically, of course) an experiment log that combines electronic readouts with manual inputs, photographs, etc. The experiment log and checklists create a cross-linked, navigable record of the experiment.
The laboratory records of many scientists are a mess of handwritten or electronic notes and large numbers of badly organized data files and folders. Datacollect2 can help record the natural structure of the experiment in a cross-linked form that makes it discoverable. The computerized checklists, rather than being "paperwork", make laboratory data collection more efficient: Integration with instrumentation puts controls right where you need them, and the well-defined processes help reduce errors and waste.
The use of checklists in other industries such as aerospace and medicine has dramatically reduced rates of errors in those fields. Recording the filled checklists keeps a record of what was done, and integration with electronic instrumentation allows some data to be directly extracted from its source, reducing the opportunity for transcription errors. When desired, the overall plan for an experiment or sequence of experiments can itself be represented in a checklist, helping to provide further context (and providing a concrete outlet for experiment planning).
Datacollect2 is a system for checklist-based experiment logging -- it is a tool for recording what you are doing and what you have done. Datacollect2 is not a tool for creating sophisticated integrated experiment control and data acquisition systems ("virtual instruments"): Other tools such as Dataguzzler and LabView are far more suited to that task. Datacollect2 is a tool suited to recording your use of virtual instruments, especially if the virtual instruments provide a programmatic interface that can be used to accept commands from and transmit output to Datacollect2. (Note: As of this writing, a general-purpose Datacollect2 interface for Dataguzzler does exist, but no such interface has yet been developed for LabView.
Datacollect2 is built on open Web standards such as XML, XLink, and the idea of the URL as a form of cross-reference. Experiment logs and checklists are stored in XML text files, which has unique advantages in being extensible and both human- and machine-readable. XLink provides a standardized way to define a cross-reference in XML, such as from an experiment log to a checklist. The fact that XLink is standardized makes the cross-reference discoverable using automated tools.
Datacollect2 helps you create discoverable experiment logs, cross-linked with checklists and data files, but the structure is not very useful without a way to look at those experiment logs and navigate the structure. The separate companion package databrowse is a plug-in for web-server software that creates a navigable and configurable online representation of your data repository, with the ability to browse checklists and experiment logs, follow cross links, and drill down into data files. It is extendable via custom plug-ins to be able to analyze any type of data file.
An internal library within Datacollect2, xmldoc provides a programmatic interface for extracting tabular data from experiment logs. An internal class library dc_value provides representations of numbers with physical units, cross-references, and more. The processing tool, processtrak, is distributed along with Datacollect2. It provides a framework for defining data analysis and processing steps while keeping the intermediate results well-organized.
The basic idea of processtrak is that you define analysis and processing steps which transform the original experiment log (.xlg file) into a processed experiment log (.xlp file). The processed experiment log starts out identical to the original experiment log, which is never modified. Each processing step then operates on the processed log, adding additional information, perhaps generating processed data files from the originals. Processing steps can be rerun as needed and during debugging. processtrak uses provenance tracking to help verify consistency of the generated output.
See the file INSTALL.txt distributed with Limatix.
For a simple demonstration of Datacollect2 capabilities, copy the demonstration files into a new directory:
To start, run the datacollect2 program:
This is the main experiment log window. It provides a place to view
or update various parameters that are synchronized to the experiment log:
The current measurement number index (Measnum), the specimen ID (Specimen)s,
who is performing the experiment (Perfby), and the date or dates during which the experiment was performed. It also provides fields to record
the goal of your experiment, an automatically populated list
of photographs, and a field to record notes.
Use the File menu: File...New to create a new experiment log in the same directory where you placed the above-listed files. You will be asked whether the experiment will involve a single specimen or multiple specimens. Select "Multiple specimen" for now.
This experiment requires additional measurement fields, beyond those built into datacollect2. You need to load in a configuration file to define those fields. From the File... menu select "Load Custom Config" and browse to your copy of thermalconductivity.dcc.
Start by viewing the parameters: From the "Gui" menu
select "Open paramdb editor" to see a table of currently available
parameters:
The table lists each parameter, its current value, the default units for that parameter (for numeric parameters), the value type, and the controller
in charge of the parameter.
Try editing the "specimen" parameter by clicking on its value field. Note that once you tab or carriage-return out of editing the text, the "specimen" field of the main experiment log window changes to match. This is because the two fields (in the paramdb editor and in the experiment log window) both refer to the same underlying parameter, and thus they remain synchronized.
If you do not tab- or carriage-return out of editing the field it will remain colored yellow, which indicates that it is out of sync with the underlying parameter. You can press "Esc" to cancel your change. Always be sure fields are colored gray or green, indicating that the change was successful!
Look at the 'Controller' column of the paramdb editor and notice that the "Specimen" parameter uses the 'synced' controller. That means the specimen parameter is (or can be) synchronized with a file. The controller of a parameter mediates (or delegates mediation) of requests to change its value. Some controllers can be used to make parameters that represent the internal settings of connected laboratory instruments.
Without exiting from datacollect, open your experiment log using
a text editor:
Note that
the specimen ID you entered is shown in the <dc:specimen>
tag. The experiment log is constantly updated as you change
'synced' parameters. Now change the specimen ID using your text
editor and save the file (it is a good idea to quit the text
editor as well). Datacollect will not notice the change until
it rereads the file, usually because you have done something
else, such as changing another 'synced' parameter that requires
resyncing with the file. So type something into the 'notes'
field and press 'tab' to confirm your change, and you will see
your manual edit to the experiment log file reflected in the
"Specimen" field alongside your new update to the 'notes' field!
One of the things that is very powerful about datacollect is that you can do manual editing on-the-fly to go back and correct mistakes or make changes to the experiment log that might not be directly possible through the user interface. (Only the experiment log is fully synchronized like this; be sure to close plan files and checklists before editing them with external tools)
Go to the Plan menu... Open and select "thermalconductivity_crossply_meas.plx". This opens up the test plan you copied in earlier. Try clicking the "Open thermalconductivity_prep.chx" button. It won't let you because it won't let you open a sub-checklist until this checklist has a name (that's to give you a chance to set parameters that might affect the file name). Checklists don't get names until a box has been checked. So in this case, just check and uncheck a box on the right-hand side. That assigns this checklist a name and saves the filled copy on disk. You can browse it with a text editor as "thermalconductivity_crossply_meas.plf". Unlike the experiment log, it is NOT safe to edit a filled checklist in a text editor while it is open in datacollect (just close the checklist, and reopen it when you are done editing).
Click the "Open thermalconductivity_prep.chx" button. Note that the status next to that changes to "1 start/0 done" (You can use the status pulldown to bring up this particular checklist).
The thermalconductivity_prep.chx checklist is a "measurement checklist". That means the button at the bottom is "Finish and save measurement" rather than "Done", and when you click the "Finish and save measurement" button, a new measurement (with snapshots of all parameters) is saved to the experiment log.
When filling out this checklist, be sure to enter the specimen ID and press return before any box is checked. Enter something into the specimen ID field, press return, and then check that first box. Checking the first box gives the checklist a name. The window title will change to the new name of the checklist and its name includes the specimen ID (That is why you had to be careful to enter the specimen ID first). The filled checklist name also begins with the measurement number ("Measnum" box). The measurement number increments every time a measurement is saved.
The specimen id was included in the filled checklist name because the checklist has a special XML tag that tells it how to name the filled checklist: <dest autofilename="concat('thermalconductivity_prep_',dc:paramdb('specimen'),'.chf')"/>
In any case, check off the items in the checklist as if you were performing the experiment. Enter '.2 m' in the specimen length field, and notice how it automatically converts your input from meters into millimeters. That is because the field units were specified as mm in the .dcc configuration file.
When done, type some notes into the "Notes" field, being sure to press <tab> after typing. Then press the "Finish and save measurement" button.
When you press the "Finish and save measurement" button at the bottom of a measurement checklist, datacollect will both mark the checklist as "done" and add a measurement to the experiment log. The measurement will be represented by a <dc:measurement> tag in the experiment log containing the current set of parameter values from the parameter database (except for parameters configured with the hide_from_meas flag set):
<dc:measurement> <dc:measnum>1</dc:measnum> <dc:recordmeastimestamp>2016-03-23T23:27:26-05:00</dc:recordmeastimestamp> <chx:clinfo>testlist_V1._3/23/16</chx:clinfo> <chx:cltitle>Test checklist</chx:cltitle> <dc:specimen>S02-AA-19</dc:specimen> <dc:hostname>gavroche</dc:hostname> <dc:measphotos/> <dc:measchecklist xlink:href="2016-03-23_files/0000-thermalconductivity_prep_S02-AA-19.chf"/> <dc:date>2016-03-23</dc:date> <dc:perfby></dc:perfby> <dc:notes></dc:notes> </dc:measurement>The measurement entry in the experiment log always stores the parameter values from the instant the "Finish and save measurement" button was pressed. The experiment log also gets (in the <dc:measchecklist> tag) a hyperlink to the filled checklist. Individual parameter values from steps marked as <intermediate/> are captured when the step was checked and stored in the filled checklist. The value for the same parameter stored in the experiment log will be different if the parameter changed value between when the step was checked and when the "Finish and save measurement" button was pressed.
Notice also that datacollect has automatically created a "_files" directory to store files from this experiment. This directory is where it will put filled-out checklists, and if you have data files from other software, this directory is probably where you should put them.
You can perform additional measurements (in this case prepare more samples) either by hitting the "Reset" button at the bottom of the completed checklist or by pressing the "Open thermalconductivity_prep.chx" button in the plan (don't click the 'Switch to Read/Write' button at the top; that will attempt to reload your newly completed checklist, and require synchronization of the parameters shown at the top, including Measnum, which has just incremented). Notice that when press the "Reset" or "Open" buttons, the status shown in the plan updates. You could also go back to the main datacollect experiment log window and select "Open custom checklist" from the "Checklist" menu, but that would not link the new checklist to the plan, so it is usually best avoided.
Checklists and plans are generally treated similarly by datacollect and have identical file formats and structures. They are just listed separately because they are conceptually different. A checklist is for a routine process that may well be performed repetitively. A plan is an intended series of tasks and is usually custom written or modified for the particular task at hand.
When opening checklists you have the option of using the regular "Open" option (for standard or centrally-located checklists) or the "Open custom checklist" option. These options are the same except for how the original checklist is cross-referenced: In the case of the regular "Open" option the cross-reference is an absolute reference. In the case of the custom option, the cross-reference is a relative link to a file that is presumed to be stored relative to your data directory. So with the custom option, if you move the data tree around, since the custom checklist is presumably stored alongside the data the cross reference will still work after the data tree is moved. With the regular "Open" option the assumption is that the standard or centrally located checklist won't move with the data so an absolute reference is necessary.
Unfilled checklists use the ".chx" filename extension (CHecklistXml). Filled checklists use the ".chf" extension (ChecklistFilled). Similarly, unfilled plans use the ".plx" extension (PLanXml) and filled plans use the ".plf" extension (PLanFilled).
Checklists and plans can use special kinds of steps. The example plan uses a special kind of step "runchecklist" to support opening the "thermalconductivity_prep.chx" and "thermalconductivity_meas.chx" checklists. Likewise the "thermalconductivity_prep.chx" uses a "dc_param" step to provide the specimen entry box at the top and the specimen length box farther down. The "thermalconductivity_meas.chx" also uses a "hrefbutton" step to give you a way to reference a saved data file.
In most cases, parameters are saved to the experiment log when you press the "Save Measurement" button, and are not saved to the checklist. When you revisit an old checklist you will see the current parameter values (since the widgets are active and connected to the parameter database), not the historical parameter values from when the checklist was completed. This is because the design intent of datacollect is to snapshot the current parameter values when you press the 'save measurement' button, and because values in the experiment log will be easier to access than values buried in a checklist.
Nevertheless, sometimes you want to store an intermediate parameter value in a checklist, before saving the entire measurement. Storing an intermediate is indeed possible and will result in different behavior: The entry box for the parameter will track the parameter database only when the step is unchecked. When the step is checked, the displayed value is fixed and stored into the filled checklist, and the entry box is grayed out. Intermediate parameter storage mode is enabled by adding a <chx:intermediate/> element to the <chx:checkitem> element for the checklist step. Marking an checklist parameter step as intermediate does not prevent the parameter from being saved to the experiment log (use the hide_from_meas parameter on creation in the .dcc file to accomplish that), not does it ensure that the value saved to the experiment log and the value from the checklist are the same. If the parameter is changed between checking the checklist box and saving the measurement to the experiment log, then the stored values will be different!
The doc/processtrak_example directory includes a complete example of the use of ProcessTrak for data analysis. Thanks to Joseph Hynek for providing the data and for his permission to share the data.
It is from an RF (radio frequency) survey of the Creston, IA area. The bulk data files are in the creston_jan2016/ subdirectory. RF spectrum data was captured from a vehicle and stored in .csv format. Simultaneously, GPS tracking data was captured using a cellphone. The two datasets are merged to create geographic maps of estimated RF intensity at different frequencies.
You can adjust the comments in the process_spectrum.prx file to use either the creston_jan2016.xlg experiment log file as input or the creston_jan2016.xls spreadsheet file as input. To use the spreadsheet file you will need to have the xlrd Python package installed.
A ProcessTrak process consists of a series of steps that operate on experiment logs. In this case, there are six steps listed in the process_spectrum.prx file:
| Step | Description |
|---|---|
| copyinput | (this step is always implicitly present, and copies the experiment log to the processed experiment log.) |
| extract_rflog_entries | Extract data from the rflog csv files into the XML experiment log |
| combine_freqband_lines | Merge adjacent spectrum entries for different frequency subbands into a merged spectrum covering the entire frequency band of interest |
| mergegps | Merge in GPS data by aligning times. |
| energymap | Generate .png images of RF energy at different frequencies using matplotlib. Also create .kml (Google Earth) files for rendering these images as geographic overlays. |
| generatespreadsheet | Generate a summary spreadsheet listing the frequencies, .png images, and .kml overlays. |
ProcessTrak currently runs from the command line shell. Start in the example directory and run processtrak process_spectrum.prx --steps. This will list the available steps:
List of steps for -s option --------------------------- copyinput (WILL OVERWRITE CURRENT OUTPUT) extract_rflog_entries combine_freqband_lines mergegps energymap generatespreadsheet
First, run the copyinput step: processtrak process_spectrum.prx -s copyinput. This copies the input file (either creston_jan2016.xls or creston_jan2016.xlg, depending on which is commented out in the .prx file) to creston_jan2016.xlp, the processed experiment log:
<?xml version='1.0' encoding='UTF-8'?> <dc:experiment xmlns:prx="http://limatix.org/processtrak/processinginstructions" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:ls="http://limatix.org/spreadsheet" xmlns:lip="http://limatix.org/provenance" xmlns:dcv="http://limatix.org/dcvalue" xmlns:dc="http://limatix.org/datacollect" xmlns:pt="http://limatix.org/processtrak" lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"> <dc:summary lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"> <dc:dest xlink:href="creston_jan2016/" lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"/> </dc:summary> <dc:measurement lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"> <dc:rflog xlink:href="creston_jan2016/creston_rf1.csv" lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"/> </dc:measurement> ... <dc:measurement lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"> <dc:gpslog xlink:href="creston_jan2016/Creston8.gpx" lip:wasgeneratedby="uuid=db7cf5e5ab34f14132979bd1eace790b3c7eff76;"/> </dc:measurement> <lip:process uuid="4f8ff3651f8e075155a221db7fd9f66a89e1e50c"> <lip:wascontrolledby> <lip:prxfile xlink:href="process_spectrum.prx" xlink:type="simple" warnlevel="info" type="href" mtime="2016-07-11T18:07:02.099510+00:00" lip:timestamp="2016-07-11T18:07:02.099510+00:00"/> </lip:wascontrolledby> <lip:starttimestamp>2016-07-11T17:07:34.416009-05:00</lip:starttimestamp> <lip:hostname pid="7780" uid="1667" username="sdh4">thermal.cnde.iastate.edu</lip:hostname> <lip:argv>['/usr/bin/processtrak', 'process_spectrum.prx', '-s', 'copyinput']</lip:argv> <lip:inputfile xlink:href="creston_jan2016.xlg" xlink:type="simple"/> <lip:target xlink:href="" xlink:type="simple"/> <lip:process uuid="db7cf5e5ab34f14132979bd1eace790b3c7eff76"> <lip:used xlink:href="creston_jan2016.xlg" xlink:type="simple" warnlevel="warning" type="href" mtime="2016-07-11T21:45:06.136009+00:00"/> <lip:action>copyinput</lip:action> <lip:starttimestamp>2016-07-11T17:07:34.417219-05:00</lip:starttimestamp> <lip:finishtimestamp>2016-07-11T17:07:34.427022-05:00</lip:finishtimestamp> </lip:process> <lip:finishtimestamp>2016-07-11T17:07:34.428232-05:00</lip:finishtimestamp> </lip:process> </dc:experiment>
The processed experiment log looks intimidating with lots of complicated numbers, but most of that is just the provenance, history, and cross-references used to implement traceability: Being able to identify where your outputs came from.
In particular, note the <dc:dest> indicating where to store output. files and a series of <dc:measurement> tags with rflog and gpslog content that correspond to the input experiment log. Also look at the <lip:process> section at the bottom. This section stores a record of the copyinputoperation, including what inputs were used, what the parameters were, etc. Within the main <lip:process> there is a sub-<lip:process> with (in the above case) a uuid= attribute (universally-unique identifier) starting with "db7c". The various tags above have a lip:wasgeneratedby= attribute that refers to this same uuid. That is ProcessTrak's record of where those tags came from.
Now run the remaining steps in sequence and watch the file grow. The extract_rflog_entries step adds a bunch of <spectrumlog> tags. The combine_freqband_lines step adds <mergedspectrumlog> tags that combine information from multiple <spectrumlog> tags. Notice how additional <lip:process> tags are generated for each of these steps.
Now is a good time to look at process_spectrum.prx in more depth. AT the top, the input files are specified. Then with <elementmatch> and <inputfilematch>, default constraints for which elements and which files to operate on. Then a series of steps, with parameters supplied as needed, and with links to the Python scripts for executing those steps.
ProcessTrak provide two tools: pt_checkprovenance and pt_cleanup to help keep your processed results neat and tidy, and to verify consistency. Try running pt_checkprovenance on creston_jan2016.xlp. This tool walks the provenance graph (the lip:wasgeneratedby and lip:used references) to determine if there are any errors or inconsistencies in the generated output. It should pass without warnings or errors. Now rerun an earlier step without rerunning the later step, and rerun pt_checkprovenance. It will give errors. You can see the details of the errors by adding the "-v" option. If you rerun the later steps in order and return pt_checkprovenance you will find the errors have cleared. The pt_checkprovenance tool is very useful in making sure your output is consistent and all steps have been rerun as needed.
Now try running mergegps twice. The fact that you have run a step twice means that there is excess information in the processed experiment log about the extra run, and perhaps excess or obsolete data that shouldn't be there anymore. The pt_cleanup tool will remove this and other unneeded, obsolete information. Try: pt_cleanup process_spectrum.prx -h To remove obsolete elements from the processed experiment log, use the "-b" option (there shouldn't be any in this case). You should be able to clean up excess provenance (excess <lip:process> tags) from the experiment log with the "-p" option. You can also use this tool to clean out the destination directly with the "-d" option.
Be careful using the pt_cleanup "-d" option to clean out the destination directory. It will ask you before it deletes anything, but it will want to delete anything it can't find a reference to. So if your destination directory is not a sub-directory or if you have manually added files to it, or if there are outputs that were never recorded in the experiment log, it might identify these for deletion.
If you want to cleanup generated files from the destination directory, reset the experiment log by running the copyinput step (this completely empties the experiment log). Then use pt_cleanup with the "-d" option and it will offer to delete all of the processing outputs.
The net result of using ProcessTrak is the ability to manage complicated multi-step processes while minimizing the need to re-run steps. Outputs are kept in a centralized location, with tools to cleanup obsolete results (pt_cleanup) and verify tracability of your results through the processing chain (pt_checkprovenance).
The most fundamental building block of Datacollect2 is XML, which is a data model usually represented as text with opening and closing tags in brackets, similar to mid-1990's HTML. Here is a very simple experiment log:
<?xml version='1.0' encoding='UTF-8'?> <dc:experiment xmlns:dc="http://limatix.org/datacollect" xmlns:xlink="http://www.w3.org/1999/xlink"> <dc:summary> <dc:specimen>A53-1394Q</dc:specimen> <dc:perfby>Holland</dc:perfby> <dc:date>2016-03-01</dc:date> <dc:dest xlink:href="A53-1394Q_test_files/"/> <dc:measnum>1</dc:measnum> <!-- This is a comment --> <dc:checklists/> </dc:summary> </dc:experiment>
The first line (optional) marks this file as XML. The basic component of XML is the element, for example <dc:date>2016-03-01</dc:date> which is defined by opening and closing tags, <dc:date> and </dc:date> respectively, and whatever is enclosed by those tags. The structure is hierarchical: The <dc:summary> element contains the <dc:specimen>, <dc:perfby>, <dc:dest>, <dc:measnum>, and <dc:checklists> tags. The <dc:dest> tag has an attribute, xlink:href with value A53-1394Q_test_files/ representing the relative URL of an XLink cross linked directory (folder).
All opening tags (no leading slash) must have corresponding closing tags (with leading slash). The exception is illustrated in the <dc:checklists> tag, above. The form with a trailing slash <dc:checklists/> is a shorthand for the opening tag immediately followed by the closing tag, with no content in between.
An XML document must have a single root element, in this case the <dc:experiment> element on the second, third, and last lines. (XML structures that do not have a single root are known as fragments.) The <dc:experiment> tag on the second and third lines has two namespace declarations that look like attributes. They define what namespaces are referred to by the dc: and xlink:. While the namespace values look like URLs, the URLs are never accessed directly, just used as unique identifiers.  Within that definition, a <checkitem> tag would be interpreted in the http://limatix.org/checklist namespace even though it doesn't have a prefix.
A segment of text in an XML document is known as a text node. Text nodes, elements, comments, and processing instructions (which we will not discuss in detail) are collectively known as nodes
An attribute named xlink:href (i.e. named href in the http://www.w3.org/1999/xlink namespace) is the XLink standard way of denoting a cross reference. XLink defines other possible attributes as well, such as xlink:arcrole, which is used to specify how the cross reference should be interpreted. For example, within Datacollect2 we use an xlink:arcrole of http://limatix.org/linktoparent to represent a reverse cross reference to the parent of a document.
Because the attribute names and namespace for XLink attributes are unique, the structure of cross-references can be discovered simply for searching for those attributes, without otherwise needing to understand the particular XML documents being searched themselves. XLink cross references are URLs, not filenames; they always use forward slash ('/') to refer to subdirectories or subfolders, never back slash ('\'), regardless of platform. The parent directory/parent folder can be referenced with '..'. XLink cross references can be relative (no transport protocol such as http:// and no leading slash), server- or filesystem-absolute (with leading slash), or world-absolute (full URL with transport protocol). Please note that while the Datacollect2 libraries will correctly manipulate world-absolute URLs, the current version is limited to accessing local files, typically by realtive URLs.
In processing an experiment log, it is often necessary to refer to a particular element within an XML file. This can be done by specifying its XPath. For example, in the above XML file, the <dc:perfby> element could be identifed by the absolute XPath /dc:experiment/dc:summary/dc:perfby. XPaths can also be specified as relative to a particular context node, which defaults to the root element (in this case the <dc:experiment> tag). As a relative path from the default context node, the path to the <dc:perfby> element would be specified as dc:summary/dc:perfby. The context node itself can always be referenced with a single period ("."). A parent element can be referenced with a double period (".."). For example, relative to the <dc:perfby> element as context node, the path to the <dc:summary> element would be ".." and the path to the <dc:experiment> element would be "../..".
An XPath like dc:summary/dc:perfby would match multiple elements if, for example, there were multiple <dc:summary> and/or multiple <dc:perfby> tags present. dc:summary/dc:perfby[1] would return the first dc:perfby element within each dc:summary element. More sophisticated constraints are also possible. For example to match a dc:measurement element containing a dc:measnum element with the particular value 5, use dc:measurement[dc:measnum='5']. XPaths can also refer to attributes by referring to them with a leading at sign ("@"). For example in the above XML example the cross reference would be identified with dc:summary/dc:dest/@xlink:href. Note that namespace prefixes (dc: and xlink: in this case) are always needed when referring to namespaced elements, even when a default namespace has been set (with xmlns=..., as described above).
The experiment log (.xlg) is intended as a record of what was done in a particular experiment. It includes both summary information and a sequence of measurements. Datacollect stores the experiment log as an XML file. Here is an example experiment log:
<?xml version='1.0' encoding='UTF-8'?> <dc:experiment xmlns:dc="http://limatix.org/datacollect" xmlns:xlink="http://www.w3.org/1999/xlink"> <dc:summary> <dc:specimen>A53-1394Q</dc:specimen> <dc:perfby>Holland</dc:perfby> <dc:date>2016-03-01</dc:date> <dc:dest xlink:href="A53-1394Q_test_files/"/> <dc:measnum>3</dc:measnum> <!-- This is a comment --> <dc:checklists> <dc:checklist xlink:href="A53-1394Q_test_files/voltagemeas_1.chf"/> <dc:checklist xlink:href="A53-1394Q_test_files/voltagemeas_2.chf"/> </dc:checklists> </dc:summary> <dc:measurement> <dc:measnum>1</dc:measnum> <dc:measchecklist xlink:href="A53-1394Q_test_files/voltagemeas_1.chf"/> <dc:voltage dcv:units="Volts">23.2</dc:voltage> </dc:measurement> <dc:measurement> <dc:measnum>2</dc:measnum> <dc:measchecklist xlink:href="A53-1394Q_test_files/voltagemeas_2.chf"/> <dc:voltage dcv:units="Volts">41.1</dc:voltage> </dc:measurement> </dc:experiment>
The <dc:experiment> element represents the entire experiment (sequence of measurements). It consists of summary data (the <dc:summary> element) which specifies parameters that are (nominally, at least) common to the entire experiment:
Saving the measurement adds a <dc:measurement> tag to the experiment log, stores snapshots values from all parameter database entries that did not have hide_from_meas=True specified, copies any autoexp elements automatically run experiments from the measurement checklist, increments measnum, and resets values of all parameter database entries which were configured with reset_with_meas_record=True.
The experiment log can be manually edited using an external text editor at any time. Datacollect2 synchronizes access to the experiment log using Python's fcntl.flock() on UNIX/Linux platforms or LockFileEx() on NT platforms. If you are using a text editor that may ignore such locking, avoid saving the experiment log while simultaneously performing an action in datacollect. Also be sure to reload the latest version of the experiment log before making manual changes. Datacollect2 always attempts to intelligently merge manual changes with automatic changes to the experiment log, but occasionally there will be an error (such as malformed XML in the manually edited file) or a manual merge process will be needed. In this case a dialog box will be opened for you to select which changes to keep and/or perform a manual merge.
Datacollect is built on the idea of documenting processes through checklists. Checklists are represented as XML files corresponding to either blank (.chx) or filled (.chf) checklists. The checklist consists of some front matter followed by a sequence of steps:
<chx:checklist xmlns:chx="http://limatix.org/checklist" xmlns:xlink="http://www.w3.org/1999/xlink" filled="false" done="false" done_is_save_measurement="true"> <chx:clinfo>identification_and_version_of_this_checklist</chx:clinfo> <chx:cltitle>Title of this checklist</chx:cltitle> <chx:specimen>12-12345</chx:specimen> <chx:perfby>Holland</chx:perfby> <chx:dest autofilename="concat('measvoltage_',chx:specimen,'_',dc:paramdb('perfby'),'.chf')"/> <chx:checkitem title="Step 1 title"> <chx:description>Step 1 description goes here</chx:description> </chx:checkitem> <chx:checkitem class="textentry" title="Step 2 title"> <chx:description>Step 2 description goes here. Step 2 provides an entry for manual input.</chx:description> </chx:checkitem> <chx:initialtext> Initial text for the entry </chx:initialtext> <chx:width>40</chx:width> </chx:checklist>
Attributes within the main <chx:checklist> tag of the checklist specify whether this checklist is one that has been filled out (filled) and one that has been marked as "done" (done). A special attribute (done_is_save_measurement) specifies that the "Done" button normally at the bottom of the checklist should be replaced by a "Save measurement" button, and that selecting that button should record the current measurement to the experiment log.
Front matter parameters identify the checklist (<chx:clinfo>), specify a title (<chx:cltitle>), specify the specimen (<chx:specimen>), and specify who performed the work (<chx:perfby>). An additional parameter (<chx:dest>) can specify a default destination directory and/or provide attributes autofilename and/or autodcfilename that tell dc_checklist and datacollect how to name the filled checklist (see below for more information)
The checklist contains a sequence of <chx:checkitem> elements representing the steps in the checklist. The <chx:checkitem> element can have a title attribute that will specify the step title. It can also have a class attribute that specifies an alternative stepclass which gives the step extra functionality beyond the usual checkbox.
The <chx:checkitem> element usually contains a nested <chx:description> element that specifies the textual description of the step. The <chx:description> supports basic HTML-style markup. Additional elements can provide parameters for the stepclass. The second step of the above example uses a "textentry" stepclass which provides an entry box for filling a value into the checklist. It then provides additional parameters <chx:initialtext> and <chx:width> for the "textentry" step. Once filled, the entered value will appear as a <chx:text> element within the <chx:checkitem>. Documentation for the various possible steps is included in an appendix, below.
The <chx:dest> tag is used to supply information used in setting the filename for the filled checklist. When a checklist is filled out using dc_checklist or datacollect2, it is saved and given a filename as soon as possible -- usually once the first checkbox has been checked (the current version of the HTML/Javascript web interface does not save until the save button at the bottom is manually checked).
The <chx:dest> specifies three things: First, a default directory to store the filled checklist, via its xlink:href= attribute (i.e. a hypertext reference). This is primarily used by dc_checklist, and not by datacollect2. Second, a rule to determine the filename for the filled checklist, via its autofilename= attribute. Third, a rule specified as the autodcfilename= attribute that overrides the autofilename= attribute to determine the filename for the filled checklist when used in datacollect2.
The filename rules are given as XPath expressions, usually formed by concatenation, e.g.
concat('checklist_name','_',chx:specimen,'.chf')
The XPath expressions are evaluated in the context of the <chx:checklist> element, so they can refer to values that might be saved within the checklist. The above example extracts the specimen ID from the <chx:specimen> element of the checklist file to use in the name for the filled checklist.
Parameter database values are also available to the XPath expression via the custom XPath function dc:paramdb(). An alternative to the above that extracts the specimen ID directly from the parameter database rather than from the checklist file would be:
concat('checklist_name','_',dc:paramdb('specimen'),'.chf')
Note that if the checklist is a measurement checklist, the measurement number (measnum) will be automatically added prior to the extension. If the file already exists, an additional index number will be generated. Since the filename rules are passed as XML attributes, if you use double-quotes to delineate the the attribute value, be sure to use single quotes, as above, to delineate the XPath strings, as above.
Do not manually modify the on-disk copy of a filled checklist while datacollect or dc_checklist has it open. If you need to modify a checklist manually, close it completely. You can leave datacollect running; just reopen the checklist (from the list of checklists in the checklists menu) once you have saved your changes.
Plans are treated nearly identically to checklists. The primary difference is conceptual: A plan is usually custom-created for the experiment and run once or perhaps repeated a few times at most, whereas a checklist represents a standard practice.
The parameter database is Datacollect's internal representation of the current parameters of the measurement and experimental equipment. It includes both the summary parameters (stored within the dc:summary element of the experiment log) and the measurement parameters, which are stored each time a measurement is saved.
Each entry in the parameter database is configured with a data type (a value class from datacollect2.dc_value) and a particular controller. The controller is the arbiter of the parameter's value. Requests to change the value of the parameter go through the controller, which is free to delegate responsibility for example to external measurement hardware.
Within datacollect the menu item "Gui...Open paramdb editor" opens an interactive parameter database viewer and editor. You can also use the dc_glade external command to run a version of the glade GUI builder to create interactive control windows containing widgets that manipulate parameter database entries. When creating a GUI, be sure to name the top level window "guiwindow" and save as a GtkBuilder .glade file. Within Datacollect2 you can simply open from the menu item "Gui...Open".
Parameter database entries are configured in the datacollect configuration (.dcc) file using Python code as follows:
paramdb.addparam("paramname",valueclass)
The addparam() function also takes several optional keyword parameters:
| keyword | value |
|---|---|
| options | list of suggested possible values |
| defunits | default units for this parameter (numericunits and similar valueclasses only) |
| displayfmt | printf-style format string for printing this parameter (numeric valueclasses only) |
| hide_from_meas | True or False: Inhibit inclusion of this parameter in the <dc:measurement> element when a measurement is saved |
| reset_with_meas_record | True or False: Reset this parameter to blank after each measurement is recorded. This flag should generally be set for parameters which lose meaning between measurements, for example the name of the file storing the data from the current measurement. |
| dangerous | True or False: Setting this parameter is somehow potentially dangerous, so that it should be inhibited from being set automatically (e.g. when parameters are loaded from a file). |
| non_settable | True or False: Specify that this parameter is not generally settable by the user |
| save_extension | For parameters that support a save operation, the filename extension to use when saving. |
The parameter database can also be accessed externally using the DBus interprocess communication (IPC) library, if DBus support is correctly installed and configured. For example:
from limatix.dc_dbus_paramclient import dc_param from limatix.dc_dbus_paramclient import dc_requestval from limatix.dc_value import stringvalue # Read a parameter as a limatix.dc_value.value object paramval=dc_param("my_parameter_name") print(paramval) # Assign a parameter actualval=dc_requestval("my_parameter_name",stringvalue("parameter_value")) print(actualval)
Datacollect is most powerful when integrated with digital measurement instrumentation to automatically record measurement values and/or control the measurement process from within datacollect checklists. There are two methods for performing such integration:
We will discuss method 1 in more detail here. Method 2 is accomplished by creating a custom checklist step that contains and wraps your instrumentation widget. The process for creating custom checklist steps is described below in the appendix on extending datacollect2.
In trying to connect datacollect parameters to instrumentation, remember that Datacollect2 is not a tool for creating virtual instruments. In interfacing to complicated interconnected measurement hardware you usually need a separate abstraction layer representing the interconnected hardware in a coherent virtual instrument model. To most easily interoperate with Datacollect2, the virtual instrument model should:
If dataguzzler is used to create the virtual instrument model, then paramdb2.dgcontroller can be used to connect Datacollect parameters to dataguzzler parameters. Custom Datacollect2 widgets and custom checklist steps for controlling Dataguzzler are built in to Dataguzzler.
The challenge in interacting with instrumentation is that the instrumentation is often slow to respond and is rarely designed to handle control input from more than one source. Instrumentation code is much easier to write when it is single threaded, but to maintain reasonable interactive GUI performance it can't run in the same thread as the GUI.
The solution is to create a single-threaded class that represents your virtual instrument (or a portion of your virtual instrument) and then to wrap this class using datacollect2.threadserializedwrapper, which creates a separate thread to run the virtual instrument and dispatches method calls to that thread. The procedure for using threadserializedwrapper is as follows:
Within the datacollect configuration add each controllable parameter or measured value using paramdb.addparam(). Be sure to supply the correct datacollect2.dc_value.value subclass and other keyword parameters (see parameter database discussion, above). For the build= parameter, supply a lambda that uses paramdb2.threadserializedcontroller, e.g.
build=lambda param: paramdb2.threadserializedcontroller(param,virtual_instrument, virtual_instrument.get_emissivity, virtual_instrument.set_emissivity, pollms=2000.0))
You can alernatively supply a save() method as a saver= keyword parameter to threadserializedcontroller for a parameter that represents a saved data file.
ProcessTrak is a tool for defining step-by-step processing procedures for data analysis. It helps avoid the unbounded need for confusing arrays of intermediate files by storing as much information in a single processed experiment log that is updated by each processing step.
Processing steps can be written in Python. The sequence of steps is defined in a ".prx" (processing XML) file. Each step operates on a set of XML elements in the processed experiment log, selected by an XPath expression. Values from sub-elements from the experiment log can be passed automatically. See the example prx_example.prx for an illustration of the structure of a ".prx" file.
processtrak is currently run from the command line. processtrak prx_file.prx --steps will list the runnable steps. Then you can run a step with, for example, processtrak prx_file.prx -s first_step. The first time you execute a step, it will copy the original experiment log (.xlg) to a "processed experiment log" (.xlp). All further operations will be on the processed .xlp file so that the original experiment log remains untouched.
The processing steps are Python scripts that can be embedded in the .prx file or be referenced as external .py files. The processing script itself is defined as a function usually called called "run" which is called once per matching XML element in the processed experiment log, and takes specially named arguments:
| name of argument | meaning |
|---|---|
| Any parameter explicitly specifed in .prx file, optionally with a suffix appended | Value from .prx file, interpreted according to suffix, as below |
| _xmldoc | datacollect2.xmldoc.xmldoc instance for the processed experiment long |
| _element | XML element to be operated on by the step |
| _dest_href | datacollect2.dc_value.hrefvalue pointing at destination directory where whiles should be written |
| The name of a sub-element of the XML element being operated on. If the sub-element is in a namespace then an underscore replaces the colon separating the namespace prefix. Optionally the name can have a suffix, which will cause the element to be interpreted according to the suffix. | No suffix means pass the element. A suffix of "_doc" means pass the xmldoc object containing the element. A suffix of "str", "float", "int", or "bool" means interpret the element content as the corresponding Python type. A suffix of "list", "tuple", "dict" or "set" means interpret the element content as a Python literal and cast to the specified type. A suffix of a dc_value value class name, e.g. "numericunits", "href", or "xmltree" will intrepret the element as an instance of the corresponding limatix.dc_value class |
Parallel processing is usually best done within your step by calling C or C++ computation routines that use OpenMP or similar. It is also possible to run multiple copies of ProcessTrak simultaneously on the same .prx file and experiment log. ProcessTrak uses file locking to ensure synchronization. For this to be useful, you need to rename your "run" function to "rununlocked" and make sure it does not access the experiment log or use any elements within the experiment log (it can accept parameters that have been converted from the experiment log, e.g. hrefs, ints, strings, and it can also return outputs that will be added to the experiment log). A future version of ProcessTrak might use Python's multiprocessing module to automatically run steps in parallel.
The button step displays a button that can can be used to trigger an event.
The dc_imagereadout step displays a parameter database entry that is an image within the checklist step alongside the description.
The dc_param step allows manual adjustment of a textual or numeric parameter database entry within the checklist step alongside the description. This is probably the most commonly used alternative stepclass.
Like dc_param (above) but provides a pull-down of preselected options on top of the manual value entry. The options are set when the parameter is configured (.dcc file) using the options=["value1", "value2"] parameter.
The runchecklist step opens a sub-checklist or sub-plan.
The rundatacollect step is used in plans (and perhaps occasionally checklists) that are run using the dc_checklist program, as opposed to with datacollect. The rundatacollect step triggers running the datacollect program with predetermined parameters.
The runmatlabscript step runs a MATLAB function and captures the output. The script can use DBus to access datacollect parameters.
The runscript step runs an external script or program and captures the output. The script can use DBus to access datacollect parameters. It can define an XML structure to pass back to datacollect using the datacollect2.dc_dbus_paramclient.dc_automeas class and its saveautomeas() method.
The savebutton step has a button that triggers some sort of save or snapshot operation to store measured results in files. Triggers up to three save operations. Note that the parameters may not be saved simultaneously -- the savebutton step may bring up file selection or confirmation dialogs in between saving the parameters.
To use the savebutton step, configure 1-3 parameter database entries that store hypertext references for the file(s) that will be saved. In the .dcc file:
paramdb.addparam("datafile",datacollect2.dc_value.hrefvalue,reset_with_meas_record=True,dangerous=True,save_extension="dat",build = lambda param: ... )
The parameter database entry needs to be built (build= parameter) with a controller that provides a perform_save() method that will save the desired data in the specified file. For example, if you have abstracted your hardware interface in a class wrapped by datacollect2.threadserializedwrapper, then you would use datacollect2.paramdb2.threadserializedcontroller with its saver= parameter set to your save method. Specifically, your build parameter might be:
build=lambda param: datacollect2.paramdb2.threadserializedcontroller(param, wrapped_instance_of_hardware_interface, saver=wrapped_instance_of_hardware_interface.save_method)
The save_method would take a single parameter, a hypertext reference value with the file to save as, and return this value when complete. For example:
def save_thermaldata(self,hrefvalue): filename=hrefvalue.getpath() ### Place code to save current data to file here return hrefvalue
The savemeasurement step includes a button that triggers saving a measurement to the experiment log. This is equivalent to pressing the done button of a 'done_is_save_measurement' checklist. It adds a <dc:measurement> tag to the experiment log, stores snapshots values from all parameter database entries that did not have hide_from_meas=True specified, copies any autoexp automatically run experiments from the measurement checklist, increments measnum, and resets values of all parameter database entries which were configured with reset_with_meas_record=True.
(none)
The textentry step provides an entry box in which a value can be entered. The entry box is not mapped to any parameter database entry; the value entered is only stored in the filled checklist. This step is supported outside of datacollect, including by the standalone HTML/Javascript checklist editor provided by the datacollect2-qautils package.
The textgraphic step provides an image alongside the description. This step is supported outside of datacollect, including by the standalone HTML/Javascript checklist editor provided by the datacollect2-qautils package.
Please note that the image itself does not get copied or moved when the checklist is filled out, so the filled checklist will keep a hypertext reference to the original image file.
The text step is the default step that just includes a text description with an optional title attribute.
(none)
All value data type classes are instances of the abstract superclass datacollect2.dc_value.value. They wrap the underlying Python representation, sometimes adding functionality such as adding unit management to numeric types. These classes are final: Once instantiated they should not be changed. Therefore references can be passed around freely without concern that the referenced object might be modified. They generally implement the following methods:
| Method name | mandatory parameters | function |
|---|---|---|
| __init__ | Wrapped or unwrapped value to for the new instance | Constructor |
| isblank | (none) | Return whether or not the value of this instance qualifies as blank |
| __unicode__ | (none) | Return unicode representation |
| __str__ | (none) | Return string representation |
| __eq__ | Another wrapped or unwrapped value | Determine whether this instance is equal to the other value |
| xmlrepr | (xmldocu,element) | Store an XML representation in the specified element within the specified xmldoc instance xmldocu |
| fromxml (classmethod) | (xmldocu,element) | Create and return an instance of this class by extracting the value from the specified element of the specified xmldoc instance xmldocu |
| merge (classmethod) | (parent,descendentlist) | Attempt to merge multiple, possibly inconsistent desecendents of parent |
| value | (none) | Return underlying value |
xmltreevalue represents arbitrary XML content as an XML tree. It can be initialized from a datacollect2.xmldoc object, an element, or a seriaized XML string. Special methods:
| Method name | parameters | function |
|---|---|---|
| get_xmldoc | (nsmap=None,contexthref=None,force_abs_href=False) | Return a copy of the underlying datacollect2.xmldoc.xmldoc instance, with the specified nsmap or HREF context overrides |
stringvalue represents a regular or unicode string. Unicode support may be unreliable under Python 2, but should work normally under Python 3. (No special methods)
hrefvalue represents a hypertext reference in a particular context. Context represents the source of the cross-reference and the components from which that source was assembled. It can be initialized from a URL or from another hrefvalue object. If providing a URL you can provide an optional contexthref keyword argument specifying the context for the URL that will be used if the URL is relative.
If you want to reference a file name or path, you must convert the file name or path to a relative or absolute URL before creating the hrefvalue. Use urllib.pathname2url() (Python 2.x) or urllib.request.pathname2url() (Python >= 3.0) to perform the conversion. If you are referencing just a file name (no path separators), you may alternatively use urllib.quote() (Python 2.x) or urllib.parse.quote() (Python 3.x) to do the conversion. If the path might be relative, then you must provide the current directory as context! i.e. the additional contructor parameter contexthref=dc_value.hrefvalue("./")
Special methods:
| Method name | parameters | function |
|---|---|---|
| ismem | (none) | Return whether this is an in-memory (mem://) URL |
| ishttp | (none) | Return whether this is an HTTP (http://) URL |
| isfile | (none) | Return whether this is an FILE (file:// or no specified protocol) URL |
| humanurl | (none) | Return most human-readable form of the full, absolute URL. Note that this is NOT a file path (see getpath()) |
| canonicalize | (none) | Attempt to create a canonicalized representation of this URL. Note that the canonical form is dependent on tag_index_paths |
| fromelement | (xmldocu,element,tag_index_paths_override=None)(none) | Create and return an hrefvalue that points at the specified element, including URL path and fragment. Use tag_index_paths_override to specify additional tag_index_paths |
| islocalfile | (none) | same as isfile() |
| absurl | (none) | Return full, absolute URL. Note that this is NOT a file path (see getpath()) |
| attempt_relative_href | (new_context) | Create a new hrefvalue relative to specified new_context |
| has_fragment | (none) | Return if the URL has a fragment (portion after the '#') |
| getunquotedfragment | (none) | Get URL fragment (after the #) in non-percent-encoded form |
| getquotedfragment | (none) | Get URL fragment (after the #) in proper percent-encoded URL form |
| gethumanfragment | (none) | Get URL fragment (after the #) translated to most human-readable form |
| get_bare_quoted_filename | (none) | Return filename portion of URL, with special characters quoted as in a URL |
| get_bare_unquoted_filename | (none) | Return filename portion of URL, not using quoting of special URL characters, as in a filename |
| isdirectory | (none) | Determine if the URL is that of a directory (i.e. ends with a slash '/') |
| getpath | (none) | For FILE URL's, convert URL to a filesystem pathname and return |
| fragless | (none) | Return a hrefvalue with any fragment portion of the URL removed |
| leafless | (none) | Return a hrefvalue with any file part portion of the URL removed (but with trailing slash present) |
| __hash__ | (none) | hrefvalue is hashable, based on the return value of absurl(), so it is usable for dictionary keys |
| evaluate_fragment | (xmldocu,refelement,noprovenance=False) | Given this hrefvalue and an opened document xmldocu which contains its target, evaluate the fragment portion of the hrefvalue and return an element set of those which match the fragment criterion. refelement is used if the fragment is a relative in-document URI (not fully supported) |
complexunitsvalue represents a complex number with units. It can be initialized from a string, a number, a complex number, a complexunitsvalue, or a numericunitsvalue. Units can also be optionally supplied. Special methods:
| Method name | parameters | function |
|---|---|---|
| numvalue | (units=None) | Return value in the specified units |
| value | (units=None) | Return value in the specified units |
| units | (none) | Return lm_units instance of the specified units |
| valuedefunits | (none) | Return value converted to specified defunits from constructor |
| format | (formatstr=None,unit=None) | Return formatted value plus units based on formatstr and in specified units |
| comsolstr | (none) | Return value and units using COMSOL's notation for specifying units |
| simplifyunits | (none) | Attempt to simplify units, returning a new complexunitsvalue |
| inunits | (unit) | Convert to a new complexunitsvalue in specified units |
| equiv | (other) | Evaluate equivalence. Simlar to equality, but NaN is equivalent to NaN |
| __pow__ | (other) | Return new complexunitsvalue raised to specify power |
| __add__ | (other) | Add value of other, return new complexunitsvalue |
| __sub__ | (other) | Subtract value of other, return new complexunitsvalue |
| __mul__ | (other) | Multiply value of other, return new complexunitsvalue |
| __div__ | (other) | Divide value of other, return new complexunitsvalue |
numericunitsvalue represents a real number with units. It can be initialized from a string, a number, or a numericunitsvalue. Units can also be optionally supplied. Special methods:
| Method name | parameters | function |
|---|---|---|
| numvalue | (units=None) | Return value in the specified units |
| value | (units=None) | Return value in the specified units |
| units | (none) | Return lm_units instance of the specified units |
| valuedefunits | (none) | Return value converted to specified defunits from constructor |
| format | (formatstr=None,unit=None) | Return formatted value plus units based on formatstr and in specified units |
| comsolstr | (none) | Return value and units using COMSOL's notation for specifying units |
| simplifyunits | (none) | Attempt to simplify units, returning a new numericunitsvalue |
| __float__ | (none) | Return value as floating point |
| inunits | (unit) | Convert to a new numericunitsvalue in specified units |
| equiv | (other) | Evaluate equivalence. Simlar to equality, but NaN is equivalent to NaN |
| __pow__ | (other) | Return new numericunitsvalue raised to specify power |
| __add__ | (other) | Add value of other, return new numericunitsvalue |
| __sub__ | (other) | Subtract value of other, return new numericunitsvalue |
| __mul__ | (other) | Multiply value of other, return new numericunitsvalue |
| __div__ | (other) | Divide value of other, return new numericunitsvalue |
integervalue represents an integer. It can be initialized from an integer, a string, or an integervalue object. Special methods:
| Method name | parameters | function |
|---|---|---|
| numvalue | (none) | Return value as from value() method |
| format | (formatstr=None) | Return formatted value based on formatstr |
| comsolstr | (none) | Return value using COMSOL's notation (no different from __str__()) |
| __add__ | (other) | Add value of other, return new integervalue |
| __sub__ | (other) | Subtract value of other, return new integervalue |
| __mul__ | (other) | Multiply value of other, return new integervalue |
| __div__ | (other) | Divide value of other, return new integervalue |
Represents vibrothermography excitation parameters. Initialized from an object or dictionary with type, f0, f1, t0, t1, t2, t3 parameters. (No special methods)
imagevalue represents an image. It can be initialized from a PIL (Python Imaging Library, or derivatives) object, an or an imagevalue object. (No special methods)
photosvalue represents a set of experiment photographs. It can be iniaizlied from a photosvalue or from a list or set of hrefvalues. Special methods:
| Method name | parameters | function |
|---|---|---|
| copyandappend | (newphotohref) | Create a new photosvalue with one element added to the set based on newphotohref |
datesetvalue represents a set of dates. It can be iniaizlied from a datesetvalue or from a string representing a date or semicolon-separated set of dates , or from a set of datetime.date objects. Special methods:
| Method name | parameters | function |
|---|---|---|
| union | (other) | Return the union of this datesetvalue with other. |
| __contains__ | (other) | Return if this datesetvalue contains all elements in other |
accumulatingdatesetvalue represents a set of dates. It is similar to datesetvalue but it overrides the merge operation, so that attempts to merge accumulate (union) together. (Special methods are same as datesetvalue)
integersetvalue represents a set of integers. It can be initialized from an integer or from set of integers, or from an integersetvalue. Special methods:
| Method name | parameters | function |
|---|---|---|
| union | (other) | Return the union of this integersetvalue with other. |
| __contains__ | (other) | Return if this integersetvalue contains all elements in other |
accumulatingintegersetvalue represents a set of dates. It is similar to integersetvalue but it overrides the merge operation, so that attempts to merge accumulate (union) together. (Special methods are same as integersetvalue)
arrayvalue represents a numpy array. It can be initialized from a numpy array or from an arrayvalue. (No special methods)
The xmldoc class represents an XML document with a suitable API for adding/removing elements, working with XML namespaces, and looking up arrays of values.
| Parameter | meaning | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| nsmap | Dictionary for namespace prefix mapping to use when reading/writing elements. If provided as None, the following mapping will be used:
| ||||||||||||||||||||
| readonly | Boolean, should the document allow modification | ||||||||||||||||||||
| use_databrowse | Boolean, should the document be accessed via databrowse library (only works with readonly) | ||||||||||||||||||||
| num_backups | Number of backup files to keep on disk | ||||||||||||||||||||
| use_locking | Boolean: Should locking be enabled? Locking requires the .lock_ro(), .unlock_ro(), .lock_rw(), and/or .unlock_rw() methods to be used to lock the document prior to access, and implements that locking using whatever underlying disk access model is active. Note that a future RESTful API version may use merge attemps on unlock() rather than actually locking the underlying filesystem object. | ||||||||||||||||||||
| contexthref | Context URL location for hypertext references within the document | ||||||||||||||||||||
| debug | Enable debugging |
Constructor for loading an xmldoc from a serialized file specified by HREF URL. Parameters:
| Parameter | meaning |
|---|---|
| href | Hypertext reference to serialized file to load |
Constructor for loading an xmldoc from a serialized file specified by name. Parameters:
| Parameter | meaning |
|---|---|
| filename | filename path of file to load |
Constructor for creating a blank xmldoc in memory. You can use the set_href() method to save it to disk
| Parameter | meaning |
|---|---|
| maintagname | namespace prefix and tag name for main tag of new document |
Constructor for creating a blank xmldoc in memory. You can use the set_href() method to save it to disk. contexthref gives the assumed context of hypertext references in the file
| Parameter | meaning |
|---|---|
| xml_string | Serialized string of XML tags to load into the document |
| force_abs_href | Convert all relative hypertext references to absolute on load |
Constructor for creating an in-memory copy of an xmldoc object. Converts hypertext references to the specified contexthref, or make them absolute if force_abs_href is specified.
| Parameter | meaning |
|---|---|
| xmldoc | Pre-existing xmldoc object |
| force_abs_href | Convert all relative hypertext references to absolute on load |
Constructor for creating an in-memory XML document by copying a tree of elements from another document. Can be the whole document, just one element, or anwhere inbetween. Note that this makes its own deep copy of the original, so the original can be modified independently. Assumes hypertext references are in the context of specified xmldocu, unless that is None in which case they are assumed to be in the context of contexthref, and will make them absolute if force_abs_href is specified.
| Parameter | meaning |
|---|---|
| lxmletree | Pre-existing lxml ElementTree object. Don't keep using it after passing it to frometree() as it becomes embedded in the new xmldoc object. |
| force_abs_href | Convert all relative hypertext references to absolute on load |
Constructor for creating an in-memory XML document from a Python LXML etree. Note that this steals the existing object, so don't use it for anything else. Assumes hypertext references are in the context of specified contexthref, and will make them absolute if force_abs_href is specified.
| Parameter | meaning |
|---|---|
| lxmletree | Pre-existing lxml ElementTree object. Don't keep using it after passing it to frometree() as it becomes embedded in the new xmldoc object. |
| force_abs_href | Convert all relative hypertext references to absolute on load |
Get the URI HREF (datacollect2.dc_value.hrefvalue object) for a this document, or a mem://URI for in-memory checklists
Get the URI HREF context (datacollect2.dc_value.hrefvalue object) for a this document
For an xmldoc with no filename set, adjust the contexthref for xlink:hrefs to contexthref. If contexthref is already set will do fixups on all xlink:hrefs in the tree. force_abs_href=True will force convert all relative xlink:hrefs into absolute (and also allows contexthref=None)
convert an xlink:href=... to a dc_value.hrefvalue object if contextnode is None, context is assumed to be the root if xpath is None, path is assumed to be the context node. xpath should be path to a node which contains the xlink:href attribute Remaining parameters are passed to xpathsingle() for help in evaluating the xpath returns dc_value.hrefvalue object. Raises NameError if the xpath gives zero or multiple results raises AttributeError if no suitable xlink:href is found in the tag can be found
convert an xlink:href=... to an absolutized url if contextnode is None, context is assumed to be the root if xpath is None, path is assumed to be the context node. xpath should be path to a node which contains the xlink:href attribute Remaining parameters are passed to xpathsingle() for help in evaluating the xpath. Returns URL. Raises NameError if the xpath gives zero or multiple results. Raises AttributeError if no suitable xlink:href is found in the tag can be found. Raises IOError if the xlink:href does not refer to a local file.
convert an xlink:href=... to a complete filesystem path if contextnode is None, context is assumed to be the root if xpath is None, path is assumed to be the context node. xpath should be path to a node which contains the xlink:href attribute. Remaining parameters are passed to xpathsingle() for help in evaluating the xpath. Returns filename. Raises NameError if the xpath gives zero or multiple results. Raises AttributeError if no suitable xlink:href is found in the tag can be found. Raises IOError if the xlink:href does not refer to a local file.
This is used to set a file location if the document did not have one, or to set a new file location (i.e. href, i.e. filename). It also updates the readonly attribute (default False). if file is currently locked, it triggers a write under the old href (i.e. filename) It triggers a write under the new href (i.e. filename) unless readonly is set. Note: if the file is not locked, and changes have been made to the on disk copy, and you change the filename, those changes will NOT be copied into the new file. If you want such behavior, lock the file (thereby reading in the changes) prior to calling setfilename. If the file is new and we're supposed to be locked, this creates the lock too. NOTE: readonly applies to the new name, but NOT NECESSARILY the old name If the name changes to something other than None, readonly must not be set If the name changes to None, you can specify a new contexthref and it will convert xlink:href's to the new contexthref. If you don't specify the new contexthref, it will store the old context in the xmldoc contexthref field. In general, xlink:hrefs will be updated with the change. if force_abs_href is True, then all such updates will be to absolute paths
Set readonly status... If locking is used, must be fully unlocked.
xpathsingle() finds a single element based on an arbitrary XPath expression. If 0 elements or more than one element is returned, it raises a NameError. The configured nsmap may be used, but note that that the default namespace is inoperative for xpath (implicit namespace means null namespace). If your path is simple, and you don't care if there are excess matches, use the find() method instead xpath: Path to search namespaces: additional namespaces contextnode: Context node or list for relative search extensions: additional extensions
Alias for xpathsingle(xpath,namespaces,contextnode)
Like xpathsingle(), but converts result to an integer. Do NOT use the number() function of xpath, as that gives floats, not integers
Alias for xpathsingleint(xpath,namespaces,contextnode)
Like xpathsingle, but converts result to a float
Alias for xpathsinglefloat(xpath,namespaces,contextnode)
Like xpathsingle, but converts result to unicode
Alias for xpathsinglestr(xpath,namespaces,contextnode)
Get the name of the tag for a specific element, with proper namespace prefix. Raises IndexError if no prefix available
getsingleelement() is an alias for xpathsingle() for backward compatibility.
Remove the provided element from the document
Remove the provided elements from the document
This routine creates and appends a new empty element to the document. parent: a path (find()-style) or an element, or None to represent the main tag. elname: name of the element prefix, with namespace prefix if appropriate The newly created element is returned
This routine copies preexisting elements (sourceelements -- a list of elements) from another document (sourcedoc) into this document. parent: a path (find()-style) or an element, or None to represent the main tag. sourcedoc: xmldoc from which to copy the elements sourceelements: list of elements to copy
This routine creates and inserts a new empty element to the document. parent: a path (find()-style) or an element, or None to represent the main tag. position: Position within parent... 0 means first, -1 means last. elname: name of the element prefix, with namespace prefix if appropriate
Set the text content of an element. element: The element object text: string or unicode object with the replacement text NOTE: Doesn't currently handle text after subelements or comments properly!
Set the text content of an element. element: The element object NOTE: Doesn't currently handle text after subelements or comments properly!
Find the specified path given the option context (or main tag) Additional namespaces or extensions can be provided if desired. path: path to search namespaces: additional namespaces to merge with the main dictionary contextnode: Starting point for path, or list of starting points. extensions: Any additional xpath extensions desired
Alias for xpath(path,namespaces,contextnode)
Like xpath, but convert node-set to floating point, return as numpy array along with units. All entries are presumed to have the same units. An exception will be thrown if a unit mismatch is found. contextnodes can be either a single context node, or a list, in which case if oneper==True, there must be exactly one result per context node. Do NOT use xpath to convert node to number returns (resultunits, numpyarray) where resultunits is a lm_units instance. Don't forget to properly initialize lm_units! iscomplex: If true, output array should be complex instead of real. oneper: If True, there must be exactly one result per context node (if contextnodes is a list)
Like xpathnumpy but must provide context nodes
Like xpath, but convert node-set to unicode, return as numpy array. contextnodes can be either a single context node, or a list, in which case if oneper==True, there must be exactly one result per context node oneper: If True, there must be exactly one result per context node (if contextnodes is a list)
Like xpathnumpy but must provide context nodes before path
Like xpath, but convert node-set to integers, return as numpy array. Nodes must NOT be comverted to numbers using xpath but must be given as nodes or (if necessary) as strings . contextnodes can be either a single context node, or a list, in which case if oneper==True, there must be exactly one result per context node oneper: If True, there must be exactly one result per context node (if contextnodes is a list)
Like xpathnumpyint, but with mandatory context before path
Get the root node of the document
Find a canonical absolute (Clark notation) xpath representation based off the filesystem root for the specified element within doc. The document must have a filename for this to work.
Get a saveable path the specified element. Treat the data structure as opaque as it may evolve: NOTE: The returned xpath is currently NOT compatible with find() and WILL be incorrect if nodes have been added or removed upwards and prior in the tree. If the canonicalize_path package is available, it will be used to provide a more consistent scheme for identifying deep content, which can often be correct even if nodes are added or removed prior in the tree. The canonicalize_path package can be customized with /etc/canonicalize_path/tag_index_paths_local.conf or /usr/local/etc/canonicalize_path/tag_index_paths_local.conf depending on the installation prefix of canonicalize_path.
Restore a saved path (as returned from savepath) to an element. Treat the data structure as opaque as it may evolve.
Find the element matching path in the tree, optionally with respect to the specified context node or the document root. find is always relative to the main tag node (default) or supplied context node. Absolute finds not supported. path: An ElementPath (simplified XPath) namespaces: additional namespaces needed for interpreting path contextnode: optional context node"""
alias for find(path,namespaces,contextnode
Add a simple sub-element containing value and optional units parent: may be a path or an element elname: Name of element to create, optionally with namespace prefix. In addition if elname begins with '@', an attribute is added instead of an element valueunits: (value,units) tuple. If units is provided, it will be an attribute with name dcv:units.
Find context child specified by tag. Return child or None (return value can be used as truth value)
Find context children specified by tag or all children. Return list
Determine whether an element is actually an XML comment
Set an attribute of an element to the specified value. Use namespace prefixes as usual. tag: The element itself, or path to it from the main tag, or None to reference attributes of the main tag attrname: Name of attribute to set value: Value of the attribute
Remove an attribute of an element. Use namespace prefixes as usual. tag: The element itself, or path to it from the main tag attrname: Name of attribute to remove
Remove the specified element.
Set the attribute of the specified element or path Use namespace prefixes as usual. tag: The element itself, or path to it from the main tag, or None to get attributes of the main tag attrname: Name of attribute to get defaultvalue: Default value of the attribute to return. If this is None and the attribute is not set, IndexError will be raised. namespaces: Additional namespaces for attribute evaluation
Check if the attribute of the specified element or path exists. Use namespace prefixes as usual. tag: The element itself, or path to it from the main tag, or None to reference the main tag attrname: Name of attribute to check the existance of
Lock the file for read only access. File locking is counted, so lock calls may be nested
Unlock the file from read-only-access
Return whether the document is locked for access
Lock the file for read-write access. File locking is counted, so lock calls may be nested
Unlock the file from read-write access
Assert that the document should be unlocked
Assert that the document should be read-write locked exactly once
Return true if element tag matches tagname
Convert to unicode string... see also tobytes()
Convert to utf-8 bytes can specify encoding=None to generate ascii (and use entities for higher characters)
Get the parent of a particular element
Close and empty this document. Flush to disk first if modified
Datacollect uses GTK as its GUI toolkit. To create a custom widget or checklist step class, you create a new GTK widget class and then tell datacollect about it.
The current version of datacollect works with PyGTK2 and (via GObject introspection) GTK3. Try to make your new class compatible with both. For example, use the following import statments to test for GObject introspection and if present, use GTK3:
if "gi" in sys.modules: # gtk3 import gi gi.require_version('Gtk','3.0') from gi.repository import Gtk as gtk from gi.repository import Gdk as gdk from gi.repository import GObject as gobject pass else : # gtk2 import gobject import gtk import gtk.gdk as gdk pass
Your new class will usually derive from an existing GTK class. Most often you derive from gtk.HBox or gtk.GBox. See the GTK documentation for information on defining GTK classes in Python.
You will need to define special class members to name your GTK class and specify its settable GTK properties: __gtype_name__ and __gproperties__. You also need to call gobject.type_register() after defining your class to register it with GTK's type system.
For creating general purpose widgets, your class's constructor __init__() should require no parameters beyond self. For a checklist step, __init__() is given three additional parameters: checklist, the checklist object, step, the datacollect2.steptemplate instance, and xmlpath, a path that can be passed to checklist.xmldoc.restorepath() to find the XML element corresponding to this step.
Often it is convienient in the constructor to construct the internal structure of a widget or step with the Glade GUI builder or Glade XML. This structure can then be conveniently instantiated:
(self.gladeobjdict,self.gladebuilder)=datacollect2.dc_gtksupp.build_from_file(os.path.join(os.path.split(sys.modules[self.__module__].__file__)[0],"my_glade_file.glade"))
The components can then be looked up in self.gladeobjdict and, if your class is derived from a GTK container, added to that container.
In addition to a constructor, all datacollect steps and widgets are expected to have a dc_gui_init() method that takes a datacollect2.dc_gtksupp.guistate object as a parameter in addition to self. The dc_gui_init() method is called later in the initialization phase, once I/O connections have been created and the parameter database is available.
Optional methods for datacollect steps and widgets include isconsistent(self,inconsistentlist) which returns False (and appends the name of the parameter to inconsistentlist) if the widget or a subwidget has an inconsistent representation of a parameter. An example of this is the user typing a few letters, but not pressing ENTER to trigger the parameter change.
Another optional method is set_readonly(self,readonly), which is called to set the readonly status of the step or widget to readonly. Optional methods for checklist steps only include handle_check(self,checked), which is called when the checklist box is checked or unchecked, and resetchecklist(self), which is called when the checklist is reset, and destroystep(self) which is called to indicate the checklist is being permanently closed.
It is also necessary to inform datacollect that the step and/or widget is available to use. This is accomplished in the setup.py of your package by marking the class as an entry point for "datacollect2.step" or "datacollect2.widget":
setup(..., entry_points={"datacollect2.step": ["my_package.my_module.my_step_class"], "datacollect2.widget": ["my_package.my_module.my_widget_class"]})
You may also want to make your widgets accessible to the glade GUI-builder. This is normally done by creating a "catalog" XML file plus corresponding .py file for loading the widgets and adding it to the glade catalog path. Unfortunately the version of glade currently used with datacollect (glade-3.6.7, for GTK2 compatibility) does not accept more than a single entry for its GLADE_CATALOG_PATH environment variable, so if you want both Datacollect's widgets and your widgets to be accessible simultaneously you have to hack around this problem.
The parameter controller for a parameter database entry is a class instance that is responsible for managing the value of the parameter and requests to change the parameter. It is usually called within a build= lambda parameter to addparam(). The first constructor parameter is the paramdb2.param instance for the parameter being controlled.
The controller needs to define a requestval(self,param,newvalue,*cbargs) method: param is the paramdb2.param instance, newvalue is the desired new value (datacollect2.dc_value.value subclass instance), cbargs is the callback function followed by extra parameters to the callback function. requestval() is an asynchronous request for the parameter to take on a particular value. It should only be called by the main GTK thread. In general, the callback may happen immediately or later after requestval() returns, but should be called in the context of the main GTK thread (such as by queueing a call with gobject.timeout_add()). requestval returns an ID that can be used to attempt to cancel the request prior to the callback.
cbargs[0], if present, is interpreted as the function to call when the request is complete. It is called as
(cbargs[0])(controlparam,request_id,error_message_or_None,new_parameter_dcvalue_or_None_if_failure,*cbargs[1:])
The controller should also define a cancelrequest(self,param,requestid) that attempts to cancel a pending request. In this case requestid would be the return value from a prior requestval().
When the controller determines that a new value should be assigned to the parameter -- either as a result of an assignment attempt or some external process that might have changed the parameter -- it should call controlparam.assignval(newvalue,self.id) where newvalue is the new value to assign, which should be an instance of the datacollect2.dc_value.value subclass controlparam.paramtype.
An optional controller method is perform_save(self,param,savehref,*cbargs). This method is used for parameters that are used to store references to files containing saved data. The perform_save method is called by the savebuttonstep. The controller should ask the underlying hardware or virtual instrument model to save its data at the specified location (savehref) and once complete assign the savehref to the parameter value.


Hello am Anna Adhiambo and a student purchasing a career in web development.
I do love singing during my free time,a times watch movies.
Reading books atimes when their is silence.I was able to make my own project which was my first app.
We are a wide co-operation that deals with health to ensure that you are secure.
Fitness is also an important guarantee since it works hand in hand with health.
Fitness includes doing exercises to keep our bodies fit and flexible and in good shape.
Health on the other hand deals with food we take in,in our daily basis.
What type of food and health routine,do we take as we care about our bodies being maintained?
Well,we will take a look at that in the next page,for now let us talk about what we are all about.
This is a food store that caters for those who requires
instant food delivery which is still fresh
and blazing hot.
Our foods are prepared by one
of the best chefs in Kenya and are packed with
care and without preservatives.


...the dead hand of the academy had yet to stifle the unbridled enthusiasms of a small band of amateurs in Europe and America.
Michael D. Coe, Breaking the Maya Code
[Note: the hypertext links in this appendix are to WWW sites external to the standards document, and were correct as of 21th February 2014.]
The resources below are mainly available from the if-archive maintained by David Kinder and Stephen Granade.
Since the 1.0 Standard was first introduced, a variety of interpreters have become available, for many different platforms and with a variety of features. The page on Playing Interactive Fiction at inform7.com is a good place to start when looking for an interpreter, as is the ifwiki page on the Z-Machine.
A few story files exist to test interpreter for various Z-Machine features:
Infocom's original compiler Zilch no longer exists, but a PDF copy of Learning ZIL, Infocom's documentation for their ZIL language, is available. Since the emergence of this file, there have been a few attempts at making a new ZIL compiler, most notably ZILF by Jesse McGrew.
No continuous part of the source code of any of Infocom's games is in the public domain [but see Stu Galley's chapter of an Infocom history article, and the IEEE article, for fragments].
Inform remains the most popular compiler for Z-Machine games. In 2006, the first public release of Inform 7 was made available. Inform 7 is a very different language from previous versions of Inform, with a focus on natural language and a powerful IDE.
While Inform 7 is the main focus of development, Inform 6 is still widely used and the compiler and libraries continue to be maintained.
A few other compilers have been made available over the years.
Mark Howell has written a toolkit of Ztools, or utility programs (1991-5, updated 1997), which includes:
These continue to be maintained (by Matthew Russotto) and the first two are extremely useful. Infodump largely supersedes Mike Threepoint's vocabulary dumper Zorkword (1991-2), which was important in its day (and which this author found extremely helpful when writing Inform 1).
Reform, by Ben Rudiak-Gould, is a decompiler for Z-Machine games which will attempt to convert them into Inform 6 source code.
Most of the Infocom games exist in several different releases, and some were written for one Version and then ported to later ones. 'Zork I', for instance, has at least 11 releases, 2 early, 8 in Version 3 (with release numbers between 5 to 88 in chronological order) and one in Version 5 (release 52 -- the releases go back to 1 when the version changes).
Version 1 and 2 games are extinct, though there are a few fossils in the hands of collectors.
The definitive guide to all Infocom story files known to exist, and an indispensable reference for anyone interested in Infocom, is Paul David Doherty's Infocom fact sheet, which is regularly updated, concise and precise. This supersedes Paul Smith's "Infocom Game Information" file.
Stefan Jokisch has written a brief specification of Infocom-format sound effects files.
Martin Frost is the author of the Quetzal standard for saved-game files. Patches to adapt Zip-based interpreters to use Quetzal are available.
Andrew Plotkin is the author of the Blorb standard for packaging up images and sounds with Z-machine games.
The Inform Technical Manual documents the format of parsing tables used in Inform games.
The documentation for Infocom's games is available online (with permission from Activision) courtesy of the Infocom Documentation Project. In addition, an archive of the " samplers" is publically available, as is an interesting historical archive of magazine articles concerning Infocom, and articles from Infocom's own publicity magazine [indexed here].
Section 1 / 2 / 3 / 4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 / 15 / 16
Appendix A / B / C / D / E / F


| Trees | Indices | Toggle frames |
|---|
AbstractBuffer --+ | VertexBufferObject --+ | AbstractMappable --+ | MappableVertexBufferObject
A VBO with system-memory backed store.
Updates to the data via set_data, set_data_region and map will be held in local memory until bind is called. The advantage is that fewer OpenGL calls are needed, increasing performance.
There may also be less performance penalty for resizing this buffer.
Updates to data via map are committed immediately.
| __init__(self, size, target, usage) | |
| bind(self) | |
| set_data(self, data) | |
| set_data_region(self, data, start, length) | |
| map(self, invalidate=False) | |
| unmap(self) | |
| AbstractBufferRegion |
get_region(self,
start,
size,
ptr_type)
Map a region of the buffer into a ctypes array of the desired
type.
|
| resize(self, size) | |
| __del__(self) (Inherited from pyglet.graphics.vertexbuffer.VertexBufferObject) | |
|
delete(self)
Delete this buffer, reducing system resource usage.
(Inherited from pyglet.graphics.vertexbuffer.VertexBufferObject)
|
|
|
unbind(self)
Reset the buffer's OpenGL target.
(Inherited from pyglet.graphics.vertexbuffer.VertexBufferObject)
|
| int |
ptr = 0
Memory offset of the buffer, as used by the glVertexPointer
family of functions
(Inherited from pyglet.graphics.vertexbuffer.AbstractBuffer)
|
| int |
size = 0
Size of buffer, in bytes
(Inherited from pyglet.graphics.vertexbuffer.AbstractBuffer)
|
| int |
target
OpenGL buffer target, for example GL_ARRAY_BUFFER
(Inherited from pyglet.graphics.vertexbuffer.AbstractBuffer)
|
| int |
usage
OpenGL buffer usage, for example GL_DYNAMIC_DRAW
(Inherited from pyglet.graphics.vertexbuffer.AbstractBuffer)
|
Map a region of the buffer into a ctypes array of the desired type. This region does not need to be unmapped, but will become invalid if the buffer is resized.
Note that although a pointer type is required, an array is mapped. For example:
get_region(0, ctypes.sizeof(c_int) * 20, ctypes.POINTER(c_int * 20))
will map bytes 0 to 80 of the buffer to an array of 20 ints.
Changes to the array may not be recognised until the region's AbstractBufferRegion.invalidate method is called.
| Trees | Indices | Toggle frames |
|---|
| Generated by Epydoc 3.0beta1 on Sun Mar 22 20:15:39 2009 | http://epydoc.sourceforge.net |


{%marked%}
####Headers
```
#Header1
##Header2
###Header3
####Header4
#####Header5
```
#Header1
##Header2
###Header3
####Header4
#####Header5
###Links
```
This is an [example link](http://example.com/).
```
This is an [example link](http://example.com/).
####Text formatting
```
Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
```
Emphasis, aka italics, with *asterisks* or _underscores_.
Strong emphasis, aka bold, with **asterisks** or __underscores__.
Combined emphasis with **asterisks and _underscores_**.
Strikethrough uses two tildes. ~~Scratch this.~~
####Block Quotes
```
> ## Blockquoted header
>
> This is blockquoted text.
>
> This is a second paragraph within the blockquoted text.
```
> ## Blockquoted header
>
> This is blockquoted text.
>
> This is a second paragraph within the blockquoted text.
####Lists
```
+ One
+ Two
+ Three
- Nested One
- Nested Two
```
+ One
+ Two
+ Three
- Nested One
- Nested Two
{%endmarked%}
{% endblock %}