Skip to content

Use consistently 1-D, 2-D, or 3-D in 'session.py' and 'conversion.py' (with hyphen and capitalized) #2307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jan 5, 2023
Merged

Use consistently 1-D, 2-D, or 3-D in 'session.py' and 'conversion.py' (with hyphen and capitalized) #2307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0158bd8
Use consistently 'x-D' in 'session.py'
yvonnefroehlich Jan 4, 2023
3ef4f11
Use consistently 'x-D' in 'conversion.py'
yvonnefroehlich Jan 4, 2023
d4d5d04
Fix typo in 'session.py'
yvonnefroehlich Jan 4, 2023
d1dcbf9
Fix line length in 'session.py'
yvonnefroehlich Jan 4, 2023
ef30314
Add commas in 'session.py'
yvonnefroehlich Jan 4, 2023
6934eb6
Some improvements
yvonnefroehlich Jan 4, 2023
3a3ce88
Use 'np.str_' not 'np.str' in 'session.py' (code review)
yvonnefroehlich Jan 5, 2023
95a3e21
Merge branch 'main' into fix-typos-16
yvonnefroehlich Jan 5, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 12 additions & 12 deletions pygmt/clib/conversion.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@

def dataarray_to_matrix(grid):
"""
Transform an xarray.DataArray into a data 2D array and metadata.
Transform an xarray.DataArray into a data 2-D array and metadata.

Use this to extract the underlying numpy array of data and the region and
increment for the grid.
Expand All @@ -31,8 +31,8 @@ def dataarray_to_matrix(grid):

Returns
-------
matrix : 2d-array
The 2D array of data from the grid.
matrix : 2-D array
The 2-D array of data from the grid.
region : list
The West, East, South, North boundaries of the grid.
inc : list
Expand Down Expand Up @@ -127,24 +127,24 @@ def dataarray_to_matrix(grid):

def vectors_to_arrays(vectors):
"""
Convert 1d vectors (lists, arrays or pandas.Series) to C contiguous 1d
Convert 1-D vectors (lists, arrays, or pandas.Series) to C contiguous 1-D
arrays.

Arrays must be in C contiguous order for us to pass their memory pointers
to GMT. If any are not, convert them to C order (which requires copying the
memory). This usually happens when vectors are columns of a 2d array or
memory). This usually happens when vectors are columns of a 2-D array or
have been sliced.

If a vector is a list or pandas.Series, get the underlying numpy array.

Parameters
----------
vectors : list of lists, 1d arrays or pandas.Series
vectors : list of lists, 1-D arrays, or pandas.Series
The vectors that must be converted.

Returns
-------
arrays : list of 1d arrays
arrays : list of 1-D arrays
The converted numpy arrays

Examples
Expand Down Expand Up @@ -179,12 +179,12 @@ def as_c_contiguous(array):

Parameters
----------
array : 1d array
array : 1-D array
The numpy array

Returns
-------
array : 1d array
array : 1-D array
Array is C contiguous order.

Examples
Expand Down Expand Up @@ -252,15 +252,15 @@ def kwargs_to_ctypes_array(argument, kwargs, dtype):

def array_to_datetime(array):
"""
Convert an 1d datetime array from various types into pandas.DatetimeIndex
Convert an 1-D datetime array from various types into pandas.DatetimeIndex
(i.e., numpy.datetime64).

If the input array is not in legal datetime formats, raise a "ParseError"
exception.

Parameters
----------
array : list or 1d array
array : list or 1-D array
The input datetime array in various formats.

Supported types:
Expand All @@ -272,7 +272,7 @@ def array_to_datetime(array):

Returns
-------
array : 1d datetime array in pandas.DatetimeIndex (i.e., numpy.datetime64)
array : 1-D datetime array in pandas.DatetimeIndex (i.e., numpy.datetime64)

Examples
--------
Expand Down
77 changes: 39 additions & 38 deletions pygmt/clib/session.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -717,7 +717,7 @@ def _check_dtype_and_dim(self, array, ndim):
"""
# check the array has the given dimension
if array.ndim != ndim:
raise GMTInvalidInput(f"Expected a numpy 1d array, got {array.ndim}d.")
raise GMTInvalidInput(f"Expected a numpy 1-D array, got {array.ndim}-D.")

# check the array has a valid/known data type
if array.dtype.type not in DTYPES:
Expand All @@ -732,7 +732,7 @@ def _check_dtype_and_dim(self, array, ndim):

