{
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# A quick start guide to the `Point` and `Sample` classes\n"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Abstract\n",
"\n",
"In this example, we present the `Point` and `Sample` classes, two fundamental objects in the library. We present the principles behind these classes and the way to create and use these objects. We show how to extract a row or a column with the slicing operator. We show how these objects interacts with Python variables and with the `numpy` module."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Introduction\n",
"\n",
"Two fundamental objects in the library are:\n",
"\n",
"* `Point`: a multidimensional point in $D$ dimensions ($\\in \\mathbb{R}^D$) ;\n",
"* `Sample`: a multivariate sample made of $N$ points in $D$ dimensions."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [],
"source": [
"import openturns as ot"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## The `Point` class\n",
"\n",
"In this section, we see how to: \n",
"\n",
"* create a point in $\\mathbb{R}^3$, \n",
"* access its components, \n",
"* update its components."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"By default, points are filled with zeros. "
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"
[0,0,0]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=3 values=[0,0,0]"
]
},
"execution_count": 2,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p = ot.Point(3)\n",
"p"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following statement returns the value of the second component (with index 1). Python beginners should remember that Python indices start at zero. "
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"0.0"
]
},
"execution_count": 3,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p[1]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following statements sets the second component. "
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"[0,2,0]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=3 values=[0,2,0]"
]
},
"execution_count": 4,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p[1] = 2\n",
"p"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"3"
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p.getDimension ()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## The `Sample` class\n",
"\n",
"The `Sample` class represents a multivariate sample made of $N$ points in $\\mathbb{R}^D$.\n",
"\n",
"* $D$ is the *dimension* of the sample, \n",
"* $N$ is the *size* of the sample. \n",
"\n",
"A `Sample` can be seen as an array of with $N$ rows and $D$ columns.\n",
"\n",
"*Remark.* The `ProcessSample` class can be used to manage a sample of stochastic processes. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The script below creates a `Sample` with size $N=5$ and dimension $D=3$."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 | v2 |
\n",
"0 | 0.0 | 0.0 | 0.0 |
\n",
"1 | 0.0 | 0.0 | 0.0 |
\n",
"2 | 0.0 | 0.0 | 0.0 |
\n",
"3 | 0.0 | 0.0 | 0.0 |
\n",
"4 | 0.0 | 0.0 | 0.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=3 data=[[0,0,0],[0,0,0],[0,0,0],[0,0,0],[0,0,0]]"
]
},
"execution_count": 6,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data = ot.Sample(5, 3)\n",
"data"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"5"
]
},
"execution_count": 7,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data.getSize()"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"3"
]
},
"execution_count": 8,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data.getDimension()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following statement sets the third component (with index 2) of the fourth point (with index 3) in the `Sample`."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 | v2 |
\n",
"0 | 0.0 | 0.0 | 0.0 |
\n",
"1 | 0.0 | 0.0 | 0.0 |
\n",
"2 | 0.0 | 0.0 | 0.0 |
\n",
"3 | 0.0 | 0.0 | 32.0 |
\n",
"4 | 0.0 | 0.0 | 0.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=3 data=[[0,0,0],[0,0,0],[0,0,0],[0,0,32],[0,0,0]]"
]
},
"execution_count": 9,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data [3, 2] = 32\n",
"data"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Get a row or a column of a `Sample`\n",
"\n",
"As with `numpy` arrays, we can extract a row or a column with the `:` slicing operator. As a reminder for Python beginners, *slicing* is the fact of extracting a part of an array with one single statement; this avoids `for` loops and improves performance and readability. "
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"[0,0,32]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=3 values=[0,0,32]"
]
},
"execution_count": 10,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"row = data [3, :]\n",
"row"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {
"scrolled": true
},
"outputs": [
{
"data": {
"text/plain": [
"openturns.typ.Point"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"type ( row )"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v2 |
\n",
"0 | 0.0 |
\n",
"1 | 0.0 |
\n",
"2 | 0.0 |
\n",
"3 | 32.0 |
\n",
"4 | 0.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=1 description=[v2] data=[[0],[0],[0],[32],[0]]"
]
},
"execution_count": 12,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"column = data [:, 2]\n",
"column"
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"openturns.typ.Sample"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"type ( column )"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We see that:\n",
"\n",
"* the `row` is a `Point`,\n",
"* the `column` is a `Sample`.\n",
"\n",
"This is consistent with the fact that, in a dimension $D$ `Sample`, a row is a $D$-dimensional `Point`."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following statement extracts several columns (with indices 0 and 2) and creates a new `Sample`. "
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 |
\n",
"0 | 0.0 | 0.0 |
\n",
"1 | 0.0 | 0.0 |
\n",
"2 | 0.0 | 0.0 |
\n",
"3 | 0.0 | 32.0 |
\n",
"4 | 0.0 | 0.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=2 data=[[0,0],[0,0],[0,0],[0,32],[0,0]]"
]
},
"execution_count": 14,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"data.getMarginal ([0 , 2])"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Create a `Point` or a `Sample` from a Python list\n",
"\n",
"The following statement creates a `Point` from a Python list."
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"[2,3]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=2 values=[2,3]"
]
},
"execution_count": 15,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p1 = ot.Point ([2 , 3])\n",
"p1"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"[0,1]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=2 values=[0,1]"
]
},
"execution_count": 16,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p2 = ot.Point(range(2))\n",
"p2"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The first useful *Pythonism* that we will review is the *list comprehension*. This creates a list from a `for` loop. This kind of statements is often used in the the examples, so that they can be as short as possible.\n",
"\n",
"In the following statement, we create a point by iterating over the components of a `Point`. "
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"[4,9]
"
],
"text/plain": [
"class=Point name=Unnamed dimension=2 values=[4,9]"
]
},
"execution_count": 17,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p3 = ot.Point ([i*i for i in p1])\n",
"p3"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The second useful *Pythonism* is the repetition with the `*` operator.\n",
"\n",
"The following statements creates a list with three 5s. "
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[5, 5, 5]"
]
},
"execution_count": 18,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"p4 = [5] * 3\n",
"p4"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also create a `Sample` from a list of `Point`s."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 |
\n",
"0 | 2.0 | 3.0 |
\n",
"1 | 0.0 | 1.0 |
\n",
"2 | 4.0 | 9.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=3 dimension=2 data=[[2,3],[0,1],[4,9]]"
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample = ot.Sample ([p1 , p2 , p3 ])\n",
"sample"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can loop over the points in a sample, using a list comprehension. In the following example, we compute the Euclidian norm of the points in the previous sample. "
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"[3.605551275463989, 1.0, 9.848857801796104]"
]
},
"execution_count": 20,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"[point.norm() for point in sample]"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We can also create a `Sample` based on a `Point`, repeated three times."
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 | v2 |
\n",
"0 | 5.0 | 5.0 | 5.0 |
\n",
"1 | 5.0 | 5.0 | 5.0 |
\n",
"2 | 5.0 | 5.0 | 5.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=3 dimension=3 data=[[5,5,5],[5,5,5],[5,5,5]]"
]
},
"execution_count": 21,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample = ot.Sample ([p4] * 3)\n",
"sample"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"A nested list of floats is the easiest way to create a non-trivial `Sample`."
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 |
\n",
"0 | 0.0 | 1.0 |
\n",
"1 | 2.0 | 3.0 |
\n",
"2 | 4.0 | 5.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=3 dimension=2 data=[[0,1],[2,3],[4,5]]"
]
},
"execution_count": 22,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample = ot.Sample ([[0 , 1], [2, 3], [4, 5]])\n",
"sample"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Interactions with Numpy\n",
"\n",
"The Python classes defined in Python modules are unknown to OpenTURNS and hence cannot be used by the library. This is why it is useful to know how to convert to and from more basic Python variable types, especially Numpy arrays."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The following statement creates a `Sample` and converts it into a bidimensional Numpy `array`."
]
},
{
"cell_type": "code",
"execution_count": 23,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([[0., 0., 0.],\n",
" [0., 0., 0.],\n",
" [0., 0., 0.],\n",
" [0., 0., 0.],\n",
" [0., 0., 0.]])"
]
},
"execution_count": 23,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"import numpy as np\n",
"sample = ot.Sample (5, 3)\n",
"array = np.array (sample)\n",
"array"
]
},
{
"cell_type": "code",
"execution_count": 24,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"numpy.ndarray"
]
},
"execution_count": 24,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"type(array)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Conversely, the following script creates a Numpy `array`, then converts it into a `Sample`."
]
},
{
"cell_type": "code",
"execution_count": 25,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 | v2 |
\n",
"0 | 3.14 | 3.14 | 3.14 |
\n",
"1 | 3.14 | 3.14 | 3.14 |
\n",
"2 | 3.14 | 3.14 | 3.14 |
\n",
"3 | 3.14 | 3.14 | 3.14 |
\n",
"4 | 3.14 | 3.14 | 3.14 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=3 data=[[3.14,3.14,3.14],[3.14,3.14,3.14],[3.14,3.14,3.14],[3.14,3.14,3.14],[3.14,3.14,3.14]]"
]
},
"execution_count": 25,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"array = 3.14 * np.ones((5 , 3))\n",
"sample = ot.Sample ( array )\n",
"sample"
]
},
{
"cell_type": "code",
"execution_count": 26,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"5"
]
},
"execution_count": 26,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample.getSize()"
]
},
{
"cell_type": "code",
"execution_count": 27,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"3"
]
},
"execution_count": 27,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample.getDimension()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"There is an ambiguous situation: a `Sample` based on several scalar values. \n",
"\n",
"For example, is a `Sample` based on 5 values:\n",
"\n",
"* a `Sample` with size 5 in 1 dimension or\n",
"* a `Sample` with size 1 in 5 dimensions?\n",
"\n",
"In order to solve the case, we can use the second input argument of the `Sample` constructor, which specifies the dimension.\n",
"\n",
"The following statement creates an array containing 5 values from 0 to 1."
]
},
{
"cell_type": "code",
"execution_count": 28,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([0. , 0.25, 0.5 , 0.75, 1. ])"
]
},
"execution_count": 28,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"u = np.linspace (0, 1, 5)\n",
"u"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Choice A: we create a `Sample` with size 5 in 1 dimension."
]
},
{
"cell_type": "code",
"execution_count": 29,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 |
\n",
"0 | 0.0 |
\n",
"1 | 0.25 |
\n",
"2 | 0.5 |
\n",
"3 | 0.75 |
\n",
"4 | 1.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=5 dimension=1 data=[[0],[0.25],[0.5],[0.75],[1]]"
]
},
"execution_count": 29,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample = ot.Sample (u, 1)\n",
"sample"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Choice B: we create a `Sample` with size 1 in 5 dimensions."
]
},
{
"cell_type": "code",
"execution_count": 30,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
" | v0 | v1 | v2 | v3 | v4 |
\n",
"0 | 0.0 | 0.25 | 0.5 | 0.75 | 1.0 |
\n",
"
"
],
"text/plain": [
"class=Sample name=Unnamed implementation=class=SampleImplementation name=Unnamed size=1 dimension=5 data=[[0,0.25,0.5,0.75,1]]"
]
},
"execution_count": 30,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"sample = ot.Sample (u, 5)\n",
"sample"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"If we do not set the optional `size` parameter, the library cannot solve the case and an exception is generated:\n",
"\n",
"```\n",
"---------------------------------------------------------------------------\n",
"TypeError Traceback (most recent call last)\n",
" in ()\n",
" 1 # Generates an expected exception\n",
"----> 2 sample = ot.Sample (u)\n",
"[...]\n",
"TypeError: InvalidArgumentException : Invalid array dimension: 1\n",
"```"
]
},
{
"cell_type": "code",
"execution_count": 31,
"metadata": {},
"outputs": [],
"source": [
"# Generates an expected exception\n",
"# sample = ot.Sample (u)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.7.4"
}
},
"nbformat": 4,
"nbformat_minor": 2
}