DOC: Clarify loadtxt input cols requirement (#21861)

Also add an example to illustrate how usecols can be used
to read a file with varying number of fields.

numpy/lib/npyio.py

@@ -1067,8 +1067,6 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None,
     r"""
     Load data from a text file.
 
-    Each row in the text file must have the same number of values.
-
     Parameters
     ----------
     fname : file, str, pathlib.Path, list of str, generator
@@ -1171,6 +1169,11 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None,
     `genfromtxt` function provides more sophisticated handling of, e.g.,
     lines with missing values.
 
+    Each row in the input text file must have the same number of values to be
+    able to read all values. If all rows do not have same number of values, a
+    subset of up to n columns (where n is the least number of values present
+    in all rows) can be read by specifying the columns via `usecols`.
+
     .. versionadded:: 1.10.0
 
     The strings produced by the Python float.hex method can be used as
@@ -1279,6 +1282,15 @@ def loadtxt(fname, dtype=float, comments='#', delimiter=None,
     >>> np.loadtxt(s, dtype="U", delimiter=",", quotechar='"')
     array('Hello, my name is "Monty"!', dtype='<U26')
 
+    Read subset of columns when all rows do not contain equal number of values:
+
+    >>> d = StringIO("1 2\n2 4\n3 9 12\n4 16 20")
+    >>> np.loadtxt(d, usecols=(0, 1))
+    array([[ 1.,  2.],
+           [ 2.,  4.],
+           [ 3.,  9.],
+           [ 4., 16.]])
+
     """
 
     if like is not None: