General Description of RepTate

RepTate (Rheology of Entangled Polymers: Toolkit for Analysis of Theory & Experiment) is a software package for viewing, exchanging and analysing experimental data. Several of the classical and latest theories of polymer dynamics are included in RepTate, so they can be tested and fitted to the experimental data.

The software is designed in a modular way, so it is easy to extend to analyze new types of data and fit with new theories.

RepTate makes extensive use of the following packages and libraries:

  • Matplotlib: Text [1].

  • Scipy: Text [2].

  • Numpy: Text [3].

  • Qt and Pyqt: Text [4], Text [5].

Main RepTate Window

The main RepTate window is called the Application Manager and is a multiple document interface (MDI) (see Fig. 1). All the applications can be opened from the Application Manager and will reside inside it. At the top of the Application Manager there is a toolbar that allows to open different applications (label 1 in Fig. 1), load and save RepTate projects, read the help and exit RepTate. Currently open applications can are shown as tabs below the toolbar (label 2 in Fig. 1). By default, tabs are named after the application name and a number. The name can be changed by double-clicking on the tab.

../../_images/RepTate_Window.png

Fig. 1 Main RepTate window showing the most important elements in the user interface.

Applications have three main separate areas:

  • The plot, in the center, is where the experimental data files and theoretical fits are shown (label 4 in Fig. 1).

  • A vertical region at the right of the window, that allows to:

    • Select the current View (way of representing the data, label 3 in Fig. 1)

    • Open data Files and arrange them into different Datasets (label 5 in Fig. 1). Different Datasets are shown as tabs, named by default as “Set” + number. The name of a Dataset can be changed by double-clicking on the tab.

    • Create a Theory associated to a given Dataset and fit it (minimize the error with respect to the Files within that Dataset, label 7 in Fig. 1). Currently open theories are named after the theory name + a number. The name can be changed by double-clicking on the tab.

Files in the current DataSet are shown in a table, along with the main parameters that describe each file (label 6 in Fig. 1). Files can be added to a Dataset with the “Open Data File” button open (Ctrl+O) or by dragging them from the file explorer and dropping them on the RepTate window. In the Theory area, the parameters of the current theory are shown in a table, with their current value and error. A blue box below the table shows information during the calculation and fitting procedure (label 8 in Fig. 1)

By clicling on the “Data Inspection” button inspection (label 1 in Fig. 2), a new region on the left of the plot area is shown where the user can inspect the contents of a file, shift data and use the Tools. Two separate areas are shown:

../../_images/RepTate_Extended_Window.png

Fig. 2 Extended RepTate window showing file data and Tools.

  • A region (label 3 in Fig. 2) where the file contents are shown in a table. Above the table (label 2 in Fig. 2) there is a toolbar that allows the user to do some operations on the data (copy, paste, shift, etc).

  • A region (label 4 in Fig. 2) that lets the user apply different Tools to the current Dataset.

The data inspection and Tools region is hidden by default.

Operating with Datasets

When an new application is opened, a new tab is created in the Main RepTate window, showing an empty application with an empty dataset, no theories and the default view. New data files must be added to the dataset in order to use all the functionality of RepTate.

Structure of data files

Only text files that have the right extension and contain the expected data can be added to the current application. The general structure of the text files that can be read by RepTate is as follows (see the example below for a quick reference):

  • [Required] The first line contains a list of parameters that describe the contents of the data in the file, as a list of variables and values separated by semicolons. Typically, the parameters will describe the conditions (temperature, pressure, etc) at which the experiment was done, plus some additional parameters to characterize the material (chemistry, molecular weight, etc) and the author of the data. Some parameters are needed by some applications and theories (for example, the temperature in the TTS module) and RepTate will show a warning if their values are missing. The values of the parameters can be real numbers, integers or strings.

  • [Optional] Some additional text lines may be present in the file with further info about the experimental data (the date and location where the data was taken, the equipment, etc). These lines ignored by RepTate.

  • [Required] The data itself must be stored in the file as columns separated by spaces or tabs. The number of columns must be greater or equal than the number of columns required by the application, and in the expected order. Additional columns are discarded. For more information, check the documentation for each particular application.

