PR changes & docs

Author: AndreiKingsley

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/jupyter/Integration.kt

@@ -57,7 +57,6 @@ import org.jetbrains.kotlinx.jupyter.api.libraries.JupyterIntegration
 import org.jetbrains.kotlinx.jupyter.api.libraries.resources
 import kotlin.reflect.KClass
 import kotlin.reflect.KProperty
-import kotlin.reflect.KType
 import kotlin.reflect.full.isSubtypeOf
 
 /** Users will get an error if their Kotlin Jupyter kernel is older than this version. */
@@ -70,29 +69,6 @@ internal class Integration(private val notebook: Notebook, private val options:
 
     val version = options["v"]
 
-    private fun KotlinKernelHost.execute(codeWithConverter: CodeWithConverter, argument: String): VariableName? {
-        val code = codeWithConverter.with(argument)
-        return if (code.isNotBlank()) {
-            val result = execute(code)
-            if (codeWithConverter.hasConverter) {
-                result.name
-            } else {
-                null
-            }
-        } else {
-            null
-        }
-    }
-
-    private fun KotlinKernelHost.execute(
-        codeWithConverter: CodeWithConverter,
-        property: KProperty<*>,
-        type: KType,
-    ): VariableName? {
-        val variableName = "(${property.name}${if (property.returnType.isMarkedNullable) "!!" else ""} as $type)"
-        return execute(codeWithConverter, variableName)
-    }
-
     private fun KotlinKernelHost.updateImportDataSchemaVariable(
         importDataSchema: ImportDataSchema,
         property: KProperty<*>,

core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/jupyter/execute.kt

@@ -0,0 +1,30 @@
+package org.jetbrains.kotlinx.dataframe.jupyter
+
+import org.jetbrains.kotlinx.dataframe.codeGen.CodeWithConverter
+import org.jetbrains.kotlinx.jupyter.api.KotlinKernelHost
+import org.jetbrains.kotlinx.jupyter.api.VariableName
+import kotlin.reflect.KProperty
+import kotlin.reflect.KType
+
+internal fun KotlinKernelHost.execute(codeWithConverter: CodeWithConverter, argument: String): VariableName? {
+    val code = codeWithConverter.with(argument)
+    return if (code.isNotBlank()) {
+        val result = execute(code)
+        if (codeWithConverter.hasConverter) {
+            result.name
+        } else {
+            null
+        }
+    } else {
+        null
+    }
+}
+
+internal fun KotlinKernelHost.execute(
+    codeWithConverter: CodeWithConverter,
+    property: KProperty<*>,
+    type: KType,
+): VariableName? {
+    val variableName = "(${property.name}${if (property.returnType.isMarkedNullable) "!!" else ""} as $type)"
+    return execute(codeWithConverter, variableName)
+}

dataframe-geo/build.gradle.kts

@@ -6,14 +6,14 @@ plugins {
         alias(kotlin.jvm)
         alias(publisher)
         alias(jupyter.api)
+        //alias(ktlint)
     }
 }
 
 group = "org.jetbrains.kotlinx"
 
 repositories {
-    // geo repositories should come before Maven Central
-    maven("https://maven.geotoolkit.org")
+    // geo repository should come before Maven Central
     maven("https://repo.osgeo.org/repository/release")
     mavenCentral()
 }
@@ -22,7 +22,6 @@ repositories {
 // jai core dependency should be excluded from geotools dependencies and added separately
 fun ExternalModuleDependency.excludeJaiCore() = exclude("javax.media", "jai_core")
 
-
 dependencies {
     api(project(":core"))
 
@@ -42,6 +41,7 @@ dependencies {
     implementation(libs.ktor.client.content.negotiation)
     implementation(libs.ktor.serialization.kotlinx.json)
 
+    testImplementation(kotlin("test"))
 }
 
 tasks.withType<KotlinCompile>().configureEach {
@@ -64,7 +64,6 @@ tasks.processJupyterApiResources {
     libraryProducers = listOf("org.jetbrains.kotlinx.dataframe.jupyter.IntegrationGeo")
 }
 
-
 tasks.test {
     useJUnitPlatform()
 }

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/GeoDataFrame.kt

@@ -7,22 +7,50 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.api.update
 import org.jetbrains.kotlinx.dataframe.api.with
 
-class GeoDataFrame<T : GeoFrame>(val df: DataFrame<T>, val crs: CoordinateReferenceSystem?) {
+/**
+ * A data structure representing a geographical DataFrame, combining spatial data with
+ * an optional Coordinate Reference System (CRS).
+ *
+ * @param T The type parameter extending `WithGeometry`, indicating the presence of a geometry column.
+ * @property df The underlying `DataFrame` containing geometries.
+ * @property crs The coordinate reference system associated with the data, if any.
+ */
+class GeoDataFrame<T : WithGeometry>(val df: DataFrame<T>, val crs: CoordinateReferenceSystem?) {
+    /**
+     * Updates the `GeoDataFrame` using a specified transformation block on the underlying DataFrame.
+     *
+     * @param updateBlock The block defining the transformations to be applied to the DataFrame.
+     * @return A new `GeoDataFrame` instance with updated data and the same CRS.
+     */
     fun update(updateBlock: DataFrame<T>.() -> DataFrame<T>): GeoDataFrame<T> {
         return GeoDataFrame(df.updateBlock(), crs)
     }
 
-    fun applyCRS(targetCRS: CoordinateReferenceSystem? = null): GeoDataFrame<T> {
-        if (targetCRS == this.crs) return this
+    /**
+     * Transforms the geometries to a specified Coordinate Reference System (CRS).
+     *
+     * This function reprojects the geometry data from the current CRS to a target CRS.
+     * If no target CRS is specified and the `GeoDataFrame` has no CRS, WGS 84 is used by default.
+     *
+     * @param targetCrs The target CRS for transformation.
+     * @return A new `GeoDataFrame` with reprojected geometries and the specified CRS.
+     */
+    fun applyCrs(targetCrs: CoordinateReferenceSystem): GeoDataFrame<T> {
+        if (targetCrs == this.crs) return this
         // Use WGS 84 by default TODO
         val sourceCRS: CoordinateReferenceSystem = this.crs ?: DEFAULT_CRS
-        val transform = CRS.findMathTransform(sourceCRS, targetCRS, true)
+        val transform = CRS.findMathTransform(sourceCRS, targetCrs, true)
         return GeoDataFrame(
             df.update { geometry }.with { JTS.transform(it, transform) },
-            targetCRS
+            targetCrs
         )
     }
 
+    override fun equals(other: Any?): Boolean {
+        if (other !is GeoDataFrame<*>) return false
+        return df == other.df && crs == other.crs
+    }
+
     companion object {
         val DEFAULT_CRS = CRS.decode("EPSG:4326", true)
     }

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/GeoFrame.kt renamed to dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/WithGeometry.kt

@@ -8,28 +8,28 @@ import org.locationtech.jts.geom.MultiPolygon
 import org.locationtech.jts.geom.Polygon
 
 @DataSchema
-interface GeoFrame {
+interface WithGeometry {
     val geometry: Geometry
 }
 
 @DataSchema
-interface PolygonGeoFrame : GeoFrame {
+interface WithPolygon : WithGeometry {
     override val geometry: Polygon
 }
 
 @DataSchema
-interface MultiPolygonGeoFrame : GeoFrame {
+interface WithMultiPolygon : WithGeometry {
     override val geometry: MultiPolygon
 }
 
 @get:JvmName("geometry")
-val <T : GeoFrame> ColumnsContainer<T>.geometry: DataColumn<Geometry>
+val <T : WithGeometry> ColumnsContainer<T>.geometry: DataColumn<Geometry>
     get() = get("geometry") as DataColumn<Geometry>
 
 @get:JvmName("geometryPolygon")
-val <T : PolygonGeoFrame> ColumnsContainer<T>.geometry: DataColumn<Polygon>
+val <T : WithPolygon> ColumnsContainer<T>.geometry: DataColumn<Polygon>
     get() = get("geometry") as DataColumn<Polygon>
 
 @get:JvmName("geometryMultiPolygon")
-val <T : MultiPolygonGeoFrame> ColumnsContainer<T>.geometry: DataColumn<MultiPolygon>
+val <T : WithMultiPolygon> ColumnsContainer<T>.geometry: DataColumn<MultiPolygon>
     get() = get("geometry") as DataColumn<MultiPolygon>

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/bounds.kt

@@ -4,6 +4,14 @@ import org.geotools.geometry.jts.ReferencedEnvelope
 import org.jetbrains.kotlinx.dataframe.api.asIterable
 import org.jetbrains.kotlinx.dataframe.geo.jts.computeBounds
 
+/**
+ * Computes the bounding envelope for all geometries in a `GeoDataFrame`,
+ * considering the specified coordinate reference system (CRS).
+ *
+ * @receiver The `GeoDataFrame` containing the geometries for which to compute bounds.
+ * @return The bounding envelope that includes all geometries,
+ * associated with the CRS of the `GeoDataFrame`.
+ */
 fun GeoDataFrame<*>.bounds(): ReferencedEnvelope {
     return ReferencedEnvelope(df.geometry.asIterable().computeBounds(), crs)
 }

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/geotools/ToGeoDataFrame.kt renamed to dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/geotools/toGeoDataFrame.kt

@@ -10,7 +10,7 @@ import org.jetbrains.kotlinx.dataframe.DataFrame
 import org.jetbrains.kotlinx.dataframe.api.Infer
 import org.jetbrains.kotlinx.dataframe.api.toDataFrame
 import org.jetbrains.kotlinx.dataframe.geo.GeoDataFrame
-import org.jetbrains.kotlinx.dataframe.geo.GeoFrame
+import org.jetbrains.kotlinx.dataframe.geo.WithGeometry
 import org.locationtech.jts.geom.Geometry
 
 fun SimpleFeatureCollection.toGeoDataFrame(): GeoDataFrame<*> {
@@ -24,7 +24,7 @@ fun SimpleFeatureCollection.toGeoDataFrame(): GeoDataFrame<*> {
     val geometryAttribute = attributeDescriptors?.find { it is GeometryDescriptor }
         ?: throw IllegalArgumentException("No geometry attribute")
 
-    // In GeoJSON the crs attribute is optional
+    // In GeoJSON, the crs attribute is optional
     val crs: CoordinateReferenceSystem? = (geometryAttribute as GeometryDescriptor).coordinateReferenceSystem
 
     val data = dataAttributes.associate { it.localName to ArrayList<Any?>() }
@@ -52,5 +52,5 @@ fun SimpleFeatureCollection.toGeoDataFrame(): GeoDataFrame<*> {
 
     val geometryColumn = DataColumn.create("geometry", geometries, Infer.Type)
 
-    return GeoDataFrame((data.toDataFrame() + geometryColumn) as DataFrame<GeoFrame>, crs)
+    return GeoDataFrame((data.toDataFrame() + geometryColumn) as DataFrame<WithGeometry>, crs)
 }

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/io/read.kt

@@ -10,20 +10,20 @@ import org.jetbrains.kotlinx.dataframe.io.asURL
 import java.net.URL
 
 
-fun GeoDataFrame.Companion.readGeoJSON(path: String): GeoDataFrame<*> {
-    return readGeoJSON(asURL(path))
+fun GeoDataFrame.Companion.readGeoJson(path: String): GeoDataFrame<*> {
+    return readGeoJson(asURL(path))
 }
 
-fun GeoDataFrame.Companion.readGeoJSON(url: URL): GeoDataFrame<*> {
+fun GeoDataFrame.Companion.readGeoJson(url: URL): GeoDataFrame<*> {
     return (FeatureJSON().readFeatureCollection(url.openStream()) as SimpleFeatureCollection).toGeoDataFrame()
 }
 
-fun DataFrame.Companion.readGeoJSON(path: String): GeoDataFrame<*> {
-    return GeoDataFrame.readGeoJSON(path)
+fun DataFrame.Companion.readGeoJson(path: String): GeoDataFrame<*> {
+    return GeoDataFrame.readGeoJson(path)
 }
 
-fun DataFrame.Companion.readGeoJSON(url: URL): GeoDataFrame<*> {
-    return GeoDataFrame.readGeoJSON(url)
+fun DataFrame.Companion.readGeoJson(url: URL): GeoDataFrame<*> {
+    return GeoDataFrame.readGeoJson(url)
 }
 
 fun GeoDataFrame.Companion.readShapefile(path: String): GeoDataFrame<*> {

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/io/write.kt

@@ -3,6 +3,7 @@ package org.jetbrains.kotlinx.dataframe.geo.io
 import org.geotools.api.data.FileDataStoreFinder
 import org.geotools.api.data.SimpleFeatureStore
 import org.geotools.api.data.Transaction
+import org.geotools.feature.simple.SimpleFeatureTypeBuilder
 import org.geotools.geojson.feature.FeatureJSON
 import org.jetbrains.kotlinx.dataframe.geo.GeoDataFrame
 import org.jetbrains.kotlinx.dataframe.geo.geotools.toSimpleFeatureCollection
@@ -12,6 +13,8 @@ import java.io.File
 fun GeoDataFrame<*>.writeGeoJson(path: String): Unit = writeGeoJson(File(path))
 
 fun GeoDataFrame<*>.writeGeoJson(file: File) {
+
+    // TODO: adds ids that breaks order of reading
     val featureJSON = FeatureJSON()
     file.outputStream().use { outputStream ->
         featureJSON.writeFeatureCollection(toSimpleFeatureCollection(), outputStream)
@@ -39,8 +42,9 @@ fun GeoDataFrame<*>.writeShapefile(directory: File) {
     val featureCollection = toSimpleFeatureCollection(fileName, true)
 
     val schema = featureCollection.schema
+    val schemaWithCrs = SimpleFeatureTypeBuilder.retype(schema, crs ?: GeoDataFrame.DEFAULT_CRS)
 
-    dataStore.createSchema(schema)
+    dataStore.createSchema(schemaWithCrs)
 
     val featureSource = dataStore.getFeatureSource(fileName) as SimpleFeatureStore
     val transaction = Transaction.AUTO_COMMIT

dataframe-geo/src/main/kotlin/org/jetbrains/kotlinx/dataframe/geo/jts/bounds.kt

@@ -3,6 +3,13 @@ package org.jetbrains.kotlinx.dataframe.geo.jts
 import org.locationtech.jts.geom.Envelope
 import org.locationtech.jts.geom.Geometry
 
+/**
+ * Computes the bounding envelope for a collection of geometries.
+ *
+ *
+ * @receiver The collection of geometries for which to compute the bounds.
+ * @return The minimal envelope that encompasses all geometries in the collection.
+ */
 fun Iterable<Geometry>.computeBounds(): Envelope {
     val bounds = Envelope()
     forEach { geometry -> bounds.expandToInclude(geometry.envelopeInternal) }