From ead0eb7f58aa17b5f2eda9734c0bbff922ba4591 Mon Sep 17 00:00:00 2001 From: Dar Dahlen Date: Wed, 12 Jun 2024 13:29:58 -0700 Subject: [PATCH] Fixes to documentation (#42) * fix docs api parameter rendering * fixing docs * expose SpkInfo * fix doc typos * mypy --- docs/conf.py | 8 +++---- src/neospy/conversion.py | 6 ++--- src/neospy/irsa.py | 42 ++++++++++++++++++++++++++++++++ src/neospy/mpc.py | 44 ++++++++++++++++++---------------- src/neospy/propagation.py | 17 +++++++------ src/neospy/rust/flux/models.rs | 18 +++++++++----- src/neospy/rust/state.rs | 2 +- src/neospy/rust/vector.rs | 31 +++++++++++++++--------- src/neospy/spice.py | 12 ++++++++-- src/neospy/wise.py | 2 +- 10 files changed, 127 insertions(+), 55 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 266f2a5..8e77d3e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -41,17 +41,17 @@ # Napoleon settings -napoleon_google_docstring = True +napoleon_google_docstring = False napoleon_numpy_docstring = True -napoleon_include_init_with_doc = True +napoleon_include_init_with_doc = False napoleon_include_private_with_doc = False napoleon_include_special_with_doc = False napoleon_use_admonition_for_examples = False napoleon_use_admonition_for_notes = False napoleon_use_admonition_for_references = False napoleon_use_ivar = False -napoleon_use_param = False -napoleon_use_rtype = False +napoleon_use_param = True +napoleon_use_rtype = True # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/src/neospy/conversion.py b/src/neospy/conversion.py index 171062e..699a8fe 100644 --- a/src/neospy/conversion.py +++ b/src/neospy/conversion.py @@ -168,7 +168,7 @@ def compute_tisserand( inclination: Inclination of the small body with respect to the perturbing body, in units of Degrees. - preturbing_semi_major: + perturbing_semi_major: Semi major axis of the parent body, in units of AU. """ cos_incl = np.cos(np.radians(inclination)) @@ -303,8 +303,8 @@ def mag_to_flux(mag: float, zero_point=3631) -> float: Parameters ---------- - flux: - Flux in Jy. + mag: + AB Magnitude. zero_point: Flux in Jy where the magnitude is zero. """ diff --git a/src/neospy/irsa.py b/src/neospy/irsa.py index 5a52265..92cd8b5 100644 --- a/src/neospy/irsa.py +++ b/src/neospy/irsa.py @@ -105,6 +105,9 @@ def query_irsa_tap( The URL of the TAPS service to query, this defaults to IRSA. auth : An optional (username, password), this may be used to access restricted data. + timeout : + Timeout for web queries. This will raise an exception if the servers to not + respond within this time. verbose : Print status responses as they are fetched from IRSA. """ @@ -171,6 +174,24 @@ def plot_fits_image(fit, vmin=-3, vmax=7, cmap="bone_r"): """ Plot a FITS image, returning a WCS object which may be used to plot future points correctly onto the current image. + + This estimates the standard deviation, subtracts the median, and scales the + displayed image by number of standard deviations from the median value. + + This returns the WCS which is constructed during the plotting process. + + This will use the existing matplotlib plotting axis if available. + + Parameters + ---------- + fit: + Fits file from Astropy. + vmin : + Minimum number of standard deviations below the median to plot. + vmax : + Maximum number of standard deviations above the median to plot. + cmap : + Color map to use for the plot. """ data = np.nan_to_num(fit.data) wcs = WCS(fit.header, relax=True) @@ -195,6 +216,27 @@ def annotate_plot( """ Add an annotation for a point in a FITS plot, this requires a world coordinate system (wcs) as returned by the plotting function above. + + Parameters + ---------- + wcs : + An Astropy World Coordinate system from the image. + ra : + The RA in degrees. + dec : + The DEC in degrees. + text : + Optional text to display. + px_gap : + How many pixels should the annotation be offset from the specified RA/DEC. + length : + Length of the bars in pixels. + lw : + Line width of the bars. + c : + Color of the bars, uses matplotlib colors. + text_color : + If text is provided, this defines the text color. """ x, y = wcs.world_to_pixel(SkyCoord(ra, dec, unit="deg")) total = length + px_gap diff --git a/src/neospy/mpc.py b/src/neospy/mpc.py index 3c9f3b1..0e9c1a0 100644 --- a/src/neospy/mpc.py +++ b/src/neospy/mpc.py @@ -32,6 +32,10 @@ def find_obs_code(name: str): >>> neospy.mpc.find_obs_code("Palomar Mountain") (33.35412, 243.13746, 1.69615, 'Palomar Mountain', '675') + Parameters + ---------- + name : + Name of the observatory, this can be a partial name, or obs code. """ codes = _core.observatory_codes() found = [] @@ -184,7 +188,7 @@ def pack_permanent_designation(unpacked): return pack_comet_designation(unpacked) -def unpack_provisional_designation(packed): +def unpack_provisional_designation(packed: str): """ Accepts a packed MPC provisional designation and returns an unpacked provisional designation. @@ -196,7 +200,7 @@ def unpack_provisional_designation(packed): Parameters ---------- - packed : str + packed : A packed 7 character provisional MPC designation of an object. """ if len(packed) == 12: @@ -211,15 +215,15 @@ def unpack_provisional_designation(packed): if int(year) < 1925: year = "A" + year[1:] loop = _mpc_hex.index(packed[4]) * 10 + int(packed[5]) - loop = "" if loop == 0 else str(loop) + loop_str = "" if loop == 0 else str(loop) order = packed[6] if order.isnumeric() or order.islower(): # it's a comet return unpack_comet_designation(packed) - return year + " " + packed[3] + order + loop + return year + " " + packed[3] + order + loop_str -def pack_provisional_designation(unpacked): +def pack_provisional_designation(unpacked: str): """ Accepts an unpacked MPC provisional designation and returns a packed provisional designation. @@ -231,7 +235,7 @@ def pack_provisional_designation(unpacked): Parameters ---------- - unpacked : str + unpacked : An unpacked provisional MPC designation of an object. """ year, designation = unpacked.split() @@ -253,7 +257,7 @@ def pack_provisional_designation(unpacked): return century + decade + half_month + loop + subloop + order -def pack_satellite_designation(unpacked): +def pack_satellite_designation(unpacked: str): """ Accepts an unpacked MPC planetary satellite designation and returns a packed designation. @@ -265,7 +269,7 @@ def pack_satellite_designation(unpacked): Parameters ---------- - unpacked : str + unpacked : An unpacked satellite MPC designation of an object. """ planet, satnum = unpacked.split() @@ -279,7 +283,7 @@ def pack_satellite_designation(unpacked): return f"{pout:1s}{digout:03d}S" -def unpack_satellite_designation(packed): +def unpack_satellite_designation(packed: str): """ Accepts a packed MPC satellite designation and returns an unpacked designation. @@ -291,7 +295,7 @@ def unpack_satellite_designation(packed): Parameters ---------- - packed : str + packed : A packed 5 character satellite MPC designation of an object. """ @@ -313,7 +317,7 @@ def unpack_satellite_designation(packed): return planets[packed[0]] + " " + int_to_roman(int(packed[1:4])) -def pack_comet_designation(unpacked): +def pack_comet_designation(unpacked: str): """ Accepts an unpacked MPC provisional designation and returns a packed provisional designation. @@ -328,7 +332,7 @@ def pack_comet_designation(unpacked): Parameters ---------- - unpacked : str + unpacked : An unpacked MPC comet designation of an object. """ @@ -383,7 +387,7 @@ def pack_comet_designation(unpacked): return comet_type + pack_provisional_designation(unpacked) -def unpack_comet_designation(packed): +def unpack_comet_designation(packed: str): """ Accepts a packed MPC comet designation and returns an unpacked provisional designation. @@ -395,7 +399,7 @@ def unpack_comet_designation(packed): Parameters ---------- - packed : str + packed : A packed 5,7, or 8 character provisional MPC designation of an object. """ if len(packed) == 5: @@ -418,7 +422,7 @@ def unpack_comet_designation(packed): return comet_add + unpack_provisional_designation(packed) -def unpack_designation(packed): +def unpack_designation(packed: str): """ Accepts either a packed provisional designation or permanent designation and returns the unpacked representation. @@ -431,7 +435,7 @@ def unpack_designation(packed): Parameters ---------- - packed : str + packed : A packed 5, 7, or 8 character MPC designation of an object. """ packed = packed.strip() @@ -445,7 +449,7 @@ def unpack_designation(packed): raise SyntaxError(f"This designation could not be unpacked '{packed}'") -def pack_designation(unpacked): +def pack_designation(unpacked: str): """ Accepts either a unpacked provisional designation or permanent designation and returns the packed representation. @@ -458,7 +462,7 @@ def pack_designation(unpacked): Parameters ---------- - unpacked : str + unpacked : An unpacked designation to be packed into either a permanent or provisional designation. """ @@ -776,7 +780,7 @@ def table_to_states(orbit_dataframe): return states -def int_to_roman(num): +def int_to_roman(num: int): """Convert an integer to a Roman numeral.""" if not isinstance(num, int): raise TypeError("Input needs to be an integer") @@ -793,7 +797,7 @@ def int_to_roman(num): return "".join(result) -def roman_to_int(num): +def roman_to_int(num: str): """Convert a Roman numeral to an integer.""" if not isinstance(num, str): diff --git a/src/neospy/propagation.py b/src/neospy/propagation.py index e59c508..6556948 100644 --- a/src/neospy/propagation.py +++ b/src/neospy/propagation.py @@ -11,6 +11,7 @@ from .spice import SpiceKernels from .vector import Vector, State +from .fov import FOVList from . import _core # pylint: disable=no-name-in-module logger = logging.getLogger(__name__) @@ -75,7 +76,7 @@ def propagate_two_body( Parameters ---------- - vec_state: + states: The input vector state to propagate. jd: The desired time at which to estimate the objects' state. @@ -128,8 +129,8 @@ def moid(state: State, other: Optional[State] = None): Parameters ---------- - states: - The state describing a number of objects. + state: + The state describing an object. other: The state of the object to calculate the MOID for, if this is not provided, then Earth is fetched from :class:`~neospy.spice.SpiceKernels` and is used in @@ -140,9 +141,11 @@ def moid(state: State, other: Optional[State] = None): return _moid_single(state, other) -def state_visible(states: list[State], fovs, dt: float = 3) -> list[list[State]]: +def state_visible( + states: list[State], fovs: FOVList, dt: float = 3 +) -> list[list[State]]: """ - Given a state and field of view, return only the objects which are visible to the + Given states and field of view, return only the objects which are visible to the observer, adding a correction for optical light delay. Objects are propagated using 2 body physics to the time of the FOV if time steps are @@ -150,8 +153,8 @@ def state_visible(states: list[State], fovs, dt: float = 3) -> list[list[State]] parameters ---------- - state: - A state which does not already have a specified FOV. + states: + States which do not already have a specified FOV. fov: A field of view from which to subselect objects which are visible. dt: diff --git a/src/neospy/rust/flux/models.rs b/src/neospy/rust/flux/models.rs index 69e8f13..c343872 100644 --- a/src/neospy/rust/flux/models.rs +++ b/src/neospy/rust/flux/models.rs @@ -15,12 +15,18 @@ use crate::{frame::PyFrames, vector::VectorLike}; /// /// Parameters /// ---------- -/// fluxes : Total fluxes per band in units of Jy / Steradian. -/// thermal_fluxes : Black body specific fluxes per band in units of Jy / Steradian. -/// hg_fluxes : Reflected light specific fluxes per band in units of Jy / Steradian. -/// v_band_magnitude : Expected magnitude in the V-band using the HG model. -/// v_band_flux : Expected flux in the V-band using the HG model. -/// magnitudes : Magnitudes in the different bands if zero mags were available. +/// fluxes : +/// Total fluxes per band in units of Jy / Steradian. +/// thermal_fluxes : +/// Black body specific fluxes per band in units of Jy / Steradian. +/// hg_fluxes : +/// Reflected light specific fluxes per band in units of Jy / Steradian. +/// v_band_magnitude : +/// Expected magnitude in the V-band using the HG model. +/// v_band_flux : +/// Expected flux in the V-band using the HG model. +/// magnitudes : +/// Magnitudes in the different bands if zero mags were available. #[pyclass(frozen, module = "neospy.flux", name = "ModelResults")] #[derive(Clone, Debug, Serialize, Deserialize)] pub struct PyModelResults(pub neospy_core::flux::ModelResults); diff --git a/src/neospy/rust/state.rs b/src/neospy/rust/state.rs index 7f28699..4429434 100644 --- a/src/neospy/rust/state.rs +++ b/src/neospy/rust/state.rs @@ -57,7 +57,7 @@ impl PyState { /// /// Parameters /// ---------- - /// frame : Frame + /// frame : Frames /// New frame to change to. pub fn change_frame(&self, frame: PyFrames) -> PyResult { let mut state = self.0.clone(); diff --git a/src/neospy/rust/vector.rs b/src/neospy/rust/vector.rs index b59aa2b..c412e61 100644 --- a/src/neospy/rust/vector.rs +++ b/src/neospy/rust/vector.rs @@ -10,7 +10,6 @@ use pyo3::prelude::*; use pyo3::{PyResult, Python}; /// Vector class which is a vector along with a reference frame. -/// #[pyclass(sequence, frozen, module = "neospy")] #[derive(Clone, Debug)] pub struct Vector { @@ -79,10 +78,14 @@ impl Vector { /// /// Parameters /// ---------- - /// el : Elevation above the X-Y plane of the frame. (Degrees) - /// az : Azimuthal angle on the X-Y plane for the frame. (Degrees) - /// frame : Frame of reference which define the coordinate axis. - /// r : Optional length of the vector, defaults to 1. + /// el : float + /// Elevation above the X-Y plane of the frame. (Degrees) + /// az : float + /// Azimuthal angle on the X-Y plane for the frame. (Degrees) + /// frame : Frames + /// Frame of reference which define the coordinate axis. + /// r : + /// Optional length of the vector, defaults to 1. #[staticmethod] pub fn from_el_az(el: f64, az: f64, r: f64, frame: PyFrames) -> Self { let (el_sin, el_cos) = (FRAC_PI_2 - el.to_radians()).sin_cos(); @@ -97,9 +100,12 @@ impl Vector { /// /// Parameters /// ---------- - /// lat : Latitude in the ecliptic frame. (Degrees) - /// lon : Longitude in the ecliptic frame. (Degrees) - /// r : Optional length of the vector, defaults to 1. + /// lat : float + /// Latitude in the ecliptic frame. (Degrees) + /// lon : float + /// Longitude in the ecliptic frame. (Degrees) + /// r : + /// Optional length of the vector, defaults to 1. #[staticmethod] pub fn from_lat_lon(lat: f64, lon: f64, r: Option) -> Self { Self::from_el_az(lat, lon, r.unwrap_or(1.0), PyFrames::Ecliptic) @@ -109,9 +115,12 @@ impl Vector { /// /// Parameters /// ---------- - /// ra : Right Ascension in the equatorial frame. (Degrees) - /// dec : Declination in the equatorial frame. (Degrees) - /// r : Optional length of the vector, defaults to 1. + /// ra : float + /// Right Ascension in the equatorial frame. (Degrees) + /// dec : float + /// Declination in the equatorial frame. (Degrees) + /// r : + /// Optional length of the vector, defaults to 1. #[staticmethod] pub fn from_ra_dec(ra: f64, dec: f64, r: Option) -> Self { Self::from_el_az(dec, ra, r.unwrap_or(1.0), PyFrames::Equatorial) diff --git a/src/neospy/spice.py b/src/neospy/spice.py index e3deb66..bdb4ba2 100644 --- a/src/neospy/spice.py +++ b/src/neospy/spice.py @@ -13,9 +13,17 @@ from .cache import cached_file_download, cache_path from .vector import Frames, State -__all__ = ["SpiceKernels"] +__all__ = ["SpiceKernels", "SpkInfo"] + SpkInfo = namedtuple("SpkInfo", "name, jd_start, jd_end, center, frame, spk_type") +"""Information contained within a Spice Kernel.""" +SpkInfo.name.__doc__ = "Name of the object." +SpkInfo.jd_start.__doc__ = "JD date of the start of the spice segment." +SpkInfo.jd_end.__doc__ = "JD date of the end of the spice segment." +SpkInfo.center.__doc__ = "Reference Center NAIF ID." +SpkInfo.frame.__doc__ = "Frame of reference." +SpkInfo.spk_type.__doc__ = "SPK Segment Type ID." def _validate_time(time: Union[float, Time]) -> float: @@ -182,7 +190,7 @@ def loaded_object_info(cls, desig: Union[int, str]) -> list[SpkInfo]: Parameters ---------- - name : + desig : Name or integer id value of the object. """ name, naif = cls.name_lookup(desig) diff --git a/src/neospy/wise.py b/src/neospy/wise.py index 632ca1c..51dacb6 100644 --- a/src/neospy/wise.py +++ b/src/neospy/wise.py @@ -471,7 +471,7 @@ def plot_frames( zoom : If the image should be centered and zoomed in on the provided RA/DEC. This can also be a number, which will change the zoom level. - band : + bands : Bands of WISE to plot, if not provided this will plot all bands for the given mission phase. """