var1=value1;var2=value2;var3=value3;...
Some text
# Some text
1.90165E+0      7.38023E+1      1.35152E+4
3.01392E+0      1.99063E+1      2.14834E+4
4.51700E+0      3.72861E+1      3.17756E+4
...             ...             ...

For more info about valid extensions and data structure inside the files, check the documentation for each application.

Adding files to datasets

There are two ways to add Files to the current application:

  • By dragging and dropping them from the system file explorer to the Application window (see Fig. 3).

  • By pressing the Open Data File button open (Ctrl+O). A file dialog is shown where one file or more files of the right type can be selected.

../../_images/dragdropfiles.gif

Fig. 3 Dragging and dropping some files to the RepTate window.

Importing data from Excel files

This feature is experimental and will be improved in the future. In the current version, when the user selects the button “Import from Excel” excel, under the button open menu, a dialog is shown that allows the user to (see Fig. 4):

  • select the Excel file

  • set the file parameters

  • select Excel Sheet that contains the data

  • set the number of rows in the Excel sheet that must be skipped

  • set the columns in the Excel sheet that correspond to the columns that the RepTate application expects to read.

../../_images/ImportfromExcel.png

Fig. 4 Importing data from an Excel file into the LVE application.

Sorting Files in a Dataset

The files in a Dataset can be sorted by name or parameter value, in increasing and decreasing order, by clicking in the corresponding column header. Clicking several times on the same header will invert the sorting order. A small arrow next to a column header name will indicate how the files in the current Dataset are sorted (see Fig. 5).

../../_images/SortingFiles.png

Fig. 5 A Dataset with files sorted by decreasing value of the gdot parameter.

When the files in a Dataset are sorted, the colours assigned to each file are also changed. The order of the colours is assigned by the selected palette. The number of colours in some palettes is limited and, therefore, if the number of files exceed the number of colours available, some files may end up having the same colour.

Viewing/Hiding Files

Each file in a Dataset can be in the enabled (checked) or disabled state (unchecked, see Fig. 6). When files are disabled, they are not shown in the current view and they are not considered during theory calculation and fitting.

../../_images/disablingfiles.gif

Fig. 6 Enabling/disabling files in a Dataset.

Showing/Editing file parameters

By double-clicking on a file name in the Dataset area, it is possible to view/edit the parameters of the file. A dialog will open, where all the file parameters are shown and all their values can be viewed/edited.

Creating new datasets

Sometimes, it is convenient to load data into separate data sets, because the data correspond to different materials or the experiments have been done in different conditions. In order to create a new empty dataset, the user must click on the “Create an empty DataSet” button newdataset (Ctrl+N) in the DataSet toolbar. By default, new DataSets are named Set i, where i is an integer that starts from 1 and increments as new DataSets are opened. The DataSet name can be changed by double-clicking on the DataSet tab.

When there are more than one Dataset in the current application, the user can switch Datasets by clicking on the corresponding tab. By default, RepTate only plots the data in the currently active Dataset. If the button “View all Datasets simultaneously” button viewall is clicked, all the data in all open Datasets is shown.

Adding Dummy files to datasets

In some cases, the user may want to explore the results of a given theory but he/she does not have any experimental data files available. Since the theories are only applied to the active files of the Dataset that owns the theory, it is convenient to be able to create empty files with parameters that span some range of values of interest (for example, the user may be interested in exploring the results of some theory when the molecular weight of the samples is changed). In RepTate, this can be done by adding Dummy files, in the submenu under the “Open Data File” button.

When the “Add Dummy files” button is clicked, a dialog is shown allowing the user to configure how the files are going to be generated (see Fig. 7):

  • The parameter(s) that are going to be changed systematically in the dummy files. By default, the possible parameters are selected from the list of important parameters, defined for every application. By ticking the check-box next to a parameter, it is selected.

  • The range of values over which the parameter will be swept, which is defined by a minimum value, a maximum value, the number of points and scale (linear or logarithmic) that will be used to separate the points between the minumum and the maximum.

  • The data in the dummy files is arbitrary. The user can select the range, number of points and scale (linear or log) in the dummy file for the first column (which frequently will act as the x-coordinate in views), as well as the default y value for the remaining columns.

  • The user can also input the chemistry, which may be interesting if a certain material is available in the Materials Database.

../../_images/DummyFiles.png

