CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <meta name="description" content="Keras documentation"> <meta name="author" content="Keras Team"> <link rel="shortcut icon" href="https://keras.io/img/favicon.ico"> <link rel="canonical" href="https://keras.io/2.18/api/utils/python_utils/" />  <meta property="og:title" content="Keras documentation: Python & NumPy utilities"> <meta property="og:image" content="https://keras.io/img/logo-k-keras-wb.png"> <meta name="twitter:title" content="Keras documentation: Python & NumPy utilities"> <meta name="twitter:image" content="https://keras.io/img/k-keras-social.png"> <meta name="twitter:card" content="summary"> <title>Python & NumPy utilities</title>  <link href="/css/bootstrap.min.css" rel="stylesheet">  <link href="https://fonts.googleapis.com/css2?family=Open+Sans:wght@400;600;700;800&display=swap" rel="stylesheet">  <link href="/css/docs.css" rel="stylesheet"> <link href="/css/monokai.css" rel="stylesheet">  <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= 'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-5DNGF4N'); </script> <script> (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','https://www.google-analytics.com/analytics.js','ga'); ga('create', 'UA-175165319-128', 'auto'); ga('send', 'pageview'); </script>  <script async defer src="https://buttons.github.io/buttons.js"></script> </head> <body>  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5DNGF4N" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>  <div class='k-page'> <div class="k-nav" id="nav-menu"> <a href='/'><img src='/img/logo-small.png' class='logo-small' /></a> <div class="nav flex-column nav-pills" role="tablist" aria-orientation="vertical"> <a class="nav-link" href="/about/" role="tab" aria-selected="">About Keras</a> <a class="nav-link" href="/getting_started/" role="tab" aria-selected="">Getting started</a> <a class="nav-link" href="/guides/" role="tab" aria-selected="">Developer guides</a> <a class="nav-link" href="/api/" role="tab" aria-selected="">Keras 3 API documentation</a> <a class="nav-link active" href="/2.18/api/" role="tab" aria-selected="">Keras 2 API documentation</a> <a class="nav-sublink" href="/2.18/api/models/">Models API</a> <a class="nav-sublink" href="/2.18/api/layers/">Layers API</a> <a class="nav-sublink" href="/2.18/api/callbacks/">Callbacks API</a> <a class="nav-sublink" href="/2.18/api/optimizers/">Optimizers</a> <a class="nav-sublink" href="/2.18/api/metrics/">Metrics</a> <a class="nav-sublink" href="/2.18/api/losses/">Losses</a> <a class="nav-sublink" href="/2.18/api/data_loading/">Data loading</a> <a class="nav-sublink" href="/2.18/api/datasets/">Built-in small datasets</a> <a class="nav-sublink" href="/2.18/api/applications/">Keras Applications</a> <a class="nav-sublink" href="/2.18/api/mixed_precision/">Mixed precision</a> <a class="nav-sublink active" href="/2.18/api/utils/">Utilities</a> <a class="nav-sublink2" href="/2.18/api/utils/model_plotting_utils/">Model plotting utilities</a> <a class="nav-sublink2" href="/2.18/api/utils/feature_space/">Structured data preprocessing utilities</a> <a class="nav-sublink2 active" href="/2.18/api/utils/python_utils/">Python & NumPy utilities</a> <a class="nav-sublink2" href="/2.18/api/utils/backend_utils/">Backend utilities</a> <a class="nav-link" href="/examples/" role="tab" aria-selected="">Code examples</a> <a class="nav-link" href="/keras_tuner/" role="tab" aria-selected="">KerasTuner: Hyperparameter Tuning</a> <a class="nav-link" href="/keras_hub/" role="tab" aria-selected="">KerasHub: Pretrained Models</a> <a class="nav-link" href="/keras_cv/" role="tab" aria-selected="">KerasCV: Computer Vision Workflows</a> <a class="nav-link" href="/keras_nlp/" role="tab" aria-selected="">KerasNLP: Natural Language Workflows</a> </div> </div> <div class='k-main'> <div class='k-main-top'> <script> function displayDropdownMenu() { e = document.getElementById("nav-menu"); if (e.style.display == "block") { e.style.display = "none"; } else { e.style.display = "block"; document.getElementById("dropdown-nav").style.display = "block"; } } function resetMobileUI() { if (window.innerWidth <= 840) { document.getElementById("nav-menu").style.display = "none"; document.getElementById("dropdown-nav").style.display = "block"; } else { document.getElementById("nav-menu").style.display = "block"; document.getElementById("dropdown-nav").style.display = "none"; } var navmenu = document.getElementById("nav-menu"); var menuheight = navmenu.clientHeight; var kmain = document.getElementById("k-main-id"); kmain.style.minHeight = (menuheight + 100) + 'px'; } window.onresize = resetMobileUI; window.addEventListener("load", (event) => { resetMobileUI() }); </script> <div id='dropdown-nav' onclick="displayDropdownMenu();"> <svg viewBox="-20 -20 120 120" width="60" height="60"> <rect width="100" height="20"></rect> <rect y="30" width="100" height="20"></rect> <rect y="60" width="100" height="20"></rect> </svg> </div> <form class="bd-search d-flex align-items-center k-search-form" id="search-form"> <input type="search" class="k-search-input" id="search-input" placeholder="Search Keras documentation..." aria-label="Search Keras documentation..." autocomplete="off"> <button class="k-search-btn"> <svg width="13" height="13" viewBox="0 0 13 13"><title>search</title><path d="m4.8495 7.8226c0.82666 0 1.5262-0.29146 2.0985-0.87438 0.57232-0.58292 0.86378-1.2877 0.87438-2.1144 0.010599-0.82666-0.28086-1.5262-0.87438-2.0985-0.59352-0.57232-1.293-0.86378-2.0985-0.87438-0.8055-0.010599-1.5103 0.28086-2.1144 0.87438-0.60414 0.59352-0.8956 1.293-0.87438 2.0985 0.021197 0.8055 0.31266 1.5103 0.87438 2.1144 0.56172 0.60414 1.2665 0.8956 2.1144 0.87438zm4.4695 0.2115 3.681 3.6819-1.259 1.284-3.6817-3.7 0.0019784-0.69479-0.090043-0.098846c-0.87973 0.76087-1.92 1.1413-3.1207 1.1413-1.3553 0-2.5025-0.46363-3.4417-1.3909s-1.4088-2.0686-1.4088-3.4239c0-1.3553 0.4696-2.4966 1.4088-3.4239 0.9392-0.92727 2.0864-1.3969 3.4417-1.4088 1.3553-0.011889 2.4906 0.45771 3.406 1.4088 0.9154 0.95107 1.379 2.0924 1.3909 3.4239 0 1.2126-0.38043 2.2588-1.1413 3.1385l0.098834 0.090049z"></path></svg> </button> </form> <script> var form = document.getElementById('search-form'); form.onsubmit = function(e) { e.preventDefault(); var query = document.getElementById('search-input').value; window.location.href = '/search.html?query=' + query; return False } </script> </div> <div class='k-main-inner' id='k-main-id'> <div class='k-location-slug'> ► <a href='/2.18/api/'>Keras 2 API documentation</a> / <a href='/2.18/api/utils/'>Utilities</a> / Python & NumPy utilities </div> <div class='k-content'> <h1 id="python-amp-numpy-utilities">Python & NumPy utilities</h1> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/tf_utils.py#L39">[source]</a> <h3 id="setrandomseed-function"><code>set_random_seed</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.set_random_seed(seed) </code></pre></div> Sets all random seeds for the program (Python, NumPy, and TensorFlow). You can use this utility to make almost any TF-Keras program fully deterministic. Some limitations apply in cases where network communications are involved (e.g. parameter server distribution), which creates additional sources of randomness, or when certain non-deterministic cuDNN ops are involved. Calling this utility is equivalent to the following: <div class="codehilite"><pre><code>import random import numpy as np import tensorflow as tf random.seed(seed) np.random.seed(seed) tf.random.set_seed(seed) </code></pre></div> Arguments <ul> <li>seed: Integer, the random seed to use.</li> </ul> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/dataset_utils.py#L32">[source]</a> <h3 id="splitdataset-function"><code>split_dataset</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.split_dataset( dataset, left_size=None, right_size=None, shuffle=False, seed=None ) </code></pre></div> Split a dataset into a left half and a right half (e.g. train / test). Arguments <ul> <li>dataset: A <a href="https://www.tensorflow.org/api_docs/python/tf/data/Dataset"><code>tf.data.Dataset</code></a> object, or a list/tuple of arrays with the same length.</li> <li>left_size: If float (in the range <code>[0, 1]</code>), it signifies the fraction of the data to pack in the left dataset. If integer, it signifies the number of samples to pack in the left dataset. If <code>None</code>, it uses the complement to <code>right_size</code>. Defaults to <code>None</code>.</li> <li>right_size: If float (in the range <code>[0, 1]</code>), it signifies the fraction of the data to pack in the right dataset. If integer, it signifies the number of samples to pack in the right dataset. If <code>None</code>, it uses the complement to <code>left_size</code>. Defaults to <code>None</code>.</li> <li>shuffle: Boolean, whether to shuffle the data before splitting it.</li> <li>seed: A random seed for shuffling.</li> </ul> Returns <ul> <li>A tuple of two <a href="https://www.tensorflow.org/api_docs/python/tf/data/Dataset"><code>tf.data.Dataset</code></a> objects: the left and right splits.</li> </ul> Example <div class="codehilite"><pre><code>>>> data = np.random.random(size=(1000, 4)) >>> left_ds, right_ds = tf.keras.utils.split_dataset(data, left_size=0.8) >>> int(left_ds.cardinality()) 800 >>> int(right_ds.cardinality()) 200 </code></pre></div> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/data_utils.py#L193">[source]</a> <h3 id="getfile-function"><code>get_file</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.get_file( fname=None, origin=None, untar=False, md5_hash=None, file_hash=None, cache_subdir="datasets", hash_algorithm="auto", extract=False, archive_format="auto", cache_dir=None, ) </code></pre></div> Downloads a file from a URL if it not already in the cache. By default the file at the url <code>origin</code> is downloaded to the cache_dir <code>~/.keras</code>, placed in the cache_subdir <code>datasets</code>, and given the filename <code>fname</code>. The final location of a file <code>example.txt</code> would therefore be <code>~/.keras/datasets/example.txt</code>. Files in tar, tar.gz, tar.bz, and zip formats can also be extracted. Passing a hash will verify the file after download. The command line programs <code>shasum</code> and <code>sha256sum</code> can compute the hash. Example <div class="codehilite"><pre><code>path_to_downloaded_file = tf.keras.utils.get_file( origin="https://storage.googleapis.com/download.tensorflow.org/example_images/flower_photos.tgz", extract=True, ) </code></pre></div> Arguments <ul> <li>fname: Name of the file. If an absolute path <code>/path/to/file.txt</code> is specified the file will be saved at that location. If <code>None</code>, the name of the file at <code>origin</code> will be used.</li> <li>origin: Original URL of the file.</li> <li>untar: Deprecated in favor of <code>extract</code> argument. boolean, whether the file should be decompressed</li> <li>md5_hash: Deprecated in favor of <code>file_hash</code> argument. md5 hash of the file for verification</li> <li>file_hash: The expected hash string of the file after download. The sha256 and md5 hash algorithms are both supported.</li> <li>cache_subdir: Subdirectory under the TF-Keras cache dir where the file is saved. If an absolute path <code>/path/to/folder</code> is specified the file will be saved at that location.</li> <li>hash_algorithm: Select the hash algorithm to verify the file. options are <code>'md5'</code>, <code>'sha256'</code>, and <code>'auto'</code>. The default 'auto' detects the hash algorithm in use.</li> <li>extract: True tries extracting the file as an Archive, like tar or zip.</li> <li>archive_format: Archive format to try for extracting the file. Options are <code>'auto'</code>, <code>'tar'</code>, <code>'zip'</code>, and <code>None</code>. <code>'tar'</code> includes tar, tar.gz, and tar.bz files. The default <code>'auto'</code> corresponds to <code>['tar', 'zip']</code>. None or an empty list will return no matches found.</li> <li>cache_dir: Location to store cached files, when None it defaults to <code>~/.keras/</code>.</li> </ul> Returns Path to the downloaded file. ⚠️ Warning on malicious downloads ⚠️ Downloading something from the Internet carries a risk. NEVER download a file/archive if you do not trust the source. We recommend that you specify the <code>file_hash</code> argument (if the hash of the source file is known) to make sure that the file you are getting is the one you expect. <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/generic_utils.py#L127">[source]</a> <h3 id="progbar-class"><code>Progbar</code> class</h3> <div class="codehilite"><pre><code>tf_keras.utils.Progbar( target, width=30, verbose=1, interval=0.05, stateful_metrics=None, unit_name="step" ) </code></pre></div> Displays a progress bar. Arguments <ul> <li>target: Total number of steps expected, None if unknown.</li> <li>width: Progress bar width on screen.</li> <li>verbose: Verbosity mode, 0 (silent), 1 (verbose), 2 (semi-verbose)</li> <li>stateful_metrics: Iterable of string names of metrics that should not be averaged over time. Metrics in this list will be displayed as-is. All others will be averaged by the progbar before display.</li> <li>interval: Minimum visual progress update interval (in seconds).</li> <li>unit_name: Display name for step counts (usually "step" or "sample").</li> </ul> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/data_utils.py#L492">[source]</a> <h3 id="sequence-class"><code>Sequence</code> class</h3> <div class="codehilite"><pre><code>tf_keras.utils.Sequence() </code></pre></div> Base object for fitting to a sequence of data, such as a dataset. Every <code>Sequence</code> must implement the <code>__getitem__</code> and the <code>__len__</code> methods. If you want to modify your dataset between epochs, you may implement <code>on_epoch_end</code>. The method <code>__getitem__</code> should return a complete batch. Notes: <code>Sequence</code> is a safer way to do multiprocessing. This structure guarantees that the network will only train once on each sample per epoch, which is not the case with generators. Examples <div class="codehilite"><pre><code>from skimage.io import imread from skimage.transform import resize import numpy as np import math # Here, `x_set` is list of path to the images # and `y_set` are the associated classes. class CIFAR10Sequence(tf.keras.utils.Sequence): def __init__(self, x_set, y_set, batch_size): self.x, self.y = x_set, y_set self.batch_size = batch_size def __len__(self): return math.ceil(len(self.x) / self.batch_size) def __getitem__(self, idx): low = idx * self.batch_size # Cap upper bound at array length; the last batch may be smaller # if the total number of items is not a multiple of batch size. high = min(low + self.batch_size, len(self.x)) batch_x = self.x[low:high] batch_y = self.y[low:high] return np.array([ resize(imread(file_name), (200, 200)) for file_name in batch_x]), np.array(batch_y) </code></pre></div> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/np_utils.py#L23">[source]</a> <h3 id="tocategorical-function"><code>to_categorical</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.to_categorical(y, num_classes=None, dtype="float32") </code></pre></div> Converts a class vector (integers) to binary class matrix. E.g. for use with <code>categorical_crossentropy</code>. Arguments <ul> <li>y: Array-like with class values to be converted into a matrix (integers from 0 to <code>num_classes - 1</code>).</li> <li>num_classes: Total number of classes. If <code>None</code>, this would be inferred as <code>max(y) + 1</code>.</li> <li>dtype: The data type expected by the input. Default: <code>'float32'</code>.</li> </ul> Returns A binary matrix representation of the input as a NumPy array. The class axis is placed last. Example <div class="codehilite"><pre><code>>>> a = tf.keras.utils.to_categorical([0, 1, 2, 3], num_classes=4) >>> print(a) [[1. 0. 0. 0.] [0. 1. 0. 0.] [0. 0. 1. 0.] [0. 0. 0. 1.]] </code></pre></div> <div class="codehilite"><pre><code>>>> b = tf.constant([.9, .04, .03, .03, ... .3, .45, .15, .13, ... .04, .01, .94, .05, ... .12, .21, .5, .17], ... shape=[4, 4]) >>> loss = tf.keras.backend.categorical_crossentropy(a, b) >>> print(np.around(loss, 5)) [0.10536 0.82807 0.1011 1.77196] </code></pre></div> <div class="codehilite"><pre><code>>>> loss = tf.keras.backend.categorical_crossentropy(a, a) >>> print(np.around(loss, 5)) [0. 0. 0. 0.] </code></pre></div> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/np_utils.py#L80">[source]</a> <h3 id="toordinal-function"><code>to_ordinal</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.to_ordinal(y, num_classes=None, dtype="float32") </code></pre></div> Converts a class vector (integers) to an ordinal regression matrix. This utility encodes class vector to ordinal regression/classification matrix where each sample is indicated by a row and rank of that sample is indicated by number of ones in that row. Arguments <ul> <li>y: Array-like with class values to be converted into a matrix (integers from 0 to <code>num_classes - 1</code>).</li> <li>num_classes: Total number of classes. If <code>None</code>, this would be inferred as <code>max(y) + 1</code>.</li> <li>dtype: The data type expected by the input. Default: <code>'float32'</code>.</li> </ul> Returns An ordinal regression matrix representation of the input as a NumPy array. The class axis is placed last. Example <div class="codehilite"><pre><code>>>> a = tf.keras.utils.to_ordinal([0, 1, 2, 3], num_classes=4) >>> print(a) [[0. 0. 0.] [1. 0. 0.] [1. 1. 0.] [1. 1. 1.]] </code></pre></div> <hr /> <a href="https://github.com/keras-team/tf-keras/tree/v2.18.0/tf_keras/utils/np_utils.py#L128">[source]</a> <h3 id="normalize-function"><code>normalize</code> function</h3> <div class="codehilite"><pre><code>tf_keras.utils.normalize(x, axis=-1, order=2) </code></pre></div> Normalizes a Numpy array. Arguments <ul> <li>x: Numpy array to normalize.</li> <li>axis: axis along which to normalize.</li> <li>order: Normalization order (e.g. <code>order=2</code> for L2 norm).</li> </ul> Returns A normalized copy of the array. <hr /> </div> <div class='k-outline'> <div class='k-outline-depth-1'> <a href='#python-amp-numpy-utilities'>Python & NumPy utilities</a> </div> <div class='k-outline-depth-3'> <a href='#setrandomseed-function'><code>set_random_seed</code> function</a> </div> <div class='k-outline-depth-3'> <a href='#splitdataset-function'><code>split_dataset</code> function</a> </div> <div class='k-outline-depth-3'> <a href='#getfile-function'><code>get_file</code> function</a> </div> <div class='k-outline-depth-3'> <a href='#progbar-class'><code>Progbar</code> class</a> </div> <div class='k-outline-depth-3'> <a href='#sequence-class'><code>Sequence</code> class</a> </div> <div class='k-outline-depth-3'> <a href='#tocategorical-function'><code>to_categorical</code> function</a> </div> <div class='k-outline-depth-3'> <a href='#toordinal-function'><code>to_ordinal</code> function</a> </div> <div class='k-outline-depth-3'> <a href='#normalize-function'><code>normalize</code> function</a> </div> </div> </div> </div> </div> </body> <footer style="float: left; width: 100%; padding: 1em; border-top: solid 1px #bbb;"> <a href="https://policies.google.com/terms">Terms</a> | <a href="https://policies.google.com/privacy">Privacy</a> </footer> </html>