prospect.layer

class prospect.layer.Layer(name: str, area: prospect.area.Area, input_features: List[prospect.feature.Feature])[source]

Bases: object

A container for Feature objects

The Layer class is mostly useful as a way to create groups of similar features.

Parameters

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • input_features (List[Feature]) – List of features that originally made up the Layer (before clipping)

name

Name of the layer

Type

str

input_features

List of features that make up the layer

Type

List[Feature]

df

GeoDataFrame with a row for each feature in the layer

Type

geopandas GeoDataFrame

classmethod from_matern_points(parent_rate: float, child_rate: float, radius: float, name: str, area: prospect.area.Area, time_penalty: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 0.0, ideal_obs_rate: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 1.0) → prospect.layer.Layer[source]

Create a Layer instance with a Matérn point process.

It has a Poisson number of clusters, each with a Poisson number of points distributed uniformly across a disk of a given radius.

Parameters

  • parent_rate (float) – Theoretical clusters per unit area across the whole space. See Notes in poisson_points() for more details

  • child_rate (float) – Theoretical child points per unit area per cluster across the whole space.

  • radius (float) – Radius of the disk around the cluster centers

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • time_penalty (Union[float, rv_frozen], optional) – Minimum amount of time it takes to record a feature (the default is 0.0, which indicates no time cost for feature recording)

  • ideal_obs_rate (Union[float, rv_frozen], optional) –

    Ideal observation rate: the frequency with which an artifact or feature will be recorded, assuming the following ideal conditions:

    • It lies inside or intersects the Coverage (see below)

    • Surface visibility is 100%

    • The surveyor is highly skilled

    The default is 1.0, which indicates that when visibility and surveyor skill allow, the feature will always be recorded.

Returns

Return type

Layer

See also

poisson_points

includes details on Poisson point process

from_pseudorandom_points

faster, naive point creation

from_poisson_points

simple Poisson points Layer

from_thomas_points

similar process, good for clusters with centers from Poisson points

uniform_disk

function used to specify point locations around parents

Notes

  1. Parents (cluster centers) are NOT created as points in the output

  2. The generated point coordinates are not guaranteed to fall within the given area, only within its bounding box. The generated GeoDataFrame, df, is clipped by the actual area bounds after they are generated, which can result in fewer points than expected. All points will remain in the input_features.

classmethod from_poisson_points(rate: float, name: str, area: prospect.area.Area, time_penalty: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 0.0, ideal_obs_rate: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 1.0) → prospect.layer.Layer[source]

Create a Layer instance of points with a Poisson point process

Parameters

  • rate (float) – Theoretical events per unit area across the whole space. See Notes in poisson_points() for more details

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • time_penalty (Union[float, rv_frozen], optional) – Minimum amount of time it takes to record a feature (the default is 0.0, which indicates no time cost for feature recording)

  • ideal_obs_rate (Union[float, rv_frozen], optional) –

    Ideal observation rate: the frequency with which an artifact or feature will be recorded, assuming the following ideal conditions:

    • It lies inside or intersects the Coverage

    • Surface visibility is 100%

    • The surveyor is highly skilled

    The default is 1.0, which indicates that when visibility and surveyor skill allow, the feature will always be recorded.

Returns

Return type

Layer

See also

poisson_points

includes details on Poisson point process

from_pseudorandom_points

faster, naive point creation

from_thomas_points

good for clusters with centers from Poisson points

from_matern_points

good for clusters with centers from Poisson points

Notes

The generated point coordinates are not guaranteed to fall within the given area, only within its bounding box. The generated GeoDataFrame, df, is clipped by the actual area bounds after they are generated, which can result in fewer points than expected. All points will remain in the input_features.

classmethod from_pseudorandom_points(n: int, name: str, area: prospect.area.Area, time_penalty: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 0.0, ideal_obs_rate: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 1.0) → prospect.layer.Layer[source]

Create a Layer instance of pseudorandom points

Parameters

  • n (int) – Number of points to generate

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • time_penalty (Union[float, rv_frozen], optional) – Minimum amount of time it takes to record a feature (the default is 0.0, which indicates no time cost for feature recording)

  • ideal_obs_rate (Union[float, rv_frozen], optional) –

    Ideal observation rate: the frequency with which an artifact or feature will be recorded, assuming the following ideal conditions:

    • It lies inside or intersects the Coverage

    • Surface visibility is 100%

    • The surveyor is highly skilled

    The default is 1.0, which indicates that when visibility and surveyor skill allow, the feature will always be recorded.

Returns

Return type

Layer

