summaryrefslogtreecommitdiff
path: root/doc/source
diff options
context:
space:
mode:
authorMukulika <mukulikapahari@gmail.com>2021-09-26 19:30:24 +0530
committerMukulika <mukulikapahari@gmail.com>2021-10-28 22:06:05 +0530
commitdbf3a4bf7ba3cb10f3cf0aa28a2413e1f06bafb1 (patch)
tree6db824fbb60843dba492156ac69187c342d75856 /doc/source
parent010971e968e71401cfadf4ca7760cb896a718dba (diff)
downloadnumpy-dbf3a4bf7ba3cb10f3cf0aa28a2413e1f06bafb1.tar.gz
DOC: Added introductory para
Diffstat (limited to 'doc/source')
-rw-r--r--doc/source/user/basics.copies.rst37
1 files changed, 23 insertions, 14 deletions
diff --git a/doc/source/user/basics.copies.rst b/doc/source/user/basics.copies.rst
index 49fdb85b1..50c6ea774 100644
--- a/doc/source/user/basics.copies.rst
+++ b/doc/source/user/basics.copies.rst
@@ -4,19 +4,26 @@
Copies and views
****************
-The NumPy array is a contiguous block of memory consisting of two parts- the
-data buffer with the actual data elements and the metadata which contains
+When operating on a NumPy array, we can sometimes improve performance by using
+:term:`views <view>` instead of copies of the array. However, when handling
+large amounts of important data, it can be risky to directly operate on it and
+it could be safer to use copies. Hence, it is important to know the difference
+between these two terms to correctly determine when to use which one.
+
+The NumPy array is a :term:`contiguous` block of memory consisting of two parts:
+the data buffer with the actual data elements, and the metadata which contains
information about the data buffer. The metadata includes data type, strides
and other important information that helps manipulate the :class:`.ndarray`
-easily. See the :ref:`organization-numpy-arrays` section for a detailed look.
+easily. See the :ref:`numpy-internals` section for a detailed look.
View or shallow copy
====================
-It is possible to perceive the array differently by changing the
-metadata. These new arrays are called views or shallow copies. The data buffer
-remains the same so any changes made to a view reflects in the original
-copy. A view can be forced through the :meth:`.ndarray.view` method.
+It is possible to access the array differently by just changing the
+metadata and without changing the data buffer. This creates a new way of
+looking at the data and these new arrays are called views or shallow copies.
+The data buffer remains the same so any changes made to a view reflects in the
+original copy. A view can be forced through the :meth:`.ndarray.view` method.
Copy or deep copy
@@ -124,12 +131,14 @@ shape attribute of the array. For example::
[1., 1.]])
>>> z = y.view()
>>> z.shape = 6
- AttributeError: Incompatible shape for in-place modification.
- Use `.reshape()` to make a copy with the desired shape.
-
-:func:`.ravel` returns a contiguous flattened view of the array
-wherever possible. On the other hand, :meth:`.ndarray.flatten` always returns
-a flattened copy of the array. However, to guarantee a view in most cases
-``x.reshape(-1)`` may be preferable.
+ Traceback (most recent call last):
+ ...
+ AttributeError: Incompatible shape for in-place modification. Use
+ `.reshape()` to make a copy with the desired shape.
+
+Taking the example of another operation, :func:`.ravel` returns a contiguous
+flattened view of the array wherever possible. On the other hand,
+:meth:`.ndarray.flatten` always returns a flattened copy of the array.
+However, to guarantee a view in most cases ``x.reshape(-1)`` may be preferable.