diff --git a/ChangeLog.txt b/ChangeLog.txt index e7b3232e..e6f50676 100644 --- a/ChangeLog.txt +++ b/ChangeLog.txt @@ -1,6 +1,8 @@ ViTables ChangeLog ================== ** May 24, 2017 ** +The Users' Guide has been updated. + Some .txt files have been updated. Calls to str(object, 'UTF-8') have been removed. diff --git a/doc/conf.py b/doc/conf.py index 88b39669..763f4bf2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -121,7 +121,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = [] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. @@ -171,7 +171,7 @@ # -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). -latex_paper_size = 'a4' +# latex_paper_size = 'a4' # The font size ('10pt', '11pt' or '12pt'). #latex_font_size = '10pt' @@ -183,7 +183,7 @@ 'Vicent Mas', 'manual'), ] -latex_elements = {'babel': '\\usepackage[english]{babel}', 'classoptions': ', openany'} +latex_elements = {'babel': '\\usepackage[english]{babel}', 'classoptions': ', openany', 'papersize': 'a4'} # The name of an image file (relative to this directory) to place at the top of # the title page. diff --git a/doc/images/browseDataset.png b/doc/images/browseDataset.png index faec036a..b950a594 100644 Binary files a/doc/images/browseDataset.png and b/doc/images/browseDataset.png differ diff --git a/doc/images/editingUserAttrs.png b/doc/images/editingUserAttrs.png index c437780a..57aff54d 100644 Binary files a/doc/images/editingUserAttrs.png and b/doc/images/editingUserAttrs.png differ diff --git a/doc/images/groupCreation.png b/doc/images/groupCreation.png index 8d9a7847..c48cfd41 100644 Binary files a/doc/images/groupCreation.png and b/doc/images/groupCreation.png differ diff --git a/doc/images/mainWindow.png b/doc/images/mainWindow.png index cb030874..53b1d7bb 100644 Binary files a/doc/images/mainWindow.png and b/doc/images/mainWindow.png differ diff --git a/doc/images/newFilteredTable.png b/doc/images/newFilteredTable.png index 61311c31..d532db5d 100644 Binary files a/doc/images/newFilteredTable.png and b/doc/images/newFilteredTable.png differ diff --git a/doc/images/propertiesDlg.png b/doc/images/propertiesDlg.png index 789b69c7..4e568c61 100644 Binary files a/doc/images/propertiesDlg.png and b/doc/images/propertiesDlg.png differ diff --git a/doc/images/treeSymbols.png b/doc/images/treeSymbols.png index 02283da7..1e6f8db6 100644 Binary files a/doc/images/treeSymbols.png and b/doc/images/treeSymbols.png differ diff --git a/doc/images/zoomingCells.png b/doc/images/zoomingCells.png index 0e5b1fe4..c0271854 100644 Binary files a/doc/images/zoomingCells.png and b/doc/images/zoomingCells.png differ diff --git a/doc/posterIcons.py b/doc/posterIcons.py index ae4b3d5f..4898b505 100644 --- a/doc/posterIcons.py +++ b/doc/posterIcons.py @@ -1,7 +1,7 @@ # -*- coding: utf-8 -*- # Copyright (C) 2005, 2006, 2007 Carabos Coop. V. All rights reserved -# Copyright (C) 2008, 2017 Vicent Mas. All rights reserved +# Copyright (C) 2008-2017 Vicent Mas. All rights reserved # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -23,13 +23,13 @@ # import sys -from PyQt4.QtCore import * -from PyQt4.QtGui import * +from qtpy import QtGui +from qtpy import QtWidgets -iconsDir = '/home/vmas/ViTables/hg_branches/vitables_tip/vitables/icons/' +ICONSDIR = '../vitables/icons/' big_icons = [('file_rw', 'The root node (read-write)'), ('file_ro', 'The root node (read-only)'), - ('dbfilters', 'The root node of the Query Results file'), + ('dbfilters', 'The root node of the Query Results file '), ('folder', 'A collapsed group '), ('document-open-folder', 'An expanded group ')] small_icons = [('table', 'A table (heterogeneus dataset) '), @@ -38,47 +38,47 @@ ('carray', 'A compressed array'), ('vlarray', 'A variable length array'), ('vlstring', 'An array of VLStrings'), + ('link_table', 'A soft link to a table (heterogeneus dataset) '), + ('link_array', 'A soft link to a regular array (homogeneus dataset) '), + ('link_earray', 'A soft link to an enlargeable array'), + ('link_carray', 'A soft link to a compressed array'), + ('link_vlarray', 'A soft link to a variable length array'), ('object', 'A serialized objects dataset'), ('image-missing', 'An unsupported dataset')] -class Poster(QMainWindow) : - def __init__(self, *args) : - apply(QMainWindow.__init__, (self,) + args) - w = QWidget(self) - l = QGridLayout(w) +class Poster(QtWidgets.QMainWindow) : + def __init__(self) : + super(QtWidgets.QMainWindow, self).__init__() + w = QtWidgets.QWidget(self) + l = QtWidgets.QGridLayout(w) self.setCentralWidget(w) self.makePoster() - def changePalette(self, widget): - palette = QPalette() - self.palette().setColor(widget.backgroundRole(), Qt.white) - widget.setPalette(palette) - - def makePoster(self): widget = self.centralWidget() layout = widget.layout() r = 0 - iconsDict = {'big_icons': big_icons, 'small_icons': small_icons} + c = 0 + iconsDict = {'22x22': big_icons, '16x16': small_icons} for key in iconsDict.keys(): for (name, caption) in iconsDict[key] : - pixmap = QPixmap() - image_path = '%s/%s.png' % ("%s%s" % (iconsDir, key), name) - print image_path + pixmap = QtGui.QPixmap() + image_path = '{0}/{1}/{2}.png'.format(ICONSDIR, key, name) pixmap.load(image_path) - imLabel = QLabel(widget) + imLabel = QtWidgets.QLabel(widget) imLabel.setPixmap(pixmap) - self.changePalette(imLabel) - layout.addWidget(imLabel, r, 0, 1, 1) - textLabel = QLabel(caption,widget) - self.changePalette(textLabel) - layout.addWidget(textLabel, r, 1, 1, 1) + layout.addWidget(imLabel, r, c, 1, 1) + textLabel = QtWidgets.QLabel(caption,widget) + layout.addWidget(textLabel, r, c + 1, 1, 1) r = r + 1 + if r > 8: + r = 0 + c = 2 def main(args) : - app = QApplication(args) + app = QtWidgets.QApplication(args) poster = Poster() poster.show() app.exec_() diff --git a/doc/usersguide-app1.rst b/doc/usersguide-app1.rst index 662ae355..0c464115 100644 --- a/doc/usersguide-app1.rst +++ b/doc/usersguide-app1.rst @@ -1,46 +1,40 @@ - -.. raw:: pdf - - PageBreak appendixPage - -.. _appendix-a: - -About Plugins -============= - -Since version 2.1 *ViTables* has a simple but powerful plugins framework. - -If you are interested in writing plugins the next paragraphs can be of utility. If not you can skip to the list of available plugins. - -Plugins live in the plugins subdirectory of the root directory where the source code is installed. A plugin can be a pure Python module -or can have a package structure (i.e. a directory with a :mod:`__init__.py` file). Packages can have as many directories as you want but -plugins must be located at top level of the package. - -The use of contracts is not enforced when writing plugins so you have nearly complete freedom for writing them. Nevertheless a plugin must -declare the following variables. :const:`plugin_class` which is set to the name of the class invoqued when your plugin is executed by *ViTables*, -:const:`plugin_name` which is set to the descriptive name of the plugin and will be used in the Plugins page of the Preferences dialog and, -finally, :const:`comment` which is set to a short description of the plugin and will be used too in the Plugins page of the Preferences dialog. - -In some cases it can be useful to use convenience variables or methods. For instance, suppose than in the Preferences dialog you want to show a -more complete description of your plugin that that provided by the :const:`comment` variable. Then you may be interested in define a method -:meth:`!helpAbout` in your plugin. - -Of course some knowledge (not necessarily a deep one) of the *ViTables* code is required in order to bind your plugin to the application core. -This task is commonly achieved via the menu bar of the main window or via the signals/slots mechanism (convenience signals can be defined in -the application if needed). - -If you need more help just send an email to developers or ask to the *ViTables* Users' Group. - -Three plugins are currently distributed along with the application: - - Time series - formats time series in a human friendly way. It supports PyTables time datatypes and PyTables time series created via scikits.timeseries - module. The format used for displaying times can be configured by user via the Preferences dialog or editing by hand the - :file:`time_format.ini` configuration file. - - Import CSV - provides import capabilities from :abbr:`CSV` files into PyTables datasets. - - Export CSV - provides export capabilities of PyTables datasets to :abbr:`CSV` files. - +.. raw:: pdf + + PageBreak appendixPage + +.. _appendix-a: + +About Plugins ++++++++++++++ + +Since version 2.1 `ViTables` has a simple but powerful plugins framework. + +If you are interested in writing plugins the next paragraphs can be of utility. If not you can skip to the list of available plugins. + +Plugins live in the plugins subdirectory of the root directory where the source code is installed. A plugin can be a pure Python module or can have a package structure (i.e. a directory with a :mod:`__init__.py` file). Packages can have as many directories as you want but plugins must be located at top level of the package. + +The use of contracts is not enforced when writing plugins so you have nearly complete freedom for writing them. Nevertheless a plugin must declare the following variables. :const:`plugin_class` which is set to the name of the class invoqued when your plugin is executed by `ViTables`, +:const:`plugin_name` which is set to the descriptive name of the plugin and will be used in the Plugins page of the Preferences dialog and, finally, :const:`comment` which is set to a short description of the plugin and will be used too in the Plugins page of the Preferences dialog. + +In some cases it can be useful to use convenience variables or methods. For instance, suppose than in the Preferences dialog you want to show a more complete description of your plugin that that provided by the :const:`comment` variable. Then you may be interested in define a method :meth:`helpAbout` in your plugin. + +Of course some knowledge (not necessarily a deep one) of the `ViTables` code is required in order to bind your plugin to the application core. This task is commonly achieved via the menu bar of the main window or via the signals/slots mechanism (convenience signals can be defined in the application if needed). + +If you need more help just send an email to developers or ask to the `ViTables` Users' Group. + +Five plugins are currently distributed along with the application: + + Time series formatter + formats time series in a human friendly way. It supports PyTables time datatypes and PyTables time series created via `pandas `_ or the obsolete scikits.timeseries module. The format used for displaying times can be configured by user via the Preferences dialog or editing by hand the :file:`time_format.ini` configuration file. + + CSV Importer + provides import capabilities from `CSV` files into PyTables datasets. + + CSV Exporter + provides export capabilities of PyTables datasets to `CSV` files. + + Tree of DBs sorting + sorts the display of the databases tree. + + Columnar organization of arrays + rearranges several arrays with the same number of rows and displays them in a unique widget. diff --git a/doc/usersguide-app2.rst b/doc/usersguide-app2.rst index 01d3f35b..f43dd711 100644 --- a/doc/usersguide-app2.rst +++ b/doc/usersguide-app2.rst @@ -1,30 +1,24 @@ -The Help Browser -================ - -*ViTables* comes with its own -fully-integrated documentation browser. It allows the -*ViTables* User's Guide to be browsed without -leaving the current working session and without opening external -applications. You can start the browser issuing the -:menuselection:`Help --> User's Guide` -command or from the toolbar. - -The help browser is a small HTML browser for -*local* documents. Despite its small size it exhibits -some nice features - -- bookmarks - -- session history - -- easy document navigation through navigation buttons - -A nice feature of bookmarks is that they can be navigated while they are being edited with the Bookmarks -Editing dialog. Simply double click on a bookmark and it will be displayed in the browser. - -.. _help-browser: -.. figure:: images/helpBrowser.png - :width: 80% - - The Users' Guide browser - +The Help Browser +++++++++++++++++ + +`ViTables` comes with its own fully-integrated documentation browser. It allows the `ViTables` User's Guide to be browsed without leaving the current working session and without opening external applications. You can start the browser issuing the +:menuselection:`Help --> User's Guide` command or from the toolbar. + +The help browser is a small HTML browser for *local* documents. Despite its small size it exhibits some nice features + +- bookmarks + +- session history + +- easy document navigation through navigation buttons + +A nice feature of bookmarks is that they can be navigated while they are being edited with the Bookmarks Editing dialog. Simply double click on a bookmark and it will be displayed in the browser. + +.. _help-browser: +.. figure:: images/helpBrowser.png + :width: 80% + :align: center + :figclass: align-center + + The Users' Guide browser + diff --git a/doc/usersguide-ch1.rst b/doc/usersguide-ch1.rst index 17394a2e..2d093089 100644 --- a/doc/usersguide-ch1.rst +++ b/doc/usersguide-ch1.rst @@ -1,197 +1,144 @@ -.. sectnum:: - -.. |geq| unicode:: U+02265 .. greater than or equal symbol - -Introduction -============ - -Overview -++++++++ - -*ViTables* is a member of the PyTables -family. It's a graphical tool for browsing and editing files in both -PyTables and :abbr:`HDF5` formats. With *ViTables* you -can easily navigate through data hierarchies, request metadata, view -real data and much more. - -*ViTables* is being developed using Python -and PyQt, the bindings of Qt libraries, so it can run on any platform -that -supports these components (which includes Windows, Mac OS X, Linux and many -other Unices). The interface and features will remain the same on all -platforms. - -Efficiency and low memory requirements are guaranteed by the fact -that data is loaded only when the object that contains it is opened and -by the use of data buffers for dealing with large datasets. - -Capabilities -++++++++++++ - -The current release provides browsing, displaying, editing and querying capabilities. Some of them are listed -below. Details are discussed in the related chapters. - -Browsing and Displaying Capabilities -************************************ - -- Display data hierarchy as a fully browsable object tree. - -- Open several files simultaneously. - -- Open files in write mode as well as in read-only mode, disabling all editing - functions. - -- Display file information (path, size, number of nodes…). - -- Display node (group or leaf) properties, including metadata and attributes. - -- Display numerical arrays, i.e. homogeneous tables. - -- Display heterogeneous table entities, i.e. records. - -- Display multidimensional table cells. - -- Unlimited zoom into the inner dimensions of multidimensional table cells. - -Editing Capabilities -******************** - -These editing features have been implemented for the object tree [#f1]_: - -- File creation and renaming. - -- Node creation (only for groups), renaming and deletion. - -- Ability to copy and move nodes from their location to a different one, even in different files. - -- Attribute creation, renaming and deletion. - -All these changes automatically update the database (i.e. the file) to which the nodes belong. - -Other -***** - -Other nice features include: - -- *Ability to smoothly navigate really large datasets*. - -- Support for doing complex table queries with a low memory footprint. - -- Flexible plugins framework. A bunch of useful plugins are already included, see the :ref:`Appendix A` for - details. - -- Configurable look and feel. - -- A logger area, where errors and warnings (if any) are printed. - -- Several levels of help are available: users guide, context help, tooltips and status bar. - -We have paid special attention to usability issues so making use of these features is intuitive and pleasant. -Nevertheless, and just in case, we are providing this guide :-). - -System Requirements -+++++++++++++++++++ - -To run *ViTables* you need to install Python 2.6 or Python 2.7, -PyTables >= 2.2 (so you have to fulfil its own requirements) and PyQt4 >= 4.8.3. - -At the moment, *ViTables* has been fully tested on Linux and Windows XP and Vista platforms. -Other Unices should run just fine when using the Linux version because all the -software that *ViTables* relies on (i.e. Python, Qt, PyQt, :abbr:`HDF5` and PyTables) is known to -run fine on many Unix platforms as well. - -Installation -++++++++++++ - -Unix -**** - -The Distutils module (part of the standard -Python distribution) has -been used to prepare an installer for -*ViTables*. It makes easy to get the -application up and running. - -At the moment no binary versions of the installer exist, so the -software has to be installed from sources. - -Provided that your system fulfills the requirements listed in -the above sections, installing the package is really easy. Just -uncompress the package, change to the distribution directory and -execute - -:: - - $ python setup.py install - -By default *ViTables* will be -installed -in the system-protected area where your system installs third party -Python packages, so you will need superuser privileges. If you prefer -to install the package in a different location (for instance, your -home directory, so that you can complete the installation as a -non-privileged user), you can do it using the ---prefix tag: - -:: - - $ python setup.py install --prefix=/home/myuser/mystuff - -Please remember that installing Python modules in non-standard -locations makes it necessary to set the :envvar:`PYTHONPATH` -environment variable properly so that the Python interpreter can find -the installed modules. - -If you need further customizations, please have a look at the -output of the command - -:: - - $python setup.py install --help - -to see the available options. Complete information about these -options can be found in the Distutils documentation. - -Windows Binary Installers -************************* - -A binary installer is available for Windows platforms. Just double click the installer icon and follow -the wizard instructions. *ViTables* will be installed in a few clicks. - -Beware that the installer is not a superpackage containing all *ViTables* requirements. You -need PyTables and PyQt4 already installed on your system (excellent installers for both packages are -available) in order to install *ViTables*. - -Mac OS X Binary Installers -************************** - -You can use the general Unix procedure to install -*ViTables* on Mac OS X, but -generating a double-clickable application bundle is -recommended. Simply untar the source package, change to the -distribution directory and execute - -:: - - $ cd macosxapp - $ ./make.sh - -If you have problems with this please, refer to the :abbr:`FAQ` page in the *ViTables* website. - -Further Reading -*************** - -General information about PyTables can be found at the -project -site . -For more information on :abbr:`HDF5`, please visit its -web site . -Information about *ViTables* is available at -. - -Questions and feedback can be mailed to the developers. - -.. rubric:: Footnotes - -.. [#f1] Dataset editing capabilities have not yet been implemented. - +.. |geq| unicode:: U+02265 .. greater than or equal symbol + +Introduction +++++++++++++ + + + +Overview +******** + +`ViTables` is a member of the `PyTables` family. It's a graphical tool for browsing and editing files in both PyTables and `HDF5` formats. With `ViTables` you can easily navigate through data hierarchies, request metadata, view +real data and much more. + +`ViTables` is being developed using `Python` and `PyQt`, the bindings of `Qt` libraries, so it can run on any platform that supports these components (which includes Windows, Mac OS X, Linux and many other Unices). The interface and features will remain the same on all platforms. + +Efficiency and low memory requirements are guaranteed by the fact that data is loaded only when the object that contains it is opened and by the use of data buffers for dealing with large datasets. + +Capabilities +************ + +The current release provides browsing, displaying, editing and querying capabilities. Some of them are listed below. Details are discussed in the related chapters. + +Browsing and displaying capabilities +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Display data hierarchy as a fully browsable object tree. + +- Open several files simultaneously. + +- Open files in write mode as well as in read-only mode, disabling all editing functions. + +- Display file information (path, size, number of nodes…). + +- Display node (group or leaf) properties, including metadata and attributes. + +- Display numerical arrays, i.e. homogeneous tables. + +- Display heterogeneous table entities, i.e. records. + +- Display multidimensional table cells. + +- Unlimited zoom into the inner dimensions of multidimensional table cells. + +Editing capabilities +^^^^^^^^^^^^^^^^^^^^ + +These editing features have been implemented for the object tree [#f1]_: + +- File creation and renaming. + +- Node creation (only for groups), renaming and deletion. + +- Ability to copy and move nodes from their location to a different one, even in different files. + +- Attribute creation, renaming and deletion. + +All these changes automatically update the database (i.e. the file) to which the nodes belong. + +Other +^^^^^ + +Other nice features include: + +- *Ability to smoothly navigate really large datasets*. + +- Support for doing complex table queries with a low memory footprint. + +- Flexible plugins framework. A bunch of useful plugins are already included, see the :ref:`Appendix A` for + details. + +- Configurable look and feel. + +- A logger area, where errors and warnings (if any) are printed. + +- Several levels of help are available: users guide, context help, tooltips and status bar. + +We have paid special attention to usability issues so making use of these features is intuitive and pleasant. +Nevertheless, and just in case, we are providing this guide :-). + +System Requirements +******************* + +To run `ViTables` you need to install recent versions of `Python` (2 or 3), `PyTables` (so you have to fulfil its own requirements) and `PyQt`. For instance, it runs smoothly with `Python` 3.6, `PyTables` 3.4 and `PyQt` 5.8. + +At the moment, `ViTables` has been fully tested on Linux and Windows 10 platforms. Other Unices should run just fine when using the Linux version because all the software that `ViTables` relies on (i.e. `Python`, `Qt`, `PyQt`, `HDF5` and `PyTables`) is known to run fine on many Unix platforms as well. + +Installation +************ + + + +Linux +^^^^^ + +The `Distutils` module (part of the standard `Python` distribution) has been used to prepare installers for +`ViTables`. It makes easy to get the application up and running. + +You can install the program using a wheel or from sources. + +Provided that your system fulfills the requirements listed in +the above sections, installing the package from sources is really easy. Just uncompress the package, change to the distribution directory and execute + +:: + + $ python setup.py install + +By default `ViTables` will be installed in the system-protected area where your system installs third party `Python` packages, so you will need superuser privileges. If you prefer +to install the package in a different location (for instance, your home directory, so that you can complete the installation as a non-privileged user), you can do it using the --prefix tag: + +:: + + $ python setup.py install --prefix=/home/myuser/mystuff + +Please remember that installing `Python` modules in non-standard locations makes it necessary to set the :envvar:`PYTHONPATH` environment variable properly so that the `Python` interpreter can find the installed modules. + +If you need further customizations, please have a look at the +output of the command + +:: + + $ python setup.py install --help + +to see the available options. Complete information about these +options can be found in the `Distutils` documentation. + +Windows and Mac OS X +^^^^^^^^^^^^^^^^^^^^ + +Currently there are no graphical installers available for these platforms. You +have to install `ViTables` from the command line, using one of the methods +described in the Linux section. + + +Further Reading +*************** + +General information about `PyTables` can be found at `its project site `_. For more information on `HDF5`, please visit its web site `www.hdfgroup.org/HDF5 `_. Information about `ViTables` is available at `vitables.org `_. + +Questions and feedback can be mailed to the developers. + +.. rubric:: Footnotes + +.. [#f1] Dataset editing capabilities have not yet been implemented. + diff --git a/doc/usersguide-ch2.rst b/doc/usersguide-ch2.rst index 678de89b..a093f5a4 100644 --- a/doc/usersguide-ch2.rst +++ b/doc/usersguide-ch2.rst @@ -1,52 +1,48 @@ -.. sectnum:: - :start: 2 - First Steps -=========== ++++++++++++ -In this chapter we are going to describe briefly the main elements -that you will meet throughout your working sessions. +In this chapter we are going to describe briefly the main elements that you will meet throughout your working sessions. How to Start -++++++++++++ +************ -Usually *ViTables* is started by running -the :program:`vitables` program under X (from a terminal emulator -or directly from your desktop). If you are using a terminal then you can -give some arguments to the command line +You can start `ViTables` from a desktop shortcut or from a terminal emulator. +If you launch the program from the command line the following options are available:: -Currently command -line arguments are available only in Linux platforms. -You can get the available arguments by issuing the command: + $ vitables --help -:: + usage: vitables [option]... [h5file]... + + positional arguments: + h5file - $ vitables --help - $ usage: vitables \[options] \[h5file] - options: - --version show program's version number and exit - -h, --help show this help message and exit - -mMODE, --mode=MODE mode access for a database - -dh5list, --dblist=h5list - a file with the list of databases to be open + optional arguments: + -h, --help show this help message and exit + --version show program's version number and exit + + h5files: + -m MODE, --mode MODE mode access for a database. Can be r(ead) or a(ppend) + -d DBLIST, --dblist DBLIST + a file with the list of HDF5 filepaths to be open -Basically you can specify a file to open or a file containing a list of -files to open. For example: + logging: + -l LOG_FILE, --log-file LOG_FILE + log file path + -v, --verbose log verbosity level + +Basically you can specify a file to open or a file containing a list of files to open. For example: :: $ vitables myh5file -will start *ViTables* and open the file myh5file -in read-write mode. If you want to open it in read-only mode then execute -the command: +will start `ViTables` and open the file myh5file in read-write mode. If you want to open it in read-only mode then execute the command: :: $ vitables -m r myh5file -In order to open a set of files at once put them in a list file with the -syntax +In order to open a set of files at once put them in a list file with the syntax :: @@ -58,31 +54,21 @@ syntax $ vitables -d h5list -Once the application is running the -:ref:`main window` appears. It consists -of a :ref:`menu bar`, a set of tool bars, a :ref:`viewing area` and a status bar. +Once the application is running the :ref:`main window` appears. It consists of a :ref:`menu bar`, a set of tool bars, a :ref:`viewing area` and a status bar. -The viewing area of the window is divided into three parts. The -:ref:`tree of databases viewer` is the narrow region placed at top left side. It will display a -tree representation of the data hierarchies we want to access. The big -panel next to the tree viewer is called the :ref:`workspace`, and will display -the real data contained in a given node of the data hierarchy. Finally, -the bottom region is the :ref:`logger`, a kind of text non interactive console -where information about your requested operations will be shown. +The viewing area of the window is divided into three parts. The :ref:`tree of databases viewer` is the narrow region placed at top left side. It will display a tree representation of the data hierarchies we want to access. The big panel next to the tree viewer is called the :ref:`workspace`, and will display the real data contained in a given node of the data hierarchy. Finally, the bottom region is the :ref:`logger`, a kind of text non interactive console where information about your requested operations will be shown. As usual, you can launch commands from the menu bar, from context menus or, if a shortcut button is available, from a toolbar. Also keyboard shortcuts are available for most commands. -After starting your session, you are likely to open some files. -Just drag the file(s) you want to open into the tree of databases viewer and they -will be opened in read-write mode. Opening can be done from the file -manager dialog too; simply issue an open command, -:menuselection:`File --> Open File` (:kbd:`Ctrl-O`) and choose a file. +After starting your session, you are likely to open some files. Just drag the file(s) you want to open into the tree of databases viewer and they will be opened in read-write mode. Opening can be done from the file manager dialog too; simply issue an open command, :menuselection:`File --> Open File` (:kbd:`Ctrl-O`) and choose a file. .. _main-window: .. figure:: images/mainWindow.png :width: 90% + :align: center + :figclass: align-center The main window @@ -90,81 +76,54 @@ manager dialog too; simply issue an open command, .. _menu-bar: The Menu Bar -++++++++++++ +************ -The menu bar is placed at top of the main window. It is composed of -six pulldown menus. +The menu bar is placed at top of the main window. It is composed of six pulldown menus. **File menu** -This menu contains commands to manipulate files in several ways: -open, close, create, save and so on. It also gives to you quick access to -the most recently opened files. +This menu contains commands to manipulate files in several ways: open, close, create, save and so on. It also gives to you quick access to the most recently opened files. **Node menu** -The :guilabel:`Node` menu contains commands to manipulate the nodes displayed in the tree of databases viewer. From this menu -you can edit nodes in a variety of ways as well as access their -properties. +The :guilabel:`Node` menu contains commands to manipulate the nodes displayed in the tree of databases viewer. From this menu you can edit nodes in a variety of ways as well as access their properties. **Dataset menu** -With this menu you can make selects in any table (the result of -your selects will be available under the Query Results node in the -tree pane). The number of entries for this menu depends on the list of enabled plugins. +With this menu you can make selects in any table (the result of your selects will be available under the Query Results node in the tree pane). The number of entries for this menu depends on the list of enabled plugins. **Settings menu** This is the menu from which the application can be customized. -Customization includes startup behavior, look and feel and plugins management. You can add/remove paths for -loading plugins, enable and disable -plugins. Changes in the enabled/disabled status of a given plugin take effect after restarting *ViTables*. See -:ref:`the ViTables Configuration chapter` for more -information on this subject. +Customization includes startup behavior, look and feel and plugins management. You can add/remove paths for loading plugins, enable and disable plugins. Changes in the enabled/disabled status of a given plugin take effect after restarting `ViTables`. See :ref:`the ViTables Configuration chapter` for more information on this subject. -Also from this menu you can show, hide and -line up the application toolbars. At the moment four toolbars are -available, :guilabel:`File`, :guilabel:`Node`, -:guilabel:`Query` and :guilabel:`Help`. +Also from this menu you can show, hide and line up the application toolbars. At the moment four toolbars are available, :guilabel:`File`, :guilabel:`Node`, :guilabel:`Query` and :guilabel:`Help`. **Window menu** -The :guilabel:`Window` menu can be used to change the arrangement of the -workspace contents, sorting the open windows as a cascade or as a tile. -By selecting a window name from this menu, you can raise (bring to the -front) that window. Any open window can be closed from this menu. +The :guilabel:`Window` menu can be used to change the arrangement of the workspace contents, sorting the open windows as a cascade or as a tile. By selecting a window name from this menu, you can raise (bring to the front) that window. Any open window can be closed from this menu. **Help menu** -The :guilabel:`Help` menu displays this User's Guide in :abbr:`HTML4` format and a -couple of *About* boxes, one for the *ViTables* itself and one for the underlying Qt libraries. The :guilabel:`Show Versions` entry shows the version numbers of the libraries -being used by *ViTables* (Qt, PyQt, PyTables and PyTables -related libraries, like Zlib or :abbr:`LZO`). Finally, from this menu you can -enter the *What's This* mode which will show context help for the components of the viewing area (the databases tree viewer, the workspace and the logger). +The :guilabel:`Help` menu displays this User's Guide in :`HTML4` format and a couple of *About* boxes, one for the `ViTables` itself and one for the underlying Qt libraries. The :guilabel:`Show Versions` entry shows the version numbers of the libraries being used by `ViTables` (Qt, PyQt, PyTables and PyTables related libraries, like Zlib or `LZO`). Finally, from this menu you can enter the *What's This* mode which will show context help for the components of the viewing area (the databases tree viewer, the workspace and the logger). .. _viewing-area: The Viewing Area -++++++++++++++++ +**************** -As mentioned before, the viewing area is -divided into three regions: the databases tree viewer (also called tree -pane), the workspace and the -logger. Now we are going to describe these regions in more detail. +As mentioned before, the viewing area is divided into three regions: the databases tree viewer (also called tree pane), the workspace and the logger. Now we are going to describe these regions in more detail. .. _tree-pane: The Databases Tree Viewer -************************* +^^^^^^^^^^^^^^^^^^^^^^^^^ -Due to the hierarchical model of the underlying :abbr:`HDF5` library, -PyTables files store their data on disk in a tree-like structure. Every -time you open a PyTables file, its so-called object tree (a -representation of the data hierarchy) is dynamically created and added to the tree of databases viewer, at the top left side of the viewing area (see :ref:`the main window Figure`). +Due to the hierarchical model of the underlying `HDF5` library, PyTables files store their data on disk in a tree-like structure. Every time you open a PyTables file, its so-called object tree (a representation of the data hierarchy) is dynamically created and added to the tree of databases viewer, at the top left side of the viewing area (see :ref:`the main window Figure`). -.. note:: since PyTables-1.2 the object tree of an opened file is made on demand: nodes are added to the tree when they are accessed. *ViTables* makes use of this feature, which results in stunningly fast opening times for files with a large number of nodes. +.. note:: since PyTables-1.2 the object tree of an opened file is made on demand: nodes are added to the tree when they are accessed. `ViTables` makes use of this feature, which results in stunningly fast opening times for files with a large number of nodes. Any object tree is made of nodes which can be classified as follows: @@ -178,31 +137,19 @@ Any object tree is made of nodes which can be classified as follows: Leaves are nodes that contain real data. They can be tables or arrays. Working with object trees is really easy. By double-clicking -on it, a root node is opened, and the tree structure below it is -displayed. Groups are presented as -folders. They can be expanded with a double-click, giving you immediate -access to their contents. A group can contain groups and/or leaves (or -may be empty). A double click on a leaf will display its content on -the workspace. You can access the available options for a given node -just with a right mouse click on it. A context menu will appear from -which commands can be launched. The contents of the menu depend on the -kind of -node being clicked (root nodes, groups, tables and arrays have all of -them their own context menu). Alternatively you can select the node -with a single mouse click and choose a command from the +on it, a root node is opened, and the tree structure below it is displayed. Groups are presented as folders. They can be expanded with a double-click, giving you immediate access to their contents. A group can contain groups and/or leaves (or +may be empty). A double click on a leaf will display its content on the workspace. You can access the available options for a given node just with a right mouse click on it. A context menu will appear from which commands can be launched. The contents of the menu depend on the kind of node being clicked (root nodes, groups, tables and arrays have all of +them their own context menu). Alternatively you can select the node with a single mouse click and choose a command from the :guilabel:`Node` menu. There is also a context menu -for the tree pane itself that will pop up by right-clicking any empty -area of the tree viewer. Last but not least, the object tree can be navigated with the keyboard too. Pressing the Enter key -the selected node will be expanded (if it is a group) or opened (if it is -a leaf). The + and - keys expand an collapse groups. +for the tree pane itself that will pop up by right-clicking any empty area of the tree viewer. Last but not least, the object tree can be navigated with the keyboard too. Pressing the Enter key the selected node will be expanded (if it is a group) or opened (if it is a leaf). The + and - keys expand an collapse groups. Every node in a given object tree has an associated icon that -allows you to identify its type quickly. The following icons are -available: +allows you to identify its type quickly. The following icons are available: .. _node-symbols: .. figure:: images/treeSymbols.png - :width: 40% + :align: center + :figclass: align-center The node symbols @@ -210,54 +157,29 @@ available: .. _workspace: The Workspace -************* - -At this point you should have one or more files opened, and their -object trees displayed in the databases tree viewer. Your next step will be to -select a leaf and display its data. Remember that the object tree -imitates the structure on disk, which makes it very easy to browse the -hierarchy of the file and locate the leaf you want to open. - -A double-click on a leaf of your choice will open it and display -its contents in a window (a *view* in the -*ViTables* jargon) placed in the workspace, the big panel at the -top right side of the viewing area -(see :ref:`the main window Figure`). - -Note that the databases tree viewer and the workspace are always -synchronized: if you select a node in the tree viewer and that node has -a view, then that view becomes the active view on the workspace. The -opposite is also true, click on a view on the workspace and its node -will be automatically selected on the databases tree viewer. +^^^^^^^^^^^^^ + +At this point you should have one or more files opened, and their object trees displayed in the databases tree viewer. Your next step will be to select a leaf and display its data. Remember that the object tree imitates the structure on disk, which makes it very easy to browse the hierarchy of the file and locate the leaf you want to open. + +A double-click on a leaf of your choice will open it and display its contents in a window (a *view* in the +`ViTables` jargon) placed in the workspace, the big panel at the top right side of the viewing area (see :ref:`the main window Figure`). + +Note that the databases tree viewer and the workspace are always synchronized: if you select a node in the tree viewer and that node has a view, then that view becomes the active view on the workspace. The opposite is also true, click on a view on the workspace and its node will be automatically selected on the databases tree viewer. The :guilabel:`Window` pulldown menu provides some additional commands that will help you to manage your -views. From -this menu you can, for instance, rearrange views, see the -list of views (which is particularly useful when the workspace is -cluttered with so many views that it's difficult to find the one -you want) or close all the views at once. - -There is also a context menu for the workspace. It can be used to change the workspace view mode: you can -display views as regular windows (default behavior) or with tabs in a tab bar. In addition it give you access -to the :guilabel:`Window` pulldown menu. +views. From this menu you can, for instance, rearrange views, see the list of views (which is particularly useful when the workspace is cluttered with so many views that it's difficult to find the one you want) or close all the views at once. +There is also a context menu for the workspace. It can be used to change the workspace view mode: you can display views as regular windows (default behavior) or with tabs in a tab bar. In addition it give you access to the :guilabel:`Window` pulldown menu. .. _logger: The Logger -********** +^^^^^^^^^^ -The logger is a read-only (i.e. non interactive) console placed at the bottom of the viewing -area (see :ref:`the main window Figure`). It is an -info panel where *ViTables* reports the result -of requested operations (namely if they were not successful). -Also runtime errors are caught and reported to you through the logger -(so you can mail the error to *ViTables* -developers and help to improve the quality of the package :-). Errors -and warning messages are highlighted in red and orange respectively. +The logger is a read-only (i.e. non interactive) console placed at the bottom of the viewing area (see :ref:`the main window Figure`). It is an info panel where `ViTables` reports the result of requested operations (namely if they were not successful). Also runtime errors are caught and reported to you through the logger (so you can mail the error to `ViTables` +developers and help to improve the quality of the package :-). Errors and warning messages are highlighted in red and orange respectively. Of course there is also a context menu for the logger that -provides you with some handy operations, like to copy selected text or -to empty the logger. +provides you with some handy operations, like to copy selected text or to empty the logger. diff --git a/doc/usersguide-ch3.rst b/doc/usersguide-ch3.rst index b2b4cb07..abc090bd 100644 --- a/doc/usersguide-ch3.rst +++ b/doc/usersguide-ch3.rst @@ -1,137 +1,102 @@ -.. sectnum:: - :start: 3 - -Browsing and Querying Datasets -============================== - -In this chapter we are going to describe how the information -contained in a dataset can be navigated and filtered. - -Browsing Datasets -+++++++++++++++++ - -A noticeable aspect of views is the visualization speed. Views show -data nearly as quickly as PyTables accesses them. As a consequence, very -large datasets (with up to 2^64 rows) can be browsed stunningly fast. - -.. _browse-large-dataset: -.. figure:: images/browseDataset.png - :width: 80% - - Browsing a large dataset - -As said in the previous chapter, datasets are displayed in views. They are spreadsheet-like windows so can be navigated as you would expect: -via scrollbar, keyboard or wheel of mouse. - -.. note:: - what makes *ViTables* views interesting is that *the navigation speed is independent of the view size*: a table with several thousand million rows is navigated as quickly as a table with just a few dozens rows. - -Another interesting feature of views is the ability to zoom in on -cells that contain multidimensional data. When you double-click in a -cell, -it is displayed in its own view, reducing by two the number of -dimensions of the displayed data. For instance, a cell containing a -vector -is displayed as a one column table of scalars. A cell that contains -two-dimensional data will be shown as a bidimensional table of scalars. -And so on. In general, a cell containing N-dimensional data will be -displayed as a table of N-2 dimensions data. Zoom can be applied as many -times as needed, so that multi-dimensional cells can be inspected until -you get a table of scalars. Finally, if you try to zoom in on a cell that -contains a scalar value, this value will be presented alone in a view; -this can be useful to visualize large scalar values (for example, large -strings) that doesn't fit on regular columns. - - -.. _zoom-cell: -.. figure:: images/zoomingCells.png - :width: 80% - - Zooming a cell - -Getting Info -++++++++++++ - -For a given node two kinds of information are available: metadata -and data. From their metadata you can retrieve information about the -objects on disk, such as table and column names, titles, number of rows, -data types in columns or attributes, among others. - -The available metadata about a given node (group or leaf) can be -accessed by right-clicking the mouse on the node and launching the -:guilabel:`Properties` command from the context menu -that appears. This can also be achieved from the :guilabel:`Node` -menu. Then the :ref:`Properties dialog `, -that contains the requested metadata, is displayed. The dialog is made of -three tabs labelled as General, System attributes and User attributes. -The General tab contains generic information about the selected node, -i.e. name, path, etc. The System and User tabs -contain tables that describe the attributes of the node. - -.. _properties_dialog: -.. figure:: images/propertiesDlg.png - :width: 60% - - The Properties dialog - -Aside from the Properties dialog, you can get information in -several other ways. - -The full path of the node currently selected in the tree view is -displayed in the status bar. This can be -useful when the object tree is large and guessing a full path is not -easy. - -The top left icon of views shows the kind of displayed data -(array or table). - -Finally, some generic information can be obtained by launching the -command -:menuselection:`Help --> WhatIsThis` -(or clicking the appropriate button on the corresponding toolbar). - -Querying Tables -+++++++++++++++ - -An interesting feature of *ViTables* is its capability to make table selections. -This means that we can select a set of table rows that fulfill a given condition. You can filter any table -(even if it is closed) by issuing the command - -:menuselection:`Dataset --> Query…` -A dialog (see :ref:`this Figure`) will -be displayed where you can create a query and select the range of rows to -which the query will apply. Notice that, *you can make -complex queries, i.e. queries that involve more than one table field. -However the queried fields cannot be multidimensional or contain data -with Complex data type*. - -*ViTables* always do its best for not being frozen due to out of memory problems when you do complex queries or the queried table is huge (or both) but it is not guarateed that it can achieve this goal. - -The selected rows are stored in a new table (but not removed from -its original location) that we will call filtered table from here on. -Filtered tables are stored in a temporary database [#f2]_ labeled as *Query results* in the databases tree viewer. The *Query results* node is always placed at the bottom of the databases tree. - -Filtered tables can be edited as any other leaf opened in read-write mode. - -By default an automatic title FilteredTable_X is given to the X-th filtered table created. In addition, those tables have three user attributes that are, in principle, only defined for filtered tables. -These attributes are: - - query - the applied query - - query_path - the full path of the queried file - - query_table - the full path of the queried table in the object tree hierarchy - -.. _query_dlg: -.. figure:: images/newFilteredTable.png - :width: 50% - - The New Query dialog - -.. rubric:: Footnotes - -.. [#f2] Every time a *ViTables* session starts, a new temporary database is created from scratch. This database has a flat structure and is stored with a unique name in a temporary directory so the operating system will remove it every time the directory is cleaned. - +Browsing and Querying Datasets +++++++++++++++++++++++++++++++ + +In this chapter we are going to describe how the information +contained in a dataset can be navigated and filtered. + +Browsing Datasets +***************** + +A noticeable aspect of views is the visualization speed. Views show data nearly as quickly as PyTables accesses them. As a consequence, very large datasets (with up to 2^64 rows) can be browsed stunningly fast. + +.. _browse-large-dataset: +.. figure:: images/browseDataset.png + :width: 80% + :align: center + :figclass: align-center + + Browsing a large dataset + +As said in the previous chapter, datasets are displayed in views. They are spreadsheet-like windows so can be navigated as you would expect: via scrollbar, keyboard or wheel of mouse. + +.. note:: + what makes `ViTables` views interesting is that *the navigation speed is independent of the view size*: a table with several thousand million rows is navigated as quickly as a table with just a few dozens rows. + +Another interesting feature of views is the ability to zoom in on cells that contain multidimensional data. When you double-click in a cell, +it is displayed in its own view, reducing by two the number of +dimensions of the displayed data. For instance, a cell containing a vector is displayed as a one column table of scalars. A cell that contains two-dimensional data will be shown as a bidimensional table of scalars. And so on. In general, a cell containing N-dimensional data will be +displayed as a table of N-2 dimensions data. Zoom can be applied as many times as needed, so that multi-dimensional cells can be inspected until you get a table of scalars. Finally, if you try to zoom in on a cell that contains a scalar value, this value will be presented alone in a view; +this can be useful to visualize large scalar values (for example, large strings) that doesn't fit on regular columns. + + +.. _zoom-cell: +.. figure:: images/zoomingCells.png + :width: 80% + :align: center + :figclass: align-center + + Zooming a cell + +Getting Info +************ + +For a given node two kinds of information are available: metadata and data. From their metadata you can retrieve information about the objects on disk, such as table and column names, titles, number of rows, data types in columns or attributes, among others. + +The available metadata about a given node (group or leaf) can be accessed by right-clicking the mouse on the node and launching the :guilabel:`Properties` command from the context menu that appears. This can also be achieved from the :guilabel:`Node` menu. Then the :ref:`Properties dialog `, that contains the requested metadata, is displayed. The dialog is made of three tabs labelled as General, System attributes and User attributes. The General tab contains generic information about the selected node, i.e. name, path, etc. The System and User tabs contain tables that describe the attributes of the node. + +.. _properties_dialog: +.. figure:: images/propertiesDlg.png + :align: center + :figclass: align-center + + The Properties dialog + +Aside from the Properties dialog, you can get information in +several other ways. + +The full path of the node currently selected in the tree view is displayed in the status bar. This can be useful when the object tree is large and guessing a full path is not easy. + +The top left icon of views shows the kind of displayed data +(array or table). + +Finally, some generic information can be obtained by launching the command :menuselection:`Help --> WhatIsThis` +(or clicking the appropriate button on the corresponding toolbar). + +Querying Tables +*************** + +An interesting feature of `ViTables` is its capability to make table selections. This means that we can select a set of table rows that fulfill a given condition. You can filter any table +(even if it is closed) by issuing the command :menuselection:`Dataset --> Query…`. + +A dialog (see :ref:`this Figure`) will be displayed where you can create a query and select the range of rows to +which the query will apply. Notice that, *you can make complex queries, i.e. queries that involve more than one table field. +However the queried fields cannot be multidimensional or contain data with Complex data type*. + +`ViTables` always do its best for not being frozen due to out of memory problems when you do complex queries or the queried table is huge (or both) but it is not guarateed that it can achieve this goal. + +The selected rows are stored in a new table (but not removed from its original location) that we will call filtered table from here on. Filtered tables are stored in a temporary database [#f2]_ labeled as *Query results* in the databases tree viewer. The *Query results* node is always placed at the bottom of the databases tree. + +Filtered tables can be edited as any other leaf opened in read-write mode. + +By default an automatic title FilteredTable_X is given to the X-th filtered table created. In addition, those tables have three user attributes that are, in principle, only defined for filtered tables. These attributes are: + + query + the applied query + + query_path + the full path of the queried file + + query_table + the full path of the queried table in the object tree hierarchy + +.. _query_dlg: +.. figure:: images/newFilteredTable.png + :align: center + :figclass: align-center + + The New Query dialog + +.. rubric:: Footnotes + +.. [#f2] Every time a `ViTables` session starts, a new temporary database is created from scratch. This database has a flat structure and is stored with a unique name in a temporary directory so the operating system will remove it every time the directory is cleaned. + diff --git a/doc/usersguide-ch4.rst b/doc/usersguide-ch4.rst index 531a7519..8ab8fc8c 100644 --- a/doc/usersguide-ch4.rst +++ b/doc/usersguide-ch4.rst @@ -1,83 +1,55 @@ -.. sectnum:: - :start: 4 - -Editing Files -============= - -In this chapter we are going to describe briefly the editing -capabilities of *ViTables*. - -Creating Complex Hierarchies -++++++++++++++++++++++++++++ - -*ViTables* supports a complete set of -editing operations on files and nodes. The result of these operations is -made immediately visible on the databases tree viewer. - -To create a new file in write mode, just issue the command :menuselection:`File --> New…` (:kbd:`Ctrl-N`). -By default, the file will be created with a ``.h5`` -extension but you can provide your desired extension. - -You can add new empty groups to a writable file as easily as you -create a new file. Simply select a group on the the tree pane and launch -the command -:menuselection:`Node --> New group…`. -A new, empty group will be added to the previously selected group. By -combining this operation with file creation, you can easily create -complex hierarchies. Later on, you can populate the hierarchies with real -data using your PyTables programs. - -.. _group-creation: -.. figure:: images/groupCreation.png - :width: 80% - - Creating a new group - -Editing Object Trees -++++++++++++++++++++ - -Files opened in write mode can be modified by moving their nodes -(groups and leaves) around. From the -:guilabel:`Node` -menu you can copy, paste, cut, rename or delete any selected node -(except root groups). Typical keyboard shortcuts are available for copy -and paste operations. Of course, you can drag and drop nodes from one -location to a different one using the mouse. - -Nodes can be moved to a different location in the object tree, but -can also be reallocated in a different file. This way you can -*merge* open files in a very flexible and comfortable -way. - -As usual, while an operation is being performed on a given node, -the shape of the mouse cursor will change into a clock, reminding you -that a PyTables operation is being executed. - -Given a node opened in read-write mode you can edit its user attributes from -the User attributes page -(see :ref:`this Figure`) -in the node Properties dialog. This page contains the user attributes -table. You can add and remove attributes with the respective buttons or -you can edit any existing attribute by clicking the table cell that you -want to modify and introducing the new value. This way you can change -name, value and type of any existing attribute. - -.. note:: multidimensional attribute values are not supported by *ViTables*. Also be aware that scalar attributes will be saved as scalar Numpy objects instead of serialized using cPickle (which used to be the default PyTables behavior). This way you will be able to read them using generic :abbr:`HDF5` tools, not just PyTables. - -Finally, the value of the TITLE system attribute can also be -edited. -Just click its cell in the System Attributes tab and enter the desired -value. - -.. _editing_user_attributes: -.. figure:: images/editingUserAttrs.png - :width: 60% - - Editing user attributes - -Editing Leaves -++++++++++++++ - -At the moment of writing, editing the real data stored in leaves -has not yet been implemented. - +Editing Files ++++++++++++++ + +In this chapter we are going to describe briefly the editing +capabilities of `ViTables`. + +Creating Complex Hierarchies +**************************** + +`ViTables` supports a complete set of editing operations on files and nodes. The result of these operations is made immediately visible on the databases tree viewer. + +To create a new file in write mode, just issue the command :menuselection:`File --> New…` (:kbd:`Ctrl-N`). By default, the file will be created with a ``.h5`` extension but you can provide your desired extension. + +You can add new empty groups to a writable file as easily as you +create a new file. Simply select a group on the the tree pane and launch the command :menuselection:`Node --> New group…`. A new, empty group will be added to the previously selected group. By combining this operation with file creation, you can easily create complex hierarchies. Later on, you can populate the hierarchies with real data using your PyTables programs. + +.. _group-creation: +.. figure:: images/groupCreation.png + :width: 80% + :align: center + :figclass: align-center + + Creating a new group + +Editing Object Trees +******************** + +Files opened in write mode can be modified by moving their nodes (groups and leaves) around. From the :guilabel:`Node` +menu you can copy, paste, cut, rename or delete any selected node (except root groups). Typical keyboard shortcuts are available for copy and paste operations. Of course, you can drag and drop nodes from one location to a different one using the mouse. + +Nodes can be moved to a different location in the object tree, but can also be reallocated in a different file. This way you can *merge* open files in a very flexible and comfortable +way. + +As usual, while an operation is being performed on a given node, the shape of the mouse cursor will change into a clock, reminding you that a PyTables operation is being executed. + +Given a node opened in read-write mode you can edit its user attributes from the User attributes page (see :ref:`this Figure`) in the node Properties dialog. This page contains the user attributes table. You can add and remove attributes with the respective buttons or you can edit any existing attribute by clicking the table cell that you want to modify and introducing the new value. This way you can change name, value and type of any existing attribute. + +.. Note:: multidimensional attribute values are not supported by `ViTables`. Also be aware that scalar attributes will be saved as scalar Numpy objects instead of serialized using cPickle (which used to be the default PyTables behavior). This way you will be able to read them using generic `HDF5` tools, not just PyTables. + +Finally, the value of the TITLE system attribute can also be +edited. Just click its cell in the System Attributes tab and enter the desired value. + +.. _editing_user_attributes: +.. figure:: images/editingUserAttrs.png + :align: center + :figclass: align-center + + Editing user attributes + +Editing Leaves +************** + +At the moment of writing, editing the real data stored in leaves +has not yet been implemented. + diff --git a/doc/usersguide-ch5.rst b/doc/usersguide-ch5.rst index 03f45975..c8e41cad 100644 --- a/doc/usersguide-ch5.rst +++ b/doc/usersguide-ch5.rst @@ -1,101 +1,81 @@ -.. sectnum:: - :start: 5 - -.. _configuration-chapter: - -Configuring ViTables -==================== - -As mentioned earlier, many aspects of the *ViTables* behaviour can -be customized by you through the -:menuselection:`Settings --> Preferences` -command. - -It shows a dialog offering you several customization -possibilities. The dialog is made of three stacked pages, -:guilabel:`General`, :guilabel:`Look & Feel` and -:guilabel:`Plugins`. - -The :guilabel:`General` page allows to change the -*ViTables* behavior at startup. You can set the -initial working directory to be that one from which *ViTables* is starting or -to be the last used -working directory. And you can recover your last working session. - -The :guilabel:`Look & Feel` page allows to change visual -aspects of the application such as fonts, colors or even the general style, -so you can adapt the global aspect of *ViTables* -to what would be expected on your platform. - -From the :guilabel:`Plugins` page the plugins can be managed. You -can enable or disable the available plugins. Changes in this page will take effect -the next time you start *ViTables*. - -The :guilabel:`OK` button will apply the new settings and -make them permanent by saving them in the Windows registry, in a -configuration file (on Unix platforms) or in a plist file (on Mac OS X platforms). Even -if settings are stored in a plain text file editing it by hand is not -recommended. Some settings, like fonts or geometry settings [#f3]_, are stored in a way not really intended to be modified manually. - -Anyway it can be worth how settings are stored so let's do it. -The configuration file is divided into sections, labeled as -[section_name]. Every section is made of subsections -written as key/value pairs and representing the item that is being -customized. -Currently the following sections/subsections are available: - - [Geometry] HSplitter - the size of the horizontal splitter - - [Geometry] Layout - the position and size of toolbars and dock widgets - - [Geometry] Position - the position and size of the application window - - [Geometry] VSplitter - the size of the vertical splitter - - [HelpBrowser] Bookmarks - the list of current bookmarks of the help browser - - [HelpBrowser] History - the navigation history of the help browser - - [Logger] Font - the logger font - - [Logger] Paper - the logger background color - - [Logger] Text - the logger text color - - [Look] currentStyle - the style that defines the application look & feel. Available styles fit the most common platforms, i.e., Windows, Unix (Motif and SGI flavors), and Macintosh - - [Plugins] Enabled - the list of full paths of enabled plugins - - [Recent] Files - the list of files recently opened - - [Session] Files - the list of files and views that were open the last time *ViTables* was closed - - [Startup] lastWorkingDir - the last directory accessed from within *ViTables* via Open File dialog - - [Startup] restoreLastSession - the last working session is restored (if possible) which means that both files and leaves that were open in the last session will be reopen at application startup. - - [Startup] startupWorkingDir - possible values are *current*, and *last*. These values indicate how the application will setup the startup working directory. - - [Workspace] Background - the workspace background brush - -.. rubric:: Footnotes - -.. [#f3] Entries in the Geometry section allow for keeping the aspect, size and position of the application window between sessions. - +.. _configuration-chapter: + +Configuring ViTables +++++++++++++++++++++ + +As mentioned earlier, many aspects of the `ViTables` behaviour can be customized by you through the :menuselection:`Settings --> Preferences` command. + +It shows a dialog offering you several customization +possibilities. The dialog is made of three stacked pages, +:guilabel:`General`, :guilabel:`Look & Feel` and :guilabel:`Plugins`. + +The :guilabel:`General` page allows to change the `ViTables` behavior at startup. You can set the initial working directory to be that one from which `ViTables` is starting or to be the last used working directory. And you can recover your last working session. + +The :guilabel:`Look & Feel` page allows to change visual +aspects of the application such as fonts, colors or even the general style, so you can adapt the global aspect of `ViTables` to what would be expected on your platform. + +From the :guilabel:`Plugins` page the plugins can be managed. You can enable or disable the available plugins. Changes in this page will take effect the next time you start `ViTables`. + +The :guilabel:`OK` button will apply the new settings and +make them permanent by saving them in the Windows registry, in a configuration file (on Unix platforms) or in a plist file (on Mac OS X platforms). Even if settings are stored in a plain text file editing it by hand is not recommended. Some settings, like fonts or geometry settings [#f3]_, are stored in a way not really intended to be modified manually. + +Anyway it can be worth how settings are stored so let's do it. +The configuration file is divided into sections, labeled as +[section_name]. Every section is made of subsections written as key/value pairs and representing the item that is being +customized. Currently the following sections/subsections are available: + + [Geometry] HSplitter + the size of the horizontal splitter + + [Geometry] Layout + the position and size of toolbars and dock widgets + + [Geometry] Position + the position and size of the application window + + [Geometry] VSplitter + the size of the vertical splitter + + [HelpBrowser] Bookmarks + the list of current bookmarks of the help browser + + [HelpBrowser] History + the navigation history of the help browser + + [Logger] Font + the logger font + + [Logger] Paper + the logger background color + + [Logger] Text + the logger text color + + [Look] currentStyle + the style that defines the application look & feel. Available styles fit the most common platforms, i.e., Windows, Unix (Motif and SGI flavors), and Macintosh + + [Plugins] Enabled + the list of full paths of enabled plugins + + [Recent] Files + the list of files recently opened + + [Session] Files + the list of files and views that were open the last time `ViTables` was closed + + [Startup] lastWorkingDir + the last directory accessed from within `ViTables` via Open File dialog + + [Startup] restoreLastSession + the last working session is restored (if possible) which means that both files and leaves that were open in the last session will be reopen at application startup. + + [Startup] startupWorkingDir + possible values are *current*, and *last*. These values indicate how the application will setup the startup working directory. + + [Workspace] Background + the workspace background brush + +.. rubric:: Footnotes + +.. [#f3] Entries in the Geometry section allow for keeping the aspect, size and position of the application window between sessions. +