Fig. 7 Dialog for adding Dummy files to a DataSet.

Reloading the data

Some times, the user may be representing some data that is being updated in real time (because an experiment or simulation is running at the same time as the RepTate session). In this cases, it is interesting to update the data in RepTate by reading again the file. This can be done by clicking the button “Reload Data Files & Theories” filereload (Ctrl+R).

Operating with Views

The data read from the files can be represented in several different ways, which are different for each application. In RepTate, the way some experimental or theory data are represented is referred to as the View.

There are two different ways to select a View:

  • From the drop-down box at the top-right corner of the Application window. By clicking on the box, a menu is shown with all the Views that are defined in the current application. By hovering the mouse over the View names, some additional information may be displayed.

  • By right-clicking on the plot area, a menu is displayed. By selecting the submenu “Select View”, the user can select the view from a list (the contents of the list are exactly the same as in the drop-down box).

At the left of the drop-down box, there is a small up-down selector that allows the user to change the number of graphs that are shown in the plot area. When there are more than one graph, a small set of tabs is shown on the left of the Plot area (see Fig. 8). The number of tabs is equal to the number of Views + 1. The tab 0 shows all views and the other tabs show a single view.

../../_images/ManyViews.png

Fig. 8 Plot area showing 4 different views and the tabs to switch from all to particular views (left).

Most Applications in RepTate show just one graph by default.

The data, as represented by the current View/Views, can be saved to a text file by clicking on the button saveview at the right of the View combo box.

Plot Area

The plot area shows the graphical representation of the data files in the current Dataset (or all the Datasets in the current application, if the “View all Datasets simultaneously” button viewall is clicked). Several operations can be done in the plot area:

  • By clicking on a data point, a label is shown with its (\(x\), \(y\)) coordinates, with respect to the current View (label 1 in Fig. 9). The label can be hidden by clicking on it again.

  • By right-clicking on the plot area and dragging the mouse, the user can zoom to an specific region of the plot.

  • By using the mouse wheel, the user can zoom in or out in the plot.

  • By right-clicking on the plot, a menu is shown with the following operations (label 3 in Fig. 9):
    • The chart can be copied to the clipboard as an image. The image can be pasted on any other program (such as Microsoft Word or Powerpoint)

    • The chart can be saved to an image file, using different formats (png, pdf, etc).

    • An annotation label can be added to the plot (label 2 in Fig. 9). LaTeX commands can be used in the text of the annotation. Annotation labels can be moved around by dragging them with the mouse and edited by double-clicking on them.

    • The view can be reset to the default zoom.

    • The view can be changed to any of the available views in the current application.

../../_images/Plot_Area.png

Fig. 9 Plot area showing data point coordinates (1), annotations (2) and pop-up menu (3).

Additional view options can be set by clicking on the “Show/Hide Figure Toolbar” button figuretoolbar on the Dataset area. The x-y ranges can be fixed by clicking on the “Lock XY axes” in the Dataset area.

Changing the Plot Properties

Most of the visual aspects of the plot (lines, symbols, axes labels, legend, etc) can be changed, by clicking the “Plot Settings” button plotsettings (Ctrl+M) in the Dataset area. A dialog is shown with different tabs, each one dedicated to a different aspect of the plot.

  • Data: in this tab, the user can select how the experimental data loaded in the Dataset is shown on the current view (see Fig. 10). By default, the experimental data is always shown as symbols, and the user can select the symbol type, size and colour. The different files in the Dataset can be shown with the same or different symbols and the colour can be set by selecting from a list of available colour palettes. Alternatively, the color can be fixed for all files or selected from a gradient, interpolating from Colour1 (which is used for the first file in the current Dataset) to Colour2 (for the last file).

../../_images/PlotStyleData.png

Fig. 10 Changing the Plot properties of the data.

  • Theory: the line type, width and colour can be selected (fixed or the same colour as the data).

  • Legend: here, the user can select if he/she wants to show the legend in the current plot, along with its location, font and other properties

such as the label that will be used to represent the data (see Fig. 11). For example, if the files in the current Dataset have the parameter Mw defined with a value, it can be used as the legend label by filling the Legend Labels field with the text “Mw = [Mw]”.

  • Annotations: here, the default properties of annotations (colour, font, opacity, etc) can be set. All new notations will have these properties. Individual annotation properties can be changed by double-clicking on the text of a particular annotation.