See also

from_poisson_points

simple Poisson points Layer

from_thomas_points

good for clusters with centers from Poisson points

from_matern_points

good for clusters with centers from Poisson points

classmethod from_rectangles(area: prospect.area.Area, n: int)[source]
classmethod from_shapefile(path: str, name: str, area: prospect.area.Area, time_penalty: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 0.0, ideal_obs_rate: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 1.0, **kwargs) → prospect.layer.Layer[source]

Create a Layer instance from a shapefile.

Parameters

  • path (str) – Filepath to the shapefile

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • time_penalty (Union[float, rv_frozen], optional) – Minimum amount of time it takes to record a feature (the default is 0.0, which indicates no time cost for feature recording)

  • ideal_obs_rate (Union[float, rv_frozen], optional) –

    Ideal observation rate: the frequency with which an artifact or feature will be recorded, assuming the following ideal conditions:

    • It lies inside or intersects the Coverage

    • Surface visibility is 100%

    • The surveyor is highly skilled

    The default is 1.0, which indicates that when visibility and surveyor skill allow, the feature will always be recorded.

Returns

Return type

Layer

classmethod from_thomas_points(parent_rate: float, child_rate: float, gauss_var: float, name: str, area: prospect.area.Area, time_penalty: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 0.0, ideal_obs_rate: Union[float, scipy.stats._distn_infrastructure.rv_frozen] = 1.0) → prospect.layer.Layer[source]

Create a Layer instance with a Thomas point process.

It has a Poisson number of clusters, each with a Poisson number of points distributed with an isotropic Gaussian distribution of a given variance.

Parameters

  • parent_rate (float) – Theoretical clusters per unit area across the whole space. See Notes in poisson_points() for more details

  • child_rate (float) – Theoretical child points per unit area per cluster across the whole space.

  • gauss_var (float) – Variance of the isotropic Gaussian distributions around the cluster centers

  • name (str) – Unique name for the layer

  • area (Area) – Containing area

  • time_penalty (Union[float, rv_frozen], optional) – Minimum amount of time it takes to record a feature (the default is 0.0, which indicates no time cost for feature recording)

  • ideal_obs_rate (Union[float, rv_frozen], optional) –

    Ideal observation rate: the frequency with which an artifact or feature will be recorded, assuming the following ideal conditions:

    • It lies inside or intersects the Coverage

    • Surface visibility is 100%

    • The surveyor is highly skilled

    The default is 1.0, which indicates that when visibility and surveyor skill allow, the feature will always be recorded.

Returns

Return type

Layer

See also

poisson_points

includes details on Poisson point process

from_pseudorandom_points

faster, naive point creation

from_poisson_points

simple Poisson points Layer

from_matern_points

similar process, good for clusters with centers from Poisson points

Notes

  1. Parents (cluster centers) are NOT created as points in the output

  2. The generated point coordinates are not guaranteed to fall within the given area, only within its bounding box. The generated GeoDataFrame, df, is clipped by the actual area bounds after they are generated, which can result in fewer points than expected. All points will remain in the input_features.

static poisson_points(area: prospect.area.Area, rate: float) → numpy.ndarray[source]

Create point coordinates from a Poisson process.

Parameters

  • area (Area) – Bounding area

  • rate (float) – Theoretical events per unit area across the whole space. See Notes for more details

Returns

Return type

np.ndarray

See also

from_poisson_points

creates Layer with Poisson process

from_pseudorandom_points

faster, naive point creation

from_thomas_points

good for clusters with centers from Poisson points

from_matern_points

good for clusters with centers from Poisson points

Notes

  1. A Poisson point process is usually said to be more “purely” random than most random number generators (like the one used in from_pseudorandom_points())

  2. The rate (usually called “lambda”) of the Poisson point process represents the number of events per unit of area per unit of time across some theoretical space of which our Area is some subset. In this case, we only have one unit of time, so the rate really represents a theoretical number of events per unit area. For example, if the specified rate is 5, in any 1x1 square, the number of points observed will be drawn randomly from a Poisson distribution with a shape parameter of 5. In practical terms, this means that over many 1x1 areas (or many observations of the same area), the mean number of points observed in that area will approximate 5.

static uniform_disk(x: float, y: float, r: float) → Tuple[float, float][source]

Randomly locate a point within a disk of specified radius

Parameters

  • x (float) – Coordinates of disk center

  • y (float) – Coordinates of disk center

  • r (float) – Radius of the disk

Returns

Random point within the disk

Return type

Tuple[float, float]

prospect.feature prospect.coverage