Welcome to melancholia’s documentation!

‘melancholia’ - print a NumPy array to a file or a variable in a human-readable way.

About ‘melancholia’

‘melancholia’ is a Python module which can be used to write a NumPy array in a format which is easy to read by humans. An array may be printed into a string variable or into a file.

‘melancholia’ checks the number of dimensions in an array and act acordignly - if an array is one dimensional, it is printed as a vector, if an array is two dimensional, it is printed as a matrix. In the latter, the first dimension of array are rows, the second diemension are columns.

‘melancholia’ takes care of:

  1. printing indices of vector entries, or matrix rows and columns
  2. printing entries of an array in a requested format
  3. addiing none or extra lines between the printed lines
  4. line wrapping, if needed
  5. printing delimiters between entries (default or custom)
  6. printing array names and dimensions (if requested)

Note

In the current version (v1.0) ‘melancholia’ supports 1-dimensional and 2-dimensional NumPy arrays. 1 dimensional arrays can be printed vertically or horizontally.

Warning

In the current version (v1.0) ‘melancholia’ does not support complex numbers.

Download and Install

melancholia’s sources are availalble to download from GitHub. To install ‘melancholia’ on your computer type:

$ python setup.py install

in the root directory of the melancholia’s source tree.

License

‘melancholia’ is a (very) free software, it is licensed under BSD 2-clause license.

Author

‘melancholia’ was created and is maintained by Jacek Pierzchlewski (jap _at_ es dot aau dot dk) from Aalborg University.
‘melancholia’ is small side project to ‘IRfDUCS’ research project www.irfducs.org.

Writing an array to a string variable

Function printA which is implemented in ‘melancholia’, is able to write a NumPy array to a string variable. Below there is a list of examples of using the function. There are more examples in files example_1Darray.py and example_2Darray.py which can be found in examples/ directory. The first file contains examples of printing 1-dimensional arrays, the latter contains examples of printing 2-dimensional arrays.

Warning

Examples below use optional arguments to the printA function. ALL of the optional arguments to the printA function can be mixed.

The simplest usage

The simplest usage of printA function is in the example below. A 2-dimensional array is passed to the function as a sole argument:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA)
 print(strA)

which gives an output like:

_images/printA_simplest_example.png

Custom delimiter

It is possible to add a custom delimiter between entries of an array. Function argument ‘strDelimiter’ is used to define a delimiter:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, strDelimiter='...')
 print(strA)

The requested delimiter can be seen in the output:

_images/printA_delimiter.png

Horizontal printing of a 1D array

NumPy array with only one dimension is by default printed vertically:

 vA = np.random.rand(10)
 strA = melancholia.printA(mA)
 print(strA)

the result is:

_images/printA_1Dvertical.png

Function argument ‘bVert1D’ switches on/off vertical printing of a 1D array. To print a matrix horizontally, the argument must be zeroed:

 vA = np.random.rand(10)
 strA = melancholia.printA(mA, bVert1D=0)
 print(strA)

The array is now printed horizontally:

_images/printA_1Dhorizontal.png

No separation between rows of a 2D array

By default, there is always one line separation between rows of a 2D array. Function argument ‘iRowSpaces’ regulates the number of empty lines printed between the rows. To print an array in a more compressed way, without any rows separation, the argument must be zeroed:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, iRowSpaces=0)
 print(strA)

which gives an output like:

_images/printA_2Dnoseparation.png

Custom format of entries

By default, the custom format of entries is ‘%.6f’. Function argument ‘strFormat’ regulates the format of entries. Allowed formats are ‘%d’ (integer numbers), %.1f, %.2f, %.3f...etc. In the example below the entries are printed as integers:

 mA = np.random.randint(-10,10(10, 10))
 strA = melancholia.printA(mA, strFormat='%d')
 print(strA)

which gives an output like:

_images/printA_format.png

Array header

It is possible to add a header before an array is printed. Header contains information about the number of dimensions of an array, its shape and the type of entries. Function argument ‘bPrintHeader’ adds a header:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, bPrintHeader=1)
 print(strA)

now there is a header added before an array:

_images/printA_header.png

Array name in a header

Function argument ‘strArrayName’ is used to add an array name to the header of an array:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, strArrayName='mA', bPrintHeader=1)
 print(strA)

the array name is added to the header:

_images/printA_headername.png

Wrap lines after x characters

If a 2D array, or a 1D array printed horizontally, has many entries in a single row, it may be needed to wrap lines with the entries. By deafult, the line is wrapped after 4096 characters. This may be regulated using ‘iMaxCols’ argument. In the example below the lines are wrapped NOT LATER then after printing 89 characters. Note: new line ‘\n’ is treated as a character.

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, iMaxCols=89)
 print(strA)

the lines are now wrapped:

_images/printA_wrapAfterXCharacters.png

Wrap lines after x entries

With argument ‘iMaxEntr’ it is possible to regulate line wrapping so that the lines are wrapped after given number of printed entries:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, iMaxEntr=9)
 print(strA)

the lines are now wrapped after 9 printed entries:

_images/printA_wrapAfterXEntries.png

No separation between the wrapped lines

If an array is printed with line wrapping, by default there is one line separation between wrapped lines. Argument ‘iLineSpaces’ is able to regulate the spacing between the lines. To remove any separation between the wrapped lines, the argument ‘iLineSpaces’ must be zeroed:

 mA = np.random.rand(10, 10)
 strA = melancholia.printA(mA, iMaxEntr=9, iLineSpaces=0)
 print(strA)

the lines are now wrapped without any line separation:

_images/printA_wrapNoSeparation.png

Writing an array to a file

Function dumpA which is implemented in ‘melancholia’, is able to write a NumPy array to a string variable. It takes two required arguments: an array to be printed to a file and a filename. The function is in fact an overlay to the printA function, hence all of the arguments which can be used with printA function (described above) work with dumpA function. An example below writes an array to a array.txt file:

 mA = np.random.rand(10, 10)
 melancholia.dumpA(mA, strFile='array.txt')

File mode

By deafult the file is opened with mode ‘w’ (write). Argument ‘strMode’ can be used to open a file in the ‘a’ (append) mode:

 mA = np.random.rand(10, 10)
 melancholia.dumpA(mA, strFile='array.txt', strMode='a')

In the ‘a’ (append) mode array is added to the end of file, while in the ‘w’ write mode, a new file is created.

Warning

In the write mode, an existing file of a given name will be deleted and overwritten.

Indices and tables