chore: update test and docs (#2)

Author: Beforerr

.gitignore

@@ -1,2 +1,4 @@
-/Manifest.toml
+Manifest.toml
 .CondaPkg
+themis_data/thd/l2/fgm/2020/thd_l2_fgm_20200420_v01.cdf
+omni_data

Project.toml

@@ -1,7 +1,7 @@
 name = "PySPEDAS"
 uuid = "668d2cef-03a7-4c36-a521-7d1c6ddc8846"
 authors = ["Beforerr <[email protected]> and contributors"]
-version = "1.0.0-DEV"
+version = "0.1.0"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
@@ -10,5 +10,8 @@ PythonCall = "6099a3de-0909-46bc-b1f4-468b9a2dfc0d"
 SpaceDataModel = "0b37b92c-f0c5-4a52-bd5c-390dec20857c"
 
 [compat]
+Dates = "1"
 DimensionalData = "0.29"
+PythonCall = "0.9.23"
+SpaceDataModel = "0.1.8"
 julia = "1.10"

README.md

@@ -1,9 +1,16 @@
 # PySPEDAS.jl
 
 [![Build Status](https://github.com/Beforerr/PySPEDAS.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/Beforerr/PySPEDAS.jl/actions/workflows/CI.yml?query=branch%3Amain)
+[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 
+A Julia wrapper around [PySPEDAS](https://github.com/spedas/pyspedas): Python-based Space Physics Environment Data Analysis Software.
 
-A simple Julia wrapper around [PySPEDAS](https://github.com/spedas/pyspedas): Python-based Space Physics Environment Data Analysis Software.
+## Installation
+
+```julia
+using Pkg
+Pkg.add("PySPEDAS")
+```
 
 ## Demo
 
@@ -32,3 +39,5 @@ mms.fgm(trange, time_clip=true, probe=2)
 ```
 
 Each mission is represented as a `Project` type, which wraps the underlying Python module.
+
+> [!NOTE] > [SPEDAS.jl](https://github.com/Beforerr/SPEDAS.jl) provides a native Julia counterpart with cross-language validation and comparison. See [SPEDAS.jl Documentation](https://beforerr.github.io/SPEDAS.jl/dev/validation/pyspedas/) for more details.

src/DimensionalData.jl

@@ -2,15 +2,15 @@ using DimensionalData
 import DimensionalData: DimArray, dims
 import DimensionalData.Lookups: NoLookup
 
-function get_xarray_dims(x; transpose=false)
+function get_xarray_dims(x; transpose = false)
     dim_names = tuple(Symbol.(collect(x.dims))...)
     dim_names = transpose ? reverse(dim_names) : dim_names
     coord_names = Symbol.(collect(x.coords.keys()))
     lookups_values = map(dim_names) do dim
         if dim in coord_names
             coord_py = getproperty(x, dim).data
             coord_type = string(coord_py.dtype.name)
-            coord = coord_type == "datetime64[ns]" ? pyconvert_time(coord_py) : PyArray(coord_py; copy=false)
+            coord = coord_type == "datetime64[ns]" ? pyconvert_time(coord_py) : PyArray(coord_py; copy = false)
             Dim{dim}(coord)
         else
             Dim{dim}(NoLookup())
@@ -21,8 +21,24 @@ end
 
 DimensionalData.dims(v::TplotVariable) = Tuple(get_xarray_dims(v.py))
 
+"""
+    get_data(::Type{DimArray}, name; kwargs...)
+
+Retrieve data from a tplot variable and convert it to a `DimensionalData.DimArray.
+"""
+get_data(::Type{DimArray}, name; kwargs...) = pyconvert_dataarray(get_data(name; kwargs...))
+
+"""
+    get_data(::Type{T<:AbstractDimStack}, names; kwargs...)
+
+Retrieve multiple tplot variables and combine them into a DimensionalData stack.
+"""
+function get_data(::Type{T}, names; kwargs...) where {T <: AbstractDimStack}
+    return T(pyconvert_dataarray.(get_data.(names; kwargs...)))
+end
+
 function DimensionalData.DimArray(var::TplotVariable; kwargs...)
-    pyconvert_dataarray(var.py; kwargs...)
+    return pyconvert_dataarray(var.py; kwargs...)
 end
 
 """
@@ -33,13 +49,13 @@ Convert a `xarray.DataArray` to a `DimensionalData.DataArray`.
 # Reference:
 - https://github.com/rafaqz/DimensionalData.jl/blob/main/ext/DimensionalDataPythonCall.jl
 """
-function pyconvert_dataarray(x; transpose=false)
+function pyconvert_dataarray(x; transpose = false)
     data_npy = transpose ? x.data.T : x.data
-    data = PyArray(data_npy; copy=false)
+    data = PyArray(data_npy; copy = false)
 
     dims = get_xarray_dims(x; transpose)
-    metadata = pyconvert(Dict{Any,Any}, x.attrs)
+    metadata = pyconvert(Dict{Any, Any}, x.attrs)
     array_name = pyis(x.name, pybuiltins.None) ? nothing : string(x.name)
 
-    return DimArray(data, dims; name=array_name, metadata)
-end
+    return DimArray(data, dims; name = array_name, metadata)
+end

src/PySPEDAS.jl

@@ -7,8 +7,8 @@ using SpaceDataModel
 using SpaceDataModel: AbstractDataVariable
 import SpaceDataModel: times
 
-export pyspedas, pytplot
-export tplot, get_data
+export pyspedas
+export pytplot, get_data
 export Project, TplotVariable
 
 include("types.jl")
@@ -18,15 +18,13 @@ include("DimensionalData.jl")
 
 using .Projects
 
-const TnamesType = Union{AbstractArray,Tuple}
+const TnamesType = Union{AbstractArray, Tuple}
 
 const pyspedas = pynew()
-const pytplot = pynew()
 const pyns = pynew()
 
 function __init__()
     PythonCall.pycopy!(pyspedas, pyimport("pyspedas"))
-    PythonCall.pycopy!(pytplot, pyimport("pytplot"))
     PythonCall.pycopy!(pyns, pyimport("numpy").timedelta64(1, "ns"))
     for p in PROJECTS
         try
@@ -37,10 +35,11 @@ function __init__()
             @warn "Failed to load project $(p): $e"
         end
     end
+    return
 end
 
-tplot(args...) = @pyconst(pyspedas.tplot)(args...)
-tplot(tnames::TnamesType, args...) = @pyconst(pyspedas.tplot)(pylist(tnames), args...)
+pytplot(args...) = @pyconst(pyspedas.tplot)(args...)
+pytplot(tnames::TnamesType, args...) = @pyconst(pyspedas.tplot)(pylist(tnames), args...)
 
 """
     get_data(name; xarray=true, kwargs...)
@@ -49,35 +48,19 @@ Retrieve data from a tplot variable by `name`.
 
 By default, returns an xarray DataArray object. If `xarray` is set to false, returns a tuple of (times, data).
 """
-get_data(name; xarray=true, kwargs...) = pyspedas.get_data(name; xarray, kwargs...)
+get_data(name; xarray = true, kwargs...) = pyspedas.get_data(name; xarray, kwargs...)
 
-"""
-    get_data(::Type{DimArray}, name; kwargs...)
-
-Retrieve data from a tplot variable and convert it to a `DimensionalData.DimArray.
-"""
-get_data(::Type{DimArray}, name; kwargs...) = pyconvert_dataarray(get_data(name; kwargs...))
-
-"""
-    get_data(::Type{T<:AbstractDimStack}, names; kwargs...)
-
-Retrieve multiple tplot variables and combine them into a DimensionalData stack.
-"""
-function get_data(::Type{T}, names; kwargs...) where {T<:AbstractDimStack}
-    T(pyconvert_dataarray.(get_data.(names; kwargs...)))
-end
-
-function demo_get_data(; trange=["2020-04-20/06:00", "2020-04-20/08:00"])
-    pyspedas.projects.themis.fgm(; trange, time_clip=true, probe='d')
-    get_data(DimArray, "thd_fgs_gsm")
+function demo_get_data(; trange = ["2017-03-23/00:00:00", "2017-04-23/23:59:59"])
+    pyspedas.projects.omni.data(; trange)
+    return get_data(DimArray, "SYM_H")
 end
 
-function demo(; trange=["2020-04-20/06:00", "2020-04-20/08:00"])
-    pyspedas.projects.solo.mag(; trange, time_clip=true)
-    pyspedas.projects.psp.fields(; trange, time_clip=true)
-    pyspedas.projects.mms.fgm(; trange, time_clip=true, probe=2)
-    pyspedas.projects.themis.fgm(; trange, time_clip=true, probe='d')
-    tplot(["B_RTN", "psp_fld_l2_mag_RTN", "mms2_fgm_b_gsm_srvy_l2_bvec", "thd_fgs_gsm"])
+function demo(; trange = ["2020-04-20/06:00", "2020-04-20/08:00"])
+    pyspedas.projects.solo.mag(; trange, time_clip = true)
+    pyspedas.projects.psp.fields(; trange, time_clip = true)
+    pyspedas.projects.mms.fgm(; trange, time_clip = true, probe = 2)
+    pyspedas.projects.themis.fgm(; trange, time_clip = true, probe = 'd')
+    return pytplot(["B_RTN", "psp_fld_l2_mag_RTN", "mms2_fgm_b_gsm_srvy_l2_bvec", "thd_fgs_gsm"])
 end
 
 end

src/types.jl

@@ -15,16 +15,16 @@ Project(name) = Project(name, pynew(), Ref{Vector{Symbol}}())
 # This somehow could prevent the Segmentation fault, see also https://github.com/JuliaPy/PythonCall.jl/issues/586
 attributes(p::Project) = p.attributes[]
 
-struct TplotVariable{T,N} <: AbstractDataVariable{T,N}
+struct TplotVariable{T, N} <: AbstractDataVariable{T, N}
     name::Symbol
-    data::PyArray{T,N}
+    data::PyArray{T, N}
     py::Py
 end
 
 function TplotVariable(name)
-    py = pytplot.data_quants[String(name)]
-    data = PyArray(py.data; copy=false)
-    TplotVariable(Symbol(name), data, py)
+    py = @pyconst(pyimport("pytplot").data_quants)[String(name)]
+    data = PyArray(py.data; copy = false)
+    return TplotVariable(Symbol(name), data, py)
 end
 
 SpaceDataModel.times(var::TplotVariable) = pyconvert_time(var.py.time.data)
@@ -36,7 +36,7 @@ end
 function (f::LoadFunction)(args...; kwargs...)
     tvars_py = f.py(args...; kwargs...)
     tvars = pyconvert(Vector{Symbol}, tvars_py)
-    NamedTuple{tuple(tvars...)}(TplotVariable.(tvars))
+    return NamedTuple{tuple(tvars...)}(TplotVariable.(tvars))
 end
 
 # Allow calling methods on the Python module
@@ -54,5 +54,5 @@ Base.show(io::IO, p::Project) = print(io, "SPEDAS Project: $(p.name)")
 Base.show(io::IO, var::TplotVariable) = print(io, var.py.data)
 function Base.show(io::IO, m::MIME"text/plain", var::TplotVariable)
     println(io, "Tplot Variable: $(var.name)")
-    show(io, m, var.py)
-end
+    return show(io, m, var.py)
+end

test/Manifest.toml

@@ -1,10 +1,13 @@
 using TestItems, TestItemRunner
 
+@run_package_tests filter = ti -> !(:skipci in ti.tags)
+
 @testitem "Aqua" begin
     using Aqua
     Aqua.test_all(PySPEDAS)
 end
 
 @testitem "PySPEDAS.jl" begin
-    @test_nowarn PySPEDAS.demo_get_data()
+    using PySPEDAS.DimensionalData
+    @test PySPEDAS.demo_get_data() isa DimArray
 end