diff --git a/README.md b/README.md index 02af994..6b5e42e 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,9 @@ with the ability to add metadata and overload behavior at every level. (For inst Additionally, [arrow-julia](https://github.com/apache/arrow-julia) provides Julia access to the Apache Arrow format, which is also good for in-memory interprocess communication, but the Awkward Array format is a superset of this format to make it easier to represent intermediate calculations. +## Documenttion +[User Guilde](https://juliahep.github.io/AwkwardArray.jl/dev/) + ## Reading and writing the same data type AwkwardArray.jl is a reimplementation of the concept of Awkward Arrays in Julia, taking advantage of Julia's capabilities. Python's Awkward Array has other backends for sending data to JIT-compiled languages—Numba (CPU and GPU) and C++ (with cppyy and ROOT's RDataFrame)—but as read-only views, owned exclusively by Python, for brief excursions only. Creating new Awkward Arrays in those JIT-compiled languages requires special tools, [ak.ArrayBuilder](https://awkward-array.org/doc/main/reference/generated/ak.ArrayBuilder.html) (discovers data type during iteration) and [LayoutBuilder](https://awkward-array.org/doc/main/user-guide/how-to-use-header-only-layoutbuilder.html) (fills a specified data type; faster). diff --git a/docs/assets/logo-300px.ico b/docs/assets/logo-300px.ico new file mode 100644 index 0000000..c3e182a Binary files /dev/null and b/docs/assets/logo-300px.ico differ diff --git a/docs/make.jl b/docs/make.jl index d24c05d..d63ca59 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -4,12 +4,12 @@ makedocs(; modules=[AwkwardArray], format = Documenter.HTML( prettyurls = get(ENV, "CI", nothing) == "true", - assets=String[], + assets=String["img/logo-300px.ico"], ), pages=[ "Introduction" => "index.md", "Example Usage" => "exampleusage.md", - "APIs" => "api.md", + "Reference Guide" => "api.md", "LICENSE" => "LICENSE.md", ], repo="https://github.com/JuliaHEP/AwkwardArray.jl/blob/{commit}{path}#L{line}", diff --git a/docs/src/api.md b/docs/src/api.md index c3684bb..4c8dc2d 100644 --- a/docs/src/api.md +++ b/docs/src/api.md @@ -1 +1,48 @@ -# API \ No newline at end of file +## List of functions + +Every `Content` subclass has the following built-in functions: + +* `Base.length` +* `Base.size` (1-tuple of `length`) +* `Base.firstindex`, `Base.lastindex` (1-based or inherited from its index) +* `Base.getindex`: select by `Int` (single item), `UnitRange{Int}` (slice), and `Symbol` (record field) +* `Base.iterate` +* `Base.(==)` (equality defined by values: a `ListOffsetArray` and a `ListArray` may be considered the same) +* `Base.push!` +* `Base.append!` +* `Base.show` + +They also have the following functions for manipulating and checking structure: + +* `AwkwardArray.parameters_of`: gets all parameters +* `AwkwardArray.has_parameter`: returns true if a parameter exists +* `AwkwardArray.get_parameter`: returns a parameter or raises an error +* `AwkwardArray.with_parameter`: returns a copy of this node with a specified parameter +* `AwkwardArray.copy`: shallow-copy of the array, allowing properties to be replaced +* `AwkwardArray.is_valid`: verifies that the structure adheres to Awkward Array's protocol + +They have the following functions for filling an array: + +* `AwkwardArray.end_list!`: closes off a `ListType` array (`ListOffsetArray`, `ListArray`, or `RegularArray`) in the manner of Python's [ak.ArrayBuilder](https://awkward-array.org/doc/main/reference/generated/ak.ArrayBuilder.html) (no `begin_list` is necessary) +* `AwkwardArray.end_record!`: closes off a `RecordArray` +* `AwkwardArray.end_tuple!`: closes off a `TupleArray` +* `AwkwardArray.push_null!`: pushes a missing value onto `OptionType` arrays (`IndexedOptionArray`, `ByteMaskedArray`, `BitMaskedArray`, or `UnmaskedArray`) +* `AwkwardArray.push_dummy!`: pushes an unspecified value onto the array (used by `ByteMaskedArray` and `BitMaskedArray`, which need to have a placeholder in memory behind each `missing` value) + +`RecordArray` and `TupleArray` have the following for selecting fields (as opposed to rows): + +* `AwkwardArray.slot`: gets a `RecordArray` or `TupleArray` field, to avoid conflicts with `Base.getindex` for `TupleArrays` (both use integers to select a field) +* `AwkwardArray.Record`: scalar representation of an item from a `RecordArray` +* `AwkwardArray.Tuple`: scalar representation of an item from a `TupleArray` (note: not the same as `Base.Tuple`) + +`UnionArray` has the following for dealing with specializations: + +* `AwkwardArray.Specialization`: selects a `UnionArray` specialization for `push!`, `append!`, etc. + +Finally, all `Content` subclasses can be converted with the following: + +* `AwkwardArray.layout_for`: returns an appropriately-nested `Content` type for a given Julia type (`DataType`) +* `AwkwardArray.from_iter`: converts Julia data into an Awkward Array +* `AwkwardArray.to_vector`: converts an Awkward Array into Julia data +* `AwkwardArray.from_buffers`: constructs an Awkward Array from a Form (JSON), length, and buffers for zero-copy passing from Python +* `AwkwardArray.to_buffers`: deconstructs an Awkward Array into a Form (JSON), length, and buffers for zero-copy passing to Python diff --git a/docs/src/index.md b/docs/src/index.md index 1d8c131..d16c577 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -135,54 +135,3 @@ String ``` Most applications of `behavior` apply to `RecordArrays` (e.g. [Vector](https://github.com/scikit-hep/vector) in Python). - -## List of functions - -Every `Content` subclass has the following built-in functions: - -* `Base.length` -* `Base.size` (1-tuple of `length`) -* `Base.firstindex`, `Base.lastindex` (1-based or inherited from its index) -* `Base.getindex`: select by `Int` (single item), `UnitRange{Int}` (slice), and `Symbol` (record field) -* `Base.iterate` -* `Base.(==)` (equality defined by values: a `ListOffsetArray` and a `ListArray` may be considered the same) -* `Base.push!` -* `Base.append!` -* `Base.show` - -They also have the following functions for manipulating and checking structure: - -* `AwkwardArray.parameters_of`: gets all parameters -* `AwkwardArray.has_parameter`: returns true if a parameter exists -* `AwkwardArray.get_parameter`: returns a parameter or raises an error -* `AwkwardArray.with_parameter`: returns a copy of this node with a specified parameter -* `AwkwardArray.copy`: shallow-copy of the array, allowing properties to be replaced -* `AwkwardArray.is_valid`: verifies that the structure adheres to Awkward Array's protocol - -They have the following functions for filling an array: - -* `AwkwardArray.end_list!`: closes off a `ListType` array (`ListOffsetArray`, `ListArray`, or `RegularArray`) in the manner of Python's [ak.ArrayBuilder](https://awkward-array.org/doc/main/reference/generated/ak.ArrayBuilder.html) (no `begin_list` is necessary) -* `AwkwardArray.end_record!`: closes off a `RecordArray` -* `AwkwardArray.end_tuple!`: closes off a `TupleArray` -* `AwkwardArray.push_null!`: pushes a missing value onto `OptionType` arrays (`IndexedOptionArray`, `ByteMaskedArray`, `BitMaskedArray`, or `UnmaskedArray`) -* `AwkwardArray.push_dummy!`: pushes an unspecified value onto the array (used by `ByteMaskedArray` and `BitMaskedArray`, which need to have a placeholder in memory behind each `missing` value) - -`RecordArray` and `TupleArray` have the following for selecting fields (as opposed to rows): - -* `AwkwardArray.slot`: gets a `RecordArray` or `TupleArray` field, to avoid conflicts with `Base.getindex` for `TupleArrays` (both use integers to select a field) -* `AwkwardArray.Record`: scalar representation of an item from a `RecordArray` -* `AwkwardArray.Tuple`: scalar representation of an item from a `TupleArray` (note: not the same as `Base.Tuple`) - -`UnionArray` has the following for dealing with specializations: - -* `AwkwardArray.Specialization`: selects a `UnionArray` specialization for `push!`, `append!`, etc. - -Finally, all `Content` subclasses can be converted with the following: - -* `AwkwardArray.layout_for`: returns an appropriately-nested `Content` type for a given Julia type (`DataType`) -* `AwkwardArray.from_iter`: converts Julia data into an Awkward Array -* `AwkwardArray.to_vector`: converts an Awkward Array into Julia data -* `AwkwardArray.from_buffers`: constructs an Awkward Array from a Form (JSON), length, and buffers for zero-copy passing from Python -* `AwkwardArray.to_buffers`: deconstructs an Awkward Array into a Form (JSON), length, and buffers for zero-copy passing to Python - -_(This will turn into proper documentation, eventually.)_ diff --git a/ext/AwkwardPythonCallExt/README.md b/ext/AwkwardPythonCallExt/README.md deleted file mode 100644 index 554bca3..0000000 --- a/ext/AwkwardPythonCallExt/README.md +++ /dev/null @@ -1,17 +0,0 @@ -[PythonCall](https://github.com/JuliaPy/PythonCall.jl) is currently configured to use the Julia-specific Python distribution -installed by the [CondaPkg.jl](https://github.com/JuliaPy/CondaPkg.jl) package. - -```julia -using CondaPkg -CondaPkg.add("numpy") -CondaPkg.add("awkward") -``` - -```julia -using PythonCall - -const ak = pyimport("awkward") - -println(ak.__version__) -2.5.0 -```