../../_images/PlotStyleLegend.png

Fig. 11 Changing the style of the legend.

  • Axes: the font of the labels and the colour of the labels and axes can be changed. Also, the user can choose whether to show grid lines or not.

As an example, a plot of LVE data with different graphical settings is shown in Fig. 11.

../../_images/PlotStyleChanged.png

Fig. 12 Example of a plot of LVE data where some of the default graphical properties have been changed.

Inspecting the Data

When the user clicks the button “Inspect contents of data files” inspection (Ctrl+I) in the Dataset area, a new panel is shown on the left side of the application window. In this panel, some operations can be done on the data, like checking the contents, copy and pasting data, shifting the curves around by dragging them with the mouse or applying Tools to the data.

View the current file data

When a file in the current Dataset is selected with the mouse, the corresponding plot is highlighted and the contents of the file are shown in the data inspection table (if the data inspection table is shown, see Fig. 13).

../../_images/DataInpection.png

Fig. 13 Inspecting the contents of the selected file.

Copy/Paste data

The data shown in the inspection data table can be copied as text (columns separated by tabs) by selecting the corresponding cells, columns or rows from the table and pressing the button “Copy” in the data inspaction area. The copied data can be pasted in another application like Excel or Matlab, or even to a different file by pressing the button “Paste” in the data inspection area.

Shift the data

Sometimes it may be convenient to compare features of two different data files that are represented in the same plot. For example, one may be interested in comparing the different terminal regions of G’ data of samples of the same polymer with different molecular weight. RepTate allows the user to shift the data vertically and/or horizontally by pressing the buttons “Shift the selected curve vertically” shiftvertical and/or “Shift the selected curve horizontally” shifthorizontal, respectively, in the data inspection area. Once the user finishes shifting the curves, he/she can check, save and reset the values of the shift factors by clicking on the corresponding buttons in the data inspection area. The whole procedure is summarized in Fig. 14.

../../_images/shiftingfiles.gif

Fig. 14 Shifting some curves horizontally and viewing the shift factors.

When the axis with respect to which the shifting is being carried out is in logarithmic scale, the shift factor represents the decimal logarithm of the factor by which one should multiply the data in order to obtain the observed shift. When the axis is in linear scale, the shift factor is just the linear shift needed to obtain the observed shift.

Fitting a theory

One of the most important features of RepTate is the ability to easily fit a theory to a set of experimental data files. The available theories in each RepTate application are described and discussed in the documentation corresponding to each application. Here, we give a short summary of the general ideas about how theories are handled in RepTate.

It is important to note that, in RepTate, theories belong to Datasets, i.e. they are applied only to the data files in the Dataset under which the theory was created.

Opening a new Theory

Below the Dataset table that contains the files, there is a toolbar for operating with theories. First, the user should select a theory from the list available in the drop-down menu. Once the right theory is selected, a new instance of the theory can be created by clicking on the “Create Selected Theory” button newtheory (Alt+N). New theories are shown as tabs below the theory toolbar. By default, theories are named after a combination of capital letters selected after the theory name + an index number. The name of any theory can be changed by double clicking on the corresponding tab.

Viewing/Editing Parameter values and options

When a new theory instance is created, a new tab opens in which two clearly separate areas can be seen (see Fig. 15):

  • A table that lists the parameters of the theory, with their current value and, if the theory has been fitted to some experimental data, the error of the fitting.

  • A text area with a light blue background that shows all the relevant information during the calculation and fitting of the theory, as well as any citation information that is relevant to the current theory.

../../_images/TheoryArea.png

Fig. 15 A theory with the parameters table and the log area (with cyan background).

Theory parameters can be shown in the table in three possible states:

  • Checked: the parameter value will be optimized during the fitting procedure.
    • Unchecked: the value of the parameter will not be optimized (it will remain constant during the next fitting procedure).

    • Grayed out or partially checked: the parameter cannot be optimized. This is intended for parameters, like exponents of scaling factors, that take well known values. Typically, grayed parameters take their value from a set of prescribed discrete values.

Theory parameters have properties, and some of these properties are very important during theory fitting. In order to check and edit the properties of parameters, the user can double-click on any parameter name. Then, a dialog is shown with a tablist, with a tab for each parameter of the theory and the current properties of each parameter (see Fig. 16). The most important properties of a parameter are:

  • name: the short name of the parameter. It is hardcoded into the theory and cannot be changed.

  • description: a short description of the parameter. It is hardcoded into the theory and cannot be changed.

  • type: the numerical type of the value of the parameter. It can be real, integer, discrete_real (its value is selected from a discrete list of real values), discrete_integer (discrete list of integer values) and boolean.

  • opt_type: indicates whether the parameter value will be optimized during the fitting procedure or not. Possible states are: opt (will be optimized), nopt (will not be optimized) and const (cannot be optimized).

  • min_value: minimum value that the parameter can adopt. If the parameter is not bounded, the minimum value is -inf.

  • max_value: maximum value that the parameter can adopt. If the parameter is not bounded, the maximum value is inf. The bounds should not be exceeded during minimization. If the user inputs manually a value that is outside the bounds, RepTate will issue a warning and set the parameter value to the bound that has been exceeded.

  • display_flag: whether the parameter will be shown in the parameter table or not.

  • discrete_values: comma-separated list of values that the parameter can adopt. Only relevant if the parameter type is either discrete_real or discrete_integer.

../../_images/ParameterProperties.png

Fig. 16 Dialog for viewing/editing parameter properties.

Calculating the theory

When the button “Calculate Theory” calculatetheory (Alt+C) is pressed, the theory is calculated using the current values of the theory parameters and for all the files in the current dataset. Since the theory may use some of the file parameters, the result of applyting the theory to each files will be different. By default, the theory is calculated exactly in the same x points as the corresponding data file. This can be changed by editing the file parameters and selecting “Extra Theory Range”.

When the theory calculation is done, some interesting information is shown in the theory log area (see Fig. 17). By default, the information displayed contains:

  • A table with the list of files that theory has been applied to, with the error (calculated as the residual sum of squares, RSS) and the number of points of each file.

  • The total error (the weighted sum of the RSS errors of all the files) and the total number of points.

  • The Bayesian Information Criterion (BIC), defined as \(BIC = n \log(RSS/n)+ p\log(n)\), where n is the number of data points and p is the number of free fitting parameters. In general, the model with the lowest BIC value should be preferred.

  • Some additional information may be shown by some theories (for example, in Fig. 17, the Likhtman-McLeish theory shows some tube related values for each file).

  • The time it took to calculate the theory, in seconds.

  • The relevant literature that the user should cite if he/she intends to use the results from the theory. The journal articles are shown as links that can be clicked in order to visit the publisher web.

../../_images/TheoryCalcLog.png

Fig. 17 Example of the information displayed after a theory calculation is finished.

Fitting the theory

Todo

Complete this section

How the fitting is done

Todo

Complete this section

Setting x and y-range limits to the fitting graphically

Todo

Complete this section

Fitting options

Todo

Complete this section

Saving theory predictions

Todo

Complete this section

Copying/Pasting theory parameters

Todo

Complete this section

Showing all theories applied to current DataSet

Todo

Complete this section

Using the Tools

  • Opening a New Tool

  • How the Tooks work

  • Shuffling the Tools

Todo

Complete this section

Working with projects

  • Saving the current RepTate session to a project file

  • Opening an existing RepTate project file

  • Sharing projects with collaborators

Todo

Complete this section

References

1

J. D. Hunter. Matplotlib: a 2d graphics environment. Computing In Science & Engineering, 9(3):90–95, 2007. doi:10.1109/MCSE.2007.55.

2

Eric Jones, Travis Oliphant, Pearu Peterson, and others. SciPy: open source scientific tools for Python. 2001–. [Online; accessed 2018-05-04]. URL: http://www.scipy.org/.

3

Travis E. Oliphant. Guide to NumPy. Provo, UT, March 2006. [Online; accessed 2018-05-04]. URL: http://web.mit.edu/dvp/Public/numpybook.pdf.

4

Riverbank Computing. Pyqt. 2009–. [Online; accessed 2018-05-04]. URL: https://en.wikipedia.org/wiki/PyQt.

5

The Qt Company. Qt. 1991–. [Online; accessed 2018-05-04]. URL: https://en.wikipedia.org/wiki/PyQt.