diff --git a/src/pg_rad/isotope.py b/src/pg_rad/isotope.py index 77cb60d..ea8be9d 100644 --- a/src/pg_rad/isotope.py +++ b/src/pg_rad/isotope.py @@ -1,18 +1,17 @@ class Isotope: + """Represents the essential information of an isotope. + + Args: + name (str): Full name (e.g. Caesium-137). + E (float): Energy of the primary gamma in keV. + b (float): Branching ratio for the gamma at energy E. + """ def __init__( self, name: str, E: float, b: float - ): - """_Represents the essential information of an isotope._ - - Args: - name (str): Full name (e.g. Caesium-137). - E (float): Energy of the primary gamma in keV. - b (float): Branching ratio for the gamma at energy E. - """ - + ): if E <= 0: raise ValueError("primary_gamma must be a positive energy (keV).") diff --git a/src/pg_rad/landscape.py b/src/pg_rad/landscape.py index 88ac625..e3ebb07 100644 --- a/src/pg_rad/landscape.py +++ b/src/pg_rad/landscape.py @@ -6,20 +6,19 @@ from pg_rad.path import Path from pg_rad.objects import Source class Landscape: + """A generic Landscape that can contain a Path and sources. + + Args: + air_density (float, optional): Air density in kg / m^3. Defaults to 1.243. + size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500. + scale (str, optional): The scale of the size argument passed. Defaults to 'meters'. + """ def __init__( self, air_density: float = 1.243, size: int | tuple[int, int, int] = 500, scale = 'meters', - ): - """_A generic Landscape that can contain a Path and sources._ - - Args: - air_density (float, optional): Air density in kg / m^3. Defaults to 1.243. - size (int | tuple[int, int, int], optional): Size of the world. Defaults to 500. - scale (str, optional): The scale of the size argument passed. Defaults to 'meters'. - """ - + ): if isinstance(size, int): self.world = np.zeros((size, size, size)) elif isinstance(size, tuple) and len(size) == 3: @@ -34,7 +33,7 @@ class Landscape: self.sources: list[Source] = [] def plot(self, z = 0): - """_Plot a slice of the world at a height z._ + """Plot a slice of the world at a height `z`. Args: z (int, optional): Height of slice. Defaults to 0. @@ -78,7 +77,14 @@ class Landscape: return fig, ax def add_sources(self, *sources: Source): - """Add one or more point sources to the world.""" + """Add one or more point sources to the world. + + Args: + *sources (pg_rad.objects.Source): One or more sources, passed as + Source1, Source2, ... + Raises: + ValueError: If the source is outside the boundaries of the landscape. + """ max_x, max_y, max_z = self.world.shape[:3] @@ -88,23 +94,26 @@ class Landscape: 0 <= source.z < max_z) for source in sources ): - raise ValueError("One or more sources are outside the world boundaries.") + raise ValueError("One or more sources are outside the landscape!") self.sources.extend(sources) def set_path(self, path: Path): + """ + Set the path in the landscape. + """ self.path = path def create_landscape_from_path(path: Path, max_z = 500): - """_Generate a Landscape from a path, using its dimensions to determine - the size of the Landscape._ + """Generate a landscape from a path, using its dimensions to determine + the size of the landscape. Args: path (Path): A Path object describing the trajectory. max_z (int, optional): Height of the world. Defaults to 500 meters. Returns: - Landscape: A Landscape with dimensions based on the provided Path. + landscape (pg_rad.landscape.Landscape): A landscape with dimensions based on the provided Path. """ max_x = np.ceil(max(path.x_list)) max_y = np.ceil(max(path.y_list)) diff --git a/src/pg_rad/objects.py b/src/pg_rad/objects.py index 752c814..9e544c8 100644 --- a/src/pg_rad/objects.py +++ b/src/pg_rad/objects.py @@ -11,6 +11,16 @@ class Object: z: float, name: str = "Unnamed object", color: str = 'grey'): + """ + A generic object. + + Args: + x (float): X coordinate. + y (float): Y coordinate. + z (float): Z coordinate. + name (str, optional): Name for the object. Defaults to "Unnamed object". + color (str, optional): Matplotlib compatible color string. Defaults to "red". + """ self.x = x self.y = y @@ -35,7 +45,7 @@ class Source(Object): isotope: Isotope, name: str | None = None, color: str = "red"): - """_A point source._ + """A point source. Args: x (float): X coordinate. @@ -47,7 +57,8 @@ class Source(Object): Defaults to None, making the name sequential. (Source-1, Source-2, etc.). color (str, optional): Matplotlib compatible color string. Defaults to "red". - """ + """ + self.id = Source._id_counter Source._id_counter += 1 diff --git a/src/pg_rad/path.py b/src/pg_rad/path.py index 62122cc..3093153 100644 --- a/src/pg_rad/path.py +++ b/src/pg_rad/path.py @@ -13,11 +13,11 @@ logger = setup_logger(__name__) class PathSegment: def __init__(self, a: tuple[float, float], b: tuple[float, float]): - """_A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b)._ + """A straight Segment of a Path, from (x_a, y_a) to (x_b, y_b). Args: - a (tuple[float, float]): _The starting point (x_a, y_a)._ - b (tuple[float, float]): _The final point (x_b, y_b)._ + a (tuple[float, float]): The starting point (x_a, y_a). + b (tuple[float, float]): The final point (x_b, y_b). """ self.a = a self.b = b @@ -45,7 +45,7 @@ class Path: z: float = 0, simplify_path = False ): - """_Construct a path of sequences based on a list of coordinates._ + """Construct a path of sequences based on a list of coordinates. Args: coord_list (Sequence[tuple[float, float]]): List of x,y coordinates. @@ -95,7 +95,7 @@ def piecewise_regression_on_path( keep_endpoints_equal: bool = False, n_breakpoints: int = 3 ): - """_Take a Path object and return a piece-wise linear approximated Path._ + """From full resolution x and y arrays, return a piecewise linearly approximated/simplified pair of x and y arrays. This function uses the `piecewise_regression` package. From a full set of coordinate pairs, the function fits linear sections, automatically finding @@ -119,8 +119,11 @@ def piecewise_regression_on_path( n_breakpoints (int, optional): Number of breakpoints. Defaults to 3. Returns: - x (Sequence[float]): _Reduced list of x coordinates._ - y (Sequence[float]): _Reduced list of y coordinates._ + x (list[float]): Reduced list of x coordinates. + y (list[float]): Reduced list of y coordinates. + + Raises: + ConvergenceError: If the fitting algorithm failed to simplify the path. Reference: Pilgrim, C., (2021). piecewise-regression (aka segmented regression) in Python. Journal of Open Source Software, 6(68), 3859, https://doi.org/10.21105/joss.03859. @@ -163,11 +166,10 @@ def path_from_RT90( north_col: str = "North", **kwargs ) -> Path: - - """_Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame._ + """Construct a path from East and North formatted coordinates (RT90) in a Pandas DataFrame. Args: - df (pd.DataFrame): DataFrame containing at least the two columns noted in the cols argument. + df (pandas.DataFrame): DataFrame containing at least the two columns noted in the cols argument. east_col (str): The column name for the East coordinates. north_col (str): The column name for the North coordinates.