Skip to content

basic_usage.rst

Latest commit

 

History

History
181 lines (148 loc) · 5.14 KB

basic_usage.rst

File metadata and controls

181 lines (148 loc) · 5.14 KB

Basic Usage

Create a hierarchy

#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"

int main ()
{
    // create a hierarchy on the local file system
    xt::xzarr_file_system_store store("test.zr3");
    auto h = xt::create_zarr_hierarchy(store);
}

Open a hierarchy

#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"

int main ()
{
    // open a hierarchy
    xt::xzarr_file_system_store store("test.zr3");
    auto h = xt::get_zarr_hierarchy(store);
}

Create an array

#include <vector>
#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"
#include "xtensor-io/xio_binary.hpp"

int main ()
{
    // open a hierarchy
    xt::xzarr_file_system_store store("test.zr3");
    auto h = xt::get_zarr_hierarchy(store);
    // create an array in the hierarchy
    nlohmann::json attrs = {{"question", "life"}, {"answer", 42}};
    std::vector<size_t> shape = {4, 4};
    std::vector<size_t> chunk_shape = {2, 2};
    // specify options
    xt::xzarr_create_array_options<xt::xio_gzip_config> o;
    o.chunk_memory_layout = 'C';
    o.chunk_separator = '/';
    o.attrs = attrs;
    o.chunk_pool_size = 10;
    o.fill_value = 0.0;

    xt::zarray z = h.create_array(
        "/arthur/dent",  // path to the array in the store
        shape,  // array shape
        chunk_shape,  // chunk shape
        "<f8",  // data type, here little-endian 64-bit floating point
        o // options
    );
    // write array data
    auto a = z.get_array<double>();
    a(2, 1) = 3.;
}

Access an array

#include <iostream>
#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"

int main ()
{
    // open a hierarchy
    xt::xzarr_file_system_store store("test.zr3");
    auto h = xt::get_zarr_hierarchy(store);
    // access an array in the hierarchy
    xt::zarray a = h.get_array("/arthur/dent");
    // read array data
    std::cout << a(2, 1) << std::endl;
    // prints `3.`
    std::cout << a(2, 2) << std::endl;
    // prints `0.` (fill value)
    std::cout << a.attrs() << std::endl;
    // prints `{"answer":42,"question":"life"}`
}

Create a group

#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"

int main ()
{
    xt::xzarr_file_system_store store("test.zr3");
    auto h = get_zarr_hierarchy(store);
    nlohmann::json attrs = {{"heart", "gold"}, {"improbability", "infinite"}};
    // create a group
    auto g = h.create_group("/tricia/mcmillan", attrs);
}

Explore the hierarchy

#include <iostream>
#include "xtensor-zarr/xzarr_hierarchy.hpp"
#include "xtensor-zarr/xzarr_file_system_store.hpp"

int main ()
{
    xt::xzarr_file_system_store store("test.zr3");
    auto h = get_zarr_hierarchy(store);
    // get children at a point in the hierarchy
    std::string children = h.get_children("/").dump();
    std::cout << children << std::endl;
    // prints `{"arthur":"implicit_group","marvin":"explicit_group","tricia":"implicit_group"}`
    // view the whole hierarchy
    std::string nodes = h.get_nodes().dump();
    std::cout << nodes << std::endl;
    // prints `{"arthur":"implicit_group","arthur/dent":"array","tricia":"implicit_group","tricia/mcmillan":"explicit_group"}`
}

Use cloud storage

#include <iostream>
#include "xtensor-zarr/xzarr_gcs_store.hpp"

int main ()
{
    // create an anonymous Google Cloud Storage client
    gcs::Client client((gcs::ClientOptions(gcs::oauth2::CreateAnonymousCredentials())));
    xzarr_gcs_store s1("zarr-demo/v3/test.zr3", client);
    // list keys under prefix
    auto keys1 = s1.list_prefix("data/root/arthur/dent/");
    for (const auto& key: keys1)
    {
        std::cout << key << std::endl;
    }
    // prints:
    // data/root/arthur/dent/c0/0
    // data/root/arthur/dent/c0/1
    // data/root/arthur/dent/c1/0
    // data/root/arthur/dent/c1/1
    // data/root/arthur/dent/c2/0
    // data/root/arthur/dent/c2/1

    xzarr_gcs_store s2("zarr-demo/v3/test.zr3/meta/root/marvin", client);
    // list all keys
    auto keys2 = s2.list();
    for (const auto& key: keys2)
    {
        std::cout << key << std::endl;
    }
    // prints:
    // android.array.json
    // paranoid.group.json
}