def put_vector(self, dataset, column, vector):
r"""
Attach a numpy 1D array as a column on a GMT dataset.
Attach a numpy 1-D array as a column on a GMT dataset.

Use this function to attach numpy array data to a GMT dataset and pass
it to GMT modules. Wraps ``GMT_Put_Vector``.
Expand All @@ -741,11 +741,11 @@ def put_vector(self, dataset, column, vector):
first. Use ``family='GMT_IS_DATASET|GMT_VIA_VECTOR'``.

Not all numpy dtypes are supported, only: int8, int16, int32, int64,
uint8, uint16, uint32, uint64, float32, float64, str\_ and datetime64.
uint8, uint16, uint32, uint64, float32, float64, str\_, and datetime64.

.. warning::
The numpy array must be C contiguous in memory. If it comes from a
column slice of a 2d array, for example, you will have to make a
column slice of a 2-D array, for example, you will have to make a
copy. Use :func:`numpy.ascontiguousarray` to make sure your vector
is contiguous (it won't copy if it already is).

Expand All @@ -756,15 +756,15 @@ def put_vector(self, dataset, column, vector):
:meth:`pygmt.clib.Session.create_data`.
column : int
The column number of this vector in the dataset (starting from 0).
vector : numpy 1d-array
The array that will be attached to the dataset. Must be a 1d C
vector : numpy 1-D array
The array that will be attached to the dataset. Must be a 1-D C
contiguous array.

Raises
------
GMTCLibError
If given invalid input or ``GMT_Put_Vector`` exits with status !=
0.
If given invalid input or ``GMT_Put_Vector`` exits with
status != 0.
"""
c_put_vector = self.get_libgmt_func(
"GMT_Put_Vector",
Expand Down Expand Up @@ -796,7 +796,7 @@ def put_vector(self, dataset, column, vector):

def put_strings(self, dataset, family, strings):
"""
Attach a numpy 1D array of dtype str as a column on a GMT dataset.
Attach a numpy 1-D array of dtype str as a column on a GMT dataset.

Use this function to attach string type numpy array data to a GMT
dataset and pass it to GMT modules. Wraps ``GMT_Put_Strings``.
Expand All @@ -806,7 +806,7 @@ def put_strings(self, dataset, family, strings):

.. warning::
The numpy array must be C contiguous in memory. If it comes from a
column slice of a 2d array, for example, you will have to make a
column slice of a 2-D array, for example, you will have to make a
copy. Use :func:`numpy.ascontiguousarray` to make sure your vector
is contiguous (it won't copy if it already is).

Expand All @@ -818,15 +818,15 @@ def put_strings(self, dataset, family, strings):
family : str
The family type of the dataset. Can be either ``GMT_IS_VECTOR`` or
``GMT_IS_MATRIX``.
strings : numpy 1d-array
The array that will be attached to the dataset. Must be a 1d C
strings : numpy 1-D array
The array that will be attached to the dataset. Must be a 1-D C
contiguous array.

Raises
------
GMTCLibError
If given invalid input or ``GMT_Put_Strings`` exits with status !=
0.
If given invalid input or ``GMT_Put_Strings`` exits with
status != 0.
"""
c_put_strings = self.get_libgmt_func(
"GMT_Put_Strings",
Expand Down Expand Up @@ -856,7 +856,7 @@ def put_strings(self, dataset, family, strings):

def put_matrix(self, dataset, matrix, pad=0):
"""
Attach a numpy 2D array to a GMT dataset.
Attach a numpy 2-D array to a GMT dataset.

Use this function to attach numpy array data to a GMT dataset and pass
it to GMT modules. Wraps ``GMT_Put_Matrix``.
Expand All @@ -865,7 +865,7 @@ def put_matrix(self, dataset, matrix, pad=0):
first. Use ``|GMT_VIA_MATRIX'`` in the family.

Not all numpy dtypes are supported, only: int8, int16, int32, int64,
uint8, uint16, uint32, uint64, float32 and float64.
uint8, uint16, uint32, uint64, float32, and float64.

.. warning::
The numpy array must be C contiguous in memory. Use
Expand All @@ -877,8 +877,8 @@ def put_matrix(self, dataset, matrix, pad=0):
dataset : :class:`ctypes.c_void_p`
The ctypes void pointer to a ``GMT_Dataset``. Create it with
:meth:`pygmt.clib.Session.create_data`.
matrix : numpy 2d-array
The array that will be attached to the dataset. Must be a 2d C
matrix : numpy 2-D array
The array that will be attached to the dataset. Must be a 2-D C
contiguous array.
pad : int
The amount of padding that should be added to the matrix. Use when
Expand All @@ -887,8 +887,8 @@ def put_matrix(self, dataset, matrix, pad=0):
Raises
------
GMTCLibError
If given invalid input or ``GMT_Put_Matrix`` exits with status !=
0.
If given invalid input or ``GMT_Put_Matrix`` exits with
status != 0.
"""
c_put_matrix = self.get_libgmt_func(
"GMT_Put_Matrix",
Expand Down Expand Up @@ -1085,7 +1085,7 @@ def open_virtual_file(self, family, geometry, direction, data):
@contextmanager
def virtualfile_from_vectors(self, *vectors):
"""
Store 1d arrays as columns of a table inside a virtual file.
Store 1-D arrays as columns of a table inside a virtual file.

Use the virtual file name to pass in the data in your vectors to a GMT
module.
Expand All @@ -1100,12 +1100,12 @@ def virtualfile_from_vectors(self, *vectors):
:meth:`pygmt.clib.Session.open_virtual_file`.

If the arrays are C contiguous blocks of memory, they will be passed
without copying to GMT. If they are not (e.g., they are columns of a 2D
array), they will need to be copied to a contiguous block.
without copying to GMT. If they are not (e.g., they are columns of a
2-D array), they will need to be copied to a contiguous block.

Parameters
----------
vectors : 1d arrays
vectors : 1-D arrays
The vectors that will be included in the array. All must be of the
same size.

Expand Down Expand Up @@ -1189,7 +1189,7 @@ def virtualfile_from_vectors(self, *vectors):
@contextmanager
def virtualfile_from_matrix(self, matrix):
"""
Store a 2d array as a table inside a virtual file.
Store a 2-D array as a table inside a virtual file.

Use the virtual file name to pass in the data in your matrix to a GMT
module.
Expand All @@ -1215,7 +1215,7 @@ def virtualfile_from_matrix(self, matrix):

Parameters
----------
matrix : 2d array
matrix : 2-D array
The matrix that will be included in the GMT data container.

Yields
Expand Down Expand Up @@ -1375,16 +1375,16 @@ def virtualfile_from_data(
----------
check_kind : str
Used to validate the type of data that can be passed in. Choose
from 'raster', 'vector' or None. Default is None (no validation).
from 'raster', 'vector', or None. Default is None (no validation).
data : str or pathlib.Path or xarray.DataArray or {table-like} or None
Any raster or vector data format. This could be a file name or
path, a raster grid, a vector matrix/arrays, or other supported
data input.
x/y/z : 1d arrays or None
x, y and z columns as numpy arrays.
extra_arrays : list of 1d arrays
Optional. A list of numpy arrays in addition to x, y and z. All
of these arrays must be of the same size as the x/y/z arrays.
x/y/z : 1-D arrays or None
x, y, and z columns as numpy arrays.
extra_arrays : list of 1-D arrays
Optional. A list of numpy arrays in addition to x, y, and z.
All of these arrays must be of the same size as the x/y/z arrays.
required_z : bool
State whether the 'z' column is required.

Expand Down Expand Up @@ -1453,22 +1453,23 @@ def virtualfile_from_data(
_data.append(np.atleast_1d(z))
if extra_arrays:
_data.extend(extra_arrays)
elif kind == "matrix": # turn 2D arrays into list of vectors
elif kind == "matrix": # turn 2-D arrays into list of vectors
try:
# pandas.Series will be handled below like a 1d numpy ndarray
# pandas.Series will be handled below like a 1-D numpy.ndarray
assert not hasattr(data, "to_frame")
# pandas.DataFrame and xarray.Dataset types
_data = [array for _, array in data.items()]
except (AttributeError, AssertionError):
try:
# Just use virtualfile_from_matrix for 2D numpy.ndarray
# Just use virtualfile_from_matrix for 2-D numpy.ndarray
# which are signed integer (i), unsigned integer (u) or
# floating point (f) types
assert data.ndim == 2 and data.dtype.kind in "iuf"
_virtualfile_from = self.virtualfile_from_matrix
_data = (data,)
except (AssertionError, AttributeError):
# Python list, tuple, numpy ndarray and pandas.Series types
# Python list, tuple, numpy.ndarray, and pandas.Series
# types
_data = np.atleast_2d(np.asanyarray(data).T)

# Finally create the virtualfile from the data, to be passed into GMT
Expand All @@ -1485,8 +1486,8 @@ def extract_region(self):

Returns
-------
* wesn : 1d array
A 1D numpy array with the west, east, south, and north dimensions
* wesn : 1-D array
A numpy 1-D array with the west, east, south, and north dimensions
of the current figure.

Examples
Expand Down