Editor

Text-editor-like functionality for programatically manipulating raw text input and output data and converting this data into container objects. This class does not behave like a fully fledged text editor but does have some basic find, replace, insert, etc. functionality.

class exa.editor.Editor(path_stream_or_string, as_interned=False, nprint=30, name=None, description=None, meta={})[source]

An editor is a representation of a text file on disk that can be programmatically manipulated.

Text lines are stored in memory; no files remain open. This class does not strive to be a fully fledged text editor rather a base class for converting input and output data from text on disk to some type of (exa framework) container object (and vice versa).

>>> template = "Hello World!\nHello {user}"
>>> editor = Editor(template)
>>> editor[0]
'Hello World!'
>>> len(editor)
2
>>> del editor[0]
>>> len(editor)
1
>>> editor.write(fullpath=None, user='Alice')
Hello Alice
Tip:
Editor line numbers use a 0 base index. To increase the number of lines displayed by the repr, increase the value of the nprint attribute.

Warning

For large text with repeating strings be sure to use the as_interned argument.

name

str

Data/file/misc name

description

str

Data/file/misc description

meta

dict

Additional metadata as key, value pairs

nrpint

int

Number of lines to display when printing

cursor

int

Line number position of the cusor (see find_next_any() and find_next_string())

write(path=None, *args, **kwargs)[source]

Perform formatting and write the formatted string to a file or stdout.

Optional arguments can be used to format the editor’s contents. If no file path is given, prints to standard output.

Parameters:
  • path (str) – Full file path (default None, prints to stdout)
  • *args – Positional arguments to format the editor with
  • **kwargs – Keyword arguments to format the editor with
format(*args, inplace=False, **kwargs)[source]

Format the string representation of the editor.

Parameters:inplace (bool) – If True, overwrite editor’s contents with formatted contents
head(n=10)[source]

Display the top of the file.

Parameters:n (int) – Number of lines to display
tail(n=10)[source]

Display the bottom of the file.

Parameters:n (int) – Number of lines to display
append(lines)[source]
Parameters:lines (list) – List of line strings to append to the end of the editor
prepend(lines)[source]
Parameters:lines (list) – List of line strings to insert at the beginning of the editor
insert(lines={})[source]

Insert lines into the editor.

Note

To insert before the first line, use preappend() (or key 0); to insert after the last line use append().

Parameters:lines (dict) – Dictionary of lines of form (lineno, string) pairs
remove_blank_lines()[source]

Remove all blank lines (blank lines are those with zero characters).

delete_lines(lines)[source]

Delete all lines with given line numbers.

Parameters:lines (list) – List of integers corresponding to line numbers to delete
find(*strings)[source]

Search the entire editor for lines that match the string.

Parameters:*strings – Any number of strings to search for
Returns:results (dict) – Dictionary of string key, line values.
find_next(string)[source]

From the editor’s current cursor position find the next instance of the given string.

Parameters:
  • string (str) – String to search for from the current cursor position.
  • reverse (bool) – Search in reverse (default false)
Returns:

tup (tuple) – Tuple of cursor position and line or None if not found

Note

This function cycles the entire editor (i.e. cursor to length of editor to zero and back to cursor position).

regex(*patterns, line=False)[source]

Search the editor for lines matching the regular expression.

Parameters:
  • *patterns – Regular expressions to search each line for
  • line (bool) – Return the whole line or the matched groups (groups default)
Returns:

results (dict) – Dictionary of pattern keys, line values (or groups - default)

replace(pattern, replacement)[source]

Replace all instances of a pattern with a replacement.

Parameters:
  • pattern (str) – Pattern to replace
  • replacement (str) – Text to insert
pandas_dataframe(start, stop, ncol)[source]

Returns the result of tab-separated pandas.read_csv on a subset of the file.

Parameters:
  • start (int) – line number where structured data starts
  • stop (int) – line number where structured data stops
  • ncol (int or list) – the number of columns in the structured data or a list of that length with column names
Returns:

pd.DataFrame – structured data

variables

Display a list of templatable variables present in the file.

Templating is accomplished by creating a bracketed object in the same way that Python performs string formatting. The editor is able to replace the placeholder value of the template. Integer templates are positional arguments.

classmethod from_file(path, **kwargs)[source]

Create an editor instance from a file on disk.

classmethod from_stream(f, **kwargs)[source]

Create an editor instance from a file stream.

classmethod from_string(string, **kwargs)[source]

Create an editor instance from a string template.

exa.editor.lines_from_file(path, as_interned=False)[source]

Create a list of file lines from a given filepath.

Parameters:
  • path (str) – File path
  • as_interned (bool) – List of “interned” strings (default False)
Returns:

strings (list) – File line list

exa.editor.lines_from_stream(f, as_interned=False)[source]

Create a list of file lines from a given file stream.

Parameters:
  • ( (f) – class:`~io.TextIOWrapper): File stream
  • as_interned (bool) – List of “interned” strings (default False)
Returns:

strings (list) – File line list

exa.editor.lines_from_string(string, as_interned=False)[source]

Create a list of file lines from a given string.

Parameters:
  • string (str) – File string
  • as_interned (bool) – List of “interned” strings (default False)
Returns:

strings (list) – File line list

Trait Supporting Data Objects

The DataFrame is an extension of the DataFrame object. It provides additional methods for creating traits.

Note

For further information on traits, see widget.

Additionally, DataFrame and related objects (e.g Field) provide attributes for defining their index and column names. This has the effect of creating relationships between different dataframes. They can be grouped into three types:

  1. index name (df1) matches index name (df2)
  2. index name (df1) matches column name (df2)
  3. column name (df1) matches column name (df2)

Note

These types correspond to one to one, one to many, and many to many relational types, respectively.

Finally, the objects contained in this module provide convenience methods for handling categorical data.

See also

For information about traits and how they allow enable dynamic visualizations see widget. For usage of numerical objects see container.

class exa.numerical.Numerical[source]

Base class for Series, DataFrame, and Field objects, providing default trait functionality, shortened string representation, and in memory copying support.

copy(*args, **kwargs)[source]

Create a copy without mangling the (class) type.

class exa.numerical.Series(*args, **kwargs)[source]

Trait supporting analogue of Series.

import numpy as np

class MySeries(Series):
    """Example usage of the exa.Series object."""
    _sname = 'data'
    _iname = 'data_index'
    _precision = 2

s = MySeries(np.random.rand(10**5))
traits = s._update_traits()
type(traits)    # dict containing "myseries_values" as a Unicode trait
class exa.numerical.DataFrame(*args, **kwargs)[source]

Trait supporting analogue of DataFrame.

class exa.numerical.Field(*args, field_values=None, **kwargs)[source]

A field is composed of the field definition (“field_data”) and values ( “field_values”). Field data define the shape and discretization of a field. Field values are scalar magnitudes (or vectors) that describe the field at each discretized point in space.

copy(*args, **kwargs)[source]

Copy the field dataframe, including the field values

memory_usage()[source]

Get the combined memory usage of the field data and field values.

class exa.numerical.Field3D(*args, field_values=None, **kwargs)[source]

Dataframe for storing dimensions of a scalar or vector field of 3D space.

Column Type Description
nx int number of grid points in x
ny int number of grid points in y
nz int number of grid points in z
ox float field origin point in x
oy float field origin point in y
oz float field origin point in z
xi float First component in x
xj float Second component in x
xk float Third component in x
yi float First component in y
yj float Second component in y
yk float Third component in y
zi float First component in z
zj float Second component in z
zk float Third component in z

Note

Each field should be flattened into an N x 1 (scalar) or N x 3 (vector) series or dataframe respectively. The orientation of the flattening should have x as the outer loop and z values as the inner loop (for both cases). This is sometimes called C-major order, C-style order, and has the last index changing the fastest and the first index changing the slowest.

See also

Field

class exa.numerical.SparseSeries(data=None, index=None, sparse_index=None, kind='block', fill_value=None, name=None, dtype=None, copy=False, fastpath=False)[source]

Trait supporting sparse series.

class exa.numerical.SparseDataFrame(*args, **kwargs)[source]

Trait supporting sparse dataframe.

Container

The BaseContainer class is the primary object for data processing, analysis, and visualization. Containers are composed of n-dimensional spreadsheet-like (see numerical) objects whose columns contain data for 2D and 3D visualization.

The BaseContainer is akin to a HDFStore in that it is a container for dataframes (and saves to an HDF5 file). It is different in that it provides visualization tools access to the data contained via automated JSON strings, transferrable between languages.

See also

container and widget

class exa.container.Container(name=None, description=None, meta=None, **kwargs)[source]

Container class responsible for all features related to data management.

copy(**kwargs)[source]

Create a copy of the current object.

concat(*args, **kwargs)[source]

Concatenate any number of container objects with the current object into a single container object.

See also

For argument description, see concat().

slice_by_indices(key)[source]

Slice the container by series or dataframe index.

Warning

Does not make a copy, must call the .copy() method on the resulting container if a copy is needed.

slice_by_cardinal_axis(key)[source]

Slice the container according to its cardinal axis.

See also

Note the warning in slice_by_indices().

info()[source]

Display information about the container’s objects.

Note

Sizes are reported in bytes.

memory_usage()[source]

Estimate the memory usage of the entire container.

network()[source]

Display information about the container’s object relationships.

Note

Due to quirks of plotting, rerunning this command until a “pleasing” visual is generated may be useful.

save(path)[source]

Save the container as an HDF5 archive.

Parameters:path (str) – Path where to save the container
classmethod load(pkid_or_path=None)[source]

Load a container object from a persistent location or file path.

Parameters:pkid_or_path – Integer pkid corresponding to the container table or file path
Returns:container – The saved container object
class exa.container.TypedMeta[source]

This metaclass creates statically typed class attributes using the property framework.

class TestMeta(TypedMeta):
    attr1 = (int, float)
    attr2 = DataFrame

class TestClass(metaclass=TestMeta):
    def __init__(self, attr1, attr2):
        self.attr1 = attr1
        self.attr2 = attr2

The above code dynamically creates code that looks like the following:

class TestClass:
    @property
    def attr1(self):
        return self._attr1

    @attr1.setter
    def attr1(self, obj):
        if not isinstance(obj, (int, float)):
            raise TypeError('attr1 must be int')
        self._attr1 = obj

    @attr1.deleter
    def attr1(self):
        del self._attr1

    @property
    def attr2(self):
        return self._attr2

    @attr2.setter
    def attr2(self, obj):
        if not isinstance(obj, DataFrame):
            raise TypeError('attr2 must be DataFrame')
        self._attr2 = obj

    @attr2.deleter
    def attr2(self):
        del self._attr2

    def __init__(self, attr1, attr2):
        self.attr1 = attr1
        self.attr2 = attr2
static create_property(name, ptype)[source]

Creates a custom property with a getter that performs computing functionality (if available) and raise a type error if setting with the wrong type.

Note

By default, the setter attempts to convert the object to the correct type; a type error is raised if this fails.

Widget

Functionality for using Jupyter notebook extensions to visualize data speficic containers. This module requires the infrastructure provided by the traitlets and ipywidgets packages.

class exa.widget.Widget(*pargs, **kwargs)[source]

Base widget class for Jupyter notebook widgets provided by exa. Standardizes bidirectional communication handling between notebook extensions’ frontend JavaScript and backend Python.

class exa.widget.ContainerWidget(container, *args, **kwargs)[source]

Jupyter notebook widget representation of an exa Container. The widget accepts a (reference to a) container and parameters and creates a suitable display. By default a container displays an interactive graphic containing information provided by info() and network().

See also

container, container

exa.widget.install_notebook_widgets(pkg_nbext, sys_nbext, verbose=False)[source]

Convenience wrapper around install_nbextension() that organizes notebook extensions for exa and related packages in a systematic fashion.

Parameters:
  • pkg_nbext (str) – Path to the “_nbextension” directory in the source
  • sys_nbext (str) – Path to the system “nbextensions” directory
  • verbose (bool) – Verbose installation