Why use Bordado?

Why use Bordado?#

The main purpose of Bordado is to facilitate generating coordinates for evenly spaced points. These could be the coordinates of a regular grid, of points along a line, or of a profile. While you could do a lot of this with a combination of numpy.linspace and numpy.meshgrid, there are a few problems that Bordado solves:

  1. What if I want to specify the spacing between points instead of how many points?

  2. What if the spacing isn’t exactly a multiple of the interval?

  3. What was the order of arguments to numpy.meshgrid and what’s the difference between the difference indexing types?

  4. What if I want points along a straight line or great circle between two points?

On top of that, Bordado also offers other utilities like splitting points into blocks and rolling windows, calculating some nearest neighbor statistics, and more.

Let’s see how it works!

Importing the package#

Everything in Bordado is available through the bordado module. There are no submodules to import. We’ll usually alias the import to bd:

import bordado as bd

Tip

Checkout the “List of functions and classes (API)” for a full list of all that Bordado offers.

We’ll also import numpy to use for some comparisons.

import numpy as np

Generating evenly spaced points#

As a first taste, let’s see how to generate values between two extremes, but passing the spacing between values instead of the number of values:

values = bd.line_coordinates(0, 10, spacing=1)
print(values)

[ 0.  1.  2.  3.  4.  5.  6.  7.  8.  9. 10.]

Notice how both extremes are included, contrasting with numpy.arange:

values_arange = np.arange(0, 10, 1)
print(values_arange)

[0 1 2 3 4 5 6 7 8 9]

Another nice thing is that line_coordinates will round the spacing if it’s not a multiple of the interval, guaranteeing that the interval boundaries are always present:

values = bd.line_coordinates(0, 10, spacing=1.3)
print("Bordado:", values)

values_arange = np.arange(0, 10, 1.3)
print("Numpy:", values_arange)

Bordado: [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
Numpy: [0.  1.3 2.6 3.9 5.2 6.5 7.8 9.1]

We can also ask it to adjust the interval instead of the spacing:

values = bd.line_coordinates(0, 10, spacing=1.3, adjust="region")
print(values)

[-0.2  1.1  2.4  3.7  5.   6.3  7.6  8.9 10.2]

The same logic applies to regular grids with bordado.grid_coordinates, which generates the values and uses numpy.meshgrid appropriately:

x, y = bd.grid_coordinates(region=(0, 10, 10, 20), spacing=1.3)
print(x)
print(y)

[[ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]
 [ 0.    1.25  2.5   3.75  5.    6.25  7.5   8.75 10.  ]]
[[10.   10.   10.   10.   10.   10.   10.   10.   10.  ]
 [11.25 11.25 11.25 11.25 11.25 11.25 11.25 11.25 11.25]
 [12.5  12.5  12.5  12.5  12.5  12.5  12.5  12.5  12.5 ]
 [13.75 13.75 13.75 13.75 13.75 13.75 13.75 13.75 13.75]
 [15.   15.   15.   15.   15.   15.   15.   15.   15.  ]
 [16.25 16.25 16.25 16.25 16.25 16.25 16.25 16.25 16.25]
 [17.5  17.5  17.5  17.5  17.5  17.5  17.5  17.5  17.5 ]
 [18.75 18.75 18.75 18.75 18.75 18.75 18.75 18.75 18.75]
 [20.   20.   20.   20.   20.   20.   20.   20.   20.  ]]

Explore the rest!#

That’s a brief overview of the functionality in Bordado, but there’s plenty more! We recommend going through our Tutorial first. Then take a look at the “How To” and also the “List of functions and classes (API)” for documentation for each function.

Oh, and don’t forget to cite Bordado if you use it in a publication!

Have questions?

Please ask on any of the Fatiando a Terra community channels!

We’re also always looking for feedback and more people to get involved in the development. Leave us a message if that’s you.